🚗 3 - Creación de un envío

Una vez obtenida la cotización, podés crear un envío en Moova realizando un HTTP POST al siguiente endpoint:

https://api-dev.moova.io/b2b/shippings?appId=TU_APP_ID

Headers requeridos

Authorization: TU_APP_KEY

⚠️ appId se pasa por query string y appKey como header Authorization.

Tipos de envío (`type`)

Tipo	Descripción
`regular`	Envío estándar. Se realiza el mismo día si pasa a READY antes de la hora corte; si no, se entrega al día siguiente.
`minutes_90`	Envío urgente a realizarse dentro de las 2-3 horas. Requiere `flow: automatic` y aprobación previa.
`next_day`	El paquete se recoge y se lleva al warehouse de Moova, donde pasa la noche. Se entrega al cliente final al día siguiente.
`pickup`	Usado por Moova para retirar paquetes y llevarlos al depósito. No usar sin coordinación previa.
`food`	Envíos de comida o bebida. Requiere `flow: automatic`.
`mercado_flex`	Envío para integraciones con Mercado Libre Flex. Incluye escaneo obligatorio por parte del Moover.
`return`	Consolidación de múltiples envíos de tipo reversa en el depósito de Moova para luego enviarlos al warehouse del seller (similar a un `pickup`, pero inverso).
`reverse`	Envío singular desde el cliente final al depósito de Moova (warehouse), generalmente por devolución.
`store_pickup`	Envío con destino a una sucursal del seller para que el cliente final lo retire allí.

Flujos (`flow`)

Flujo	Descripción
`manual`	El envío no se retira hasta que lo pases manualmente a estado `READY`. Ideal para generar etiquetas anticipadas.
`semi-automatic`	El envío se crea directamente en estado `READY`. Se retira ese mismo día si está antes de hora corte.
`automatic`	Solo para `minutes_90` o `food`. El sistema asigna un mensajero de forma automática. Requiere coordinación previa.
`warehouse`	Aplica para pedidos consolidados en el depósito de Moova. Coordinar previamente con el equipo de ventas.

Campos principales del payload

Campo	Tipo	Descripción	Obligatorio
`type`	String	Tipo de envío: `regular`, `next_day`, `minutes_90`, `pickup`, etc.	✔️
`flow`	String	Flujo: `manual`, `semi-automatic`, `automatic`, `warehouse`	✔️
`internalOrderId`	String	Referencia interna del envío	✔️
`from`	Object	Datos del remitente (ver más abajo)	✔️
`to`	Object	Datos del destinatario (ver más abajo)	✔️
`items`	Array	Bultos incluidos en el envío (no confundir con `packagesCount`)	✔️
`scheduledDate`	String	Fecha/hora en la que el envío pasa automáticamente a estado READY (UTC)	Opcional
`deliveryTimeRange`	String	Rango horario preferido: `AM` o `PM` (requiere `scheduledDate` > hoy)	Opcional
`packagesCount`	Integer	Cantidad de paquetes (para etiquetas, no es igual a items)	Opcional
`currency`	String	Moneda ISO 4217 (ej. `ars`)	Opcional
`description`	String	Descripción visible para el repartidor	Opcional
`internalCode`	String	Código interno del envío. Si el cliente tiene etiquetas propias, este valor se usará para identificarlas. Se detalla más en la sección "Obtener etiquetas".	Opcional
`comments`	String	Comentario general sobre el envío	Opcional
`extra`	Object	Objeto con información adicional personalizada	Opcional
`settings`	Array	Lista de IDs de configuraciones especiales (ver /shipping-setting-options)	Opcional
`conf`	Object	Info adicional del objeto enviado (item, assurance)	Opcional

`from` y `to`: estructuras flexibles

Se prioriza en este orden: googlePlaceId > coordenadas (lat y lng) > address > street + number.
No enviar todos los formatos juntos.
En contact siempre incluir nombre, teléfono y email si están disponibles.
En to.message podés dejar un mensaje especial para ese destino.

Ejemplos de uso de `to`

1. Con address

"to": { "address": "Av. Callao 1234, CABA,Buenos Aires, Argentina" }

2. Con street y number:

"to": { "street": "Av. Callao", "number": "1234", "floor": "3", "apartment": "B", "city": "CABA", "state": "Buenos Aires", "postalCode": "1023", "country": "AR" }

3. Con coordenadas:

"to": { "coords":{"lat": -34.603722, "lng": -58.381592}, "addressDescription":"Av. Callao 1234, CABA,Buenos Aires, Argentina" }

4. Con Google Place ID:

"to": { "placeId": "ChIJJ3SpfQsLlVQRkYXR9ua5Nhw" }

Ejemplo básico

{
   "type":"regular",
   "flow":"manual",
   "internalOrderId":"pedido-1234",
   "from":{
      "address":"Av. Santa Fe 1234",
      "city":"CABA",
      "state":"Buenos Aires",
      "postalCode":"1425",
      "country":"AR",
      "contact":{
         "name":"Juan",
         "phone":"+541112345678",
         "email":"[email protected]"
      }
   },
   "to":{
      "address":"Av. Corrientes 3000",
      "city":"CABA",
      "state":"Buenos Aires",
      "postalCode":"1199",
      "country":"AR",
      "contact":{
         "name":"Maria",
         "phone":"+541199876543",
         "email":"[email protected]"
      },
      "instructions":"Entregar en conserjería"
   },
   "items":[
      {
         "type":"box",
         "quantity":1,
         "weight":1500,
         "length":30,
         "width":20,
         "height":15
      }
   ],
   "description":"Kit promocional",
   "packagesCount":1,
   "scheduledDate":"2025-06-01 15:00:00", 
   "currency":"ars",
   "internalCode":"LABEL-XYZ-987"
}

Errores comunes

404 - `Budget not found`

El área de origen o destino no está dentro de la tarifa configurada.
El tamaño o peso de los items supera lo permitido.

En testing: enviar email a [email protected] con origen, destino y tipo de envío.
En producción: contactar a tu comercial.

`addressErrors` en la respuesta

Si hay problemas con las direcciones, el campo addressErrors se devuelve en el response. Ejemplo:

"addressErrors": { "from": { "suggestions": null } }

Si aparece from o to, indica cuál de las direcciones tiene error.
Si suggestions es null, no se pudo obtener una sugerencia válida.
Si addressErrors es null, la dirección fue interpretada correctamente.

💡 Consejo: Usar Place ID o validar previamente con la API de cotización puede ayudar a evitar errores.

Próximo paso:

Para ver configuraciones especiales como logística inversa, validaciones, flex o food, consultá la sección:
"13. Envíos especiales: settings, ida y vuelta, cobros y más"

🚗 3 - Creación de un envío

Una vez obtenida la cotización, podés crear un envío en Moova realizando un HTTP POST al siguiente endpoint:

Headers requeridos

Tipos de envío (type)

Flujos (flow)

Campos principales del payload

from y to: estructuras flexibles

Ejemplos de uso de to