Crear una expedición

Crea una nueva expedición (servicio) en GRIP. Es el endpoint principal para dar de alta entregas o recogidas desde tu sistema.

POST https://api.app.vonzu.es/api/v2/services/create

Cabeceras

secret-api-key: TU_API_KEY
Authorization-Domain: TU_DOMINIO
Content-Type: application/json

Estructura del cuerpo

Todo el contenido de la expedición se envía dentro de un objeto create:

{
  "create": {
    "type": "delivery",
    "reference": "MI-REFERENCIA-001",
    "address": { ... },
    "origin": { ... },
    "contact": { ... },
    "schedules": [ ... ],
    "...": "resto de campos"
  }
}

Campos principales

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	Tipo de servicio. `delivery` (entrega) o `pickup` (recogida).
`reference`	string	Recomendado	Referencia única que asignás a la expedición. Se usa para localizarla después.
`isReturn`	boolean	No	Indica si es una expedición de retorno.
`address`	object	Sí	Dirección de destino de la expedición. Ver más abajo.
`origin`	object	No	Dirección de origen/recogida. Misma estructura que `address`.
`contact`	object	Sí	Datos de contacto del destinatario.
`schedules`	array	No	Franjas horarias en las que se puede realizar el servicio.
`barcodes`	array de string	No	Códigos de barras asociados a los bultos.
`description`	string	No	Descripción libre de la expedición.
`comments`	string	No	Comentarios o instrucciones para el conductor.
`date`	string (`YYYY-MM-DD`)	No	Fecha prevista del servicio.
`packageCount`	number	No	Número de bultos.
`status`	object	No	Estado inicial, con un campo `code` (por ejemplo `created`).
`reimbursement`	number	No	Importe de reembolso a cobrar en la entrega.
`weight`	number	No	Peso total (kg).
`volume`	number	No	Volumen total.
`payer`	string	No	Nombre de quien paga el servicio.
`channel`	string	No	Canal de origen (por ejemplo `online`).
`dedicationTime`	number	No	Tiempo de dedicación estimado (minutos).
`removals`	number	No	Número de retiradas/recogidas asociadas.
`insuredValue`	number	No	Valor asegurado de la mercancía.
`skills`	array de string	No	Habilidades o requisitos que debe cumplir el conductor (por ejemplo `frio`, `calor`).
`extraFields`	object	No	Campos adicionales personalizados (clave/valor), como un `externalCode`.

Objeto address / origin

Campo	Tipo	Obligatorio	Descripción
`street`	string	Sí	Calle y número.
`streetExtra`	string	No	Información adicional (piso, puerta, referencia).
`postalCode`	string	Sí	Código postal.
`city`	string	Sí	Población.
`province`	string	No	Provincia.
`country`	string	Sí	País.
`geometry`	object	No	Punto geográfico en formato GeoJSON. Si no se envía, GRIP intenta geocodificar la dirección.

El objeto geometry tiene la forma:

"geometry": {
  "type": "Point",
  "coordinates": [-120.883923, 80.39382]
}

Las coordenadas van en orden [longitud, latitud] (GeoJSON).

Objeto contact

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del contacto.
`nif`	string	No	Documento de identidad / NIF.
`emails`	array de string	No	Correos de contacto.
`phones`	array de string	No	Teléfonos de contacto.

Objeto schedules

Es un array de franjas horarias, donde cada franja es un par [hora_inicio, hora_fin] en formato HH:MM:SS:

"schedules": [
  ["00:30:00", "01:45:00"]
]

Ejemplo de petición

{
  "create": {
    "type": "delivery",
    "isReturn": true,
    "address": {
      "street": "C/ CALDERILLA NUM 1CC ISLA AZUL L-051",
      "postalCode": "28054",
      "city": "MADRID",
      "province": "MADRID",
      "country": "España",
      "streetExtra": "local al lado de la papelería",
      "geometry": {
        "type": "Point",
        "coordinates": [-120.883923, 80.39382]
      }
    },
    "origin": {
      "street": "Avenida Diagonal 33",
      "postalCode": "08976",
      "city": "Barcelona",
      "province": "Barcelona",
      "country": "España",
      "geometry": {
        "type": "Point",
        "coordinates": [-120.883923, 80.39382]
      }
    },
    "schedules": [
      ["00:30:00", "01:45:00"]
    ],
    "contact": {
      "name": "Oscar",
      "nif": "4578475X",
      "emails": ["oscar@yahoo.es"],
      "phones": ["764783876"]
    },
    "reference": "7783SD8DSJS",
    "barcodes": ["2342232", "56534"],
    "description": "Paquete voluminoso",
    "comments": "Montaje a pie de calle",
    "date": "2023-07-05",
    "packageCount": 2,
    "status": { "code": "created" },
    "reimbursement": 0,
    "weight": 20,
    "volume": 10,
    "payer": "Juan Luis",
    "channel": "online",
    "dedicationTime": 10,
    "removals": 2,
    "insuredValue": 20,
    "skills": ["frio", "calor"],
    "extraFields": {
      "externalCode": "123456789",
      "key": "value"
    }
  }
}

Ejemplo de respuesta

La API devuelve la expedición creada, ya enriquecida con los identificadores internos y el estado de procesamiento:

{
  "channelId": "6377357af84db65a5dd2b7f1",
  "createdAt": "2022-12-05T16:35:17.222Z",
  "updatedAt": "2022-12-05T16:35:17.222Z",
  "type": "delivery",
  "id": 104367,
  "clientUsername": "maurocliente",
  "serviceGroupId": 0,
  "barcodes": ["..."],
  "creationStatus": "DRAFT",
  "date": "2022-12-05",
  "packageCount": 4,
  "packages": [
    {
      "barcode": "104367INTELLIGENT001",
      "id": "638e1dc5a98f395193ced6b3"
    }
  ],
  "status": { "code": "created" },
  "geocodingStatus": "queuedForService",
  "geocodingQuality": 0,
  "clientId": "635940f98d922a2d79fa0005",
  "serviceTypeCode": "SEGMENTOS",
  "basePrice": 0
}

Campos relevantes de la respuesta

Campo	Descripción
`id`	Identificador interno de la expedición en GRIP.
`createdAt` / `updatedAt`	Marcas de tiempo de creación y última actualización.
`creationStatus`	Estado de creación (por ejemplo `DRAFT`).
`packages`	Bultos generados, cada uno con su `barcode` e `id`.
`status.code`	Estado operativo de la expedición.
`geocodingStatus`	Estado del proceso de geocodificación de las direcciones.
`basePrice`	Precio base calculado para el servicio.

Nota: justo tras la creación, la expedición puede quedar en estado DRAFT y con la geocodificación en cola (queuedForService). Su estado se resuelve poco después de forma asíncrona.