🚗 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. Se crean automaticamente en el estado `READYATSTORE`. Si se prefiere notificar cuando el pedido esté listo para pickeo, se puede enviar `settings:[10]` y actualizar el estado manualmente. Ver Creacion de envios especiales y Cambios de estado

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
services	Array	Lista de servicios extras que se requieren.	Opcional
delivery	Object	Validaciones para la entrega. (Codigo de seguridad)	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, 1425 CABA, Buenos Aires, Argentina",
      "postalCode":"1425", 
      "contact":{
         "name":"Juan",
         "phone":"+541112345678",
         "email":"[email protected]"
      }
   },
   "to":{
      "street":"Av. Corrientes",
      "number":300,
      "city":"CABA",
      "state":"Buenos Aires",
      "postalCode":"1199",
      "country":"AR",
      "contact":{
         "firstName":"Maria",
         "lastName":"Gonzalez",
         "phone":"+541199876543",
         "email":"[email protected]"
      },
      "instructions":"Entregar en conserjería"
   },
   "items":[
      {
         "type":"box",
         "description":"RELOJ PARA HOMBRE",
         "referenceCode":"88667859432832",
         "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"
}

Response

{
    "id": "6c7f76d0-7f67-11f0-b5d0-e1aa5ea0996c",
    "shortId": "6c7f76d0",
    "companyId": 1,
    "courierCompanyId": null,
    "packagesCount": 1,
    "scheduledDate": null,
    "deliveryTimeRange": null,
    "type": "regular",
    "size": "M",
    "priceFormatted": "$ 220.000,02",
    "price": 220000.02,
    "currency": "ARS",
    "from": {
        "placeId": 97425,
        "googlePlaceId": "ChIJfzoxtbnKvJUR2O-zSUSNVlY",
        "address": "Av. Sta. Fe 1234, C1059ABT Cdad. Autónoma de Buenos Aires, Argentina",
        "addressExtra": null,
        "contact": "Marcos Detry",
        "email": "[email protected]",
        "phone": "+541112345678",
        "instructions": null,
        "coords": {
            "lat": -34.5959117,
            "lng": -58.3846907
        }
    },
    "to": {
        "placeId": 98971,
        "googlePlaceId": "ChIJY8jbyTI1o5URmVJmCu1e1TQ",
        "address": "Av. Corrientes 300, C1043AAR Cdad. Autónoma de Buenos Aires, Argentina",
        "addressExtra": null,
        "contact": "Maria Gonzalez",
        "email": "[email protected]",
        "phone": "+541199876543",
        "instructions": "Entregar en conserjería",
        "coords": {
            "lat": -34.6031762,
            "lng": -58.3712136
        }
    },
    "status": "DRAFT",
    "secretCode": "5033",
    "internalCode": "LABEL-XYZ-987",
    "internalOrderId": "pedido-1234",
    "internalExtraId": null,
    "description": "Kit promocional",
    "hash": "cc94742d949a6c2f04a9d05b1befee39bef7bcfed0bebb38e8eaa4f38d4818a5",
    "message": null,
    "extra": null,
    "conf": null,
    "deliveryInfo": {
        "courier": null,
        "lat": null,
        "lng": null,
        "receiver": {
            "firstName": null,
            "lastName": null,
            "scannedInfo": null
        }
    },
    "statusHistory": [
        {
            "status": "DRAFT",
            "details": null,
            "createdAt": "2025-08-22 14:51:02"
        }
    ],
    "activeSettings": [
        {
            "id": 3,
            "name": "SignaturePhoto",
            "apply_to_all": 1,
            "description": "Instead of ask for a signature, take a picture of the package.",
            "message": "Debido al coronavirus, en vez de solicitar la firma, por favor sacale una foto a la puerta del domicilio donde estás haciendo la entrega.",
            "created_at": "2021-01-05 19:01:27",
            "updated_at": "2021-01-05 19:01:27",
            "deleted_at": null,
            "laravel_through_key": "6c7f76d0-7f67-11f0-b5d0-e1aa5ea0996c"
        },
        {
            "id": 4,
            "name": "DeliveryUserIdentification",
            "apply_to_all": 1,
            "description": "Request user identification when shipping is delivered",
            "message": "Documento de identidad",
            "created_at": "2021-01-05 19:01:27",
            "updated_at": "2021-01-05 19:01:27",
            "deleted_at": null,
            "laravel_through_key": "6c7f76d0-7f67-11f0-b5d0-e1aa5ea0996c"
        }
    ],
    "services": [],
    "relatedShippings": {
        "previous": null,
        "next": null
    },
    "items": [
        {
            "description": "",
            "referenceCode": null,
            "serialNumber": null,
            "weight": 1500,
            "length": 30,
            "width": 20,
            "height": 15,
            "quantity": 1,
            "meta": null
        }
    ],
    "createdAt": "2025-08-22 14:51:02",
    "addressErrors": null
}

Información importante del response:

"id": Es el valor único de identificación del envío dentro de Moova.

Luego tenemos los campos "placeId" dentro del "from" y del "to" lo que indica este valor numérico es que se encontró la dirección. En el caso de que el campo devuelva un "null" indica que se creó el envío pero con error de dirección y para corregirlo deben ingresar al dashboard como indica la siguiente documentación.

Services

Nombre	Descripción
cash_on_delivery	Se cobra en el lugar de la entrega el producto.
seguros	Se añade un seguro al envío por el valor declarado.

En ambos casos se debe verificar si es valido para tu país con un asesor de ventas.

En el caso de serlo en el payload de creación se debe agregar lo siguiente:

"services": [ 
             "cash_on_delivery" 
            ],
"chargeAmount": "25.00"

En el caso de usar los dos Services se puede agregar uno detras del otro ejemplo: ["cash_on_delivery" , "seguros"].

Codigo de Seguridad en la Entrega

Descripción

Permite configurar un código de verificación que el destinatario debe presentar al momento de recibir su envío. Esto agrega una capa de seguridad adicional para confirmar la identidad del receptor.

Cómo funciona

Al crear o actualizar un envío, podés incluir dentro del objeto delivery un array validations con las reglas de verificación. El repartidor verá el message en su app y deberá confirmar que el código ingresado por el destinatario coincide con el code configurado.

Campos del objeto `validation`

Campo	Tipo	Requerido	Descripción
`option`	`string`	✔️	Identificador del tipo de validación. Ej: `"DNI"`, `"PIN"`, `"CODE"`
`code`	`string[]`	✔️	Array con los valores válidos aceptados
`message`	`string`	✔️	Mensaje que verá el repartidor indicando qué pedirle al destinatario

Payload a ingresar:

"delivery":{
   "validations":[
      {
         "option":"DNI",
         "code":[
            "222"
         ],
         "message":"Por favor pida los ultimos 3 numeros del DNI"
      }
   ]
}

Validación Estricta de Código Postal (`postalCodeStrict`)

Descripción

Para evitar "falsos positivos" en la geolocalización (direcciones que existen en otras ciudades o provincias con nombres similares), puedes activar la validación estricta.

Al habilitar esta opción, el sistema realiza una comparación obligatoria entre el Código Postal ingresado y el Código Postal obtenido por el geolocalizador.

Funcionamiento

Si coinciden: El envío se crea y geolocaliza normalmente.
Si NO coinciden: El envío se crea, pero se marca con un error crítico de dirección (visualizado en rojo en el dashboard). Esto permite que el equipo de operaciones revise la dirección manualmente antes de despachar el paquete.

Parámetros de Configuración

Campo	Tipo	Valor por defecto	Descripción
`postalCodeStrict`	`boolean`	`false`	Si es `true`, activa la comparación estricta entre el CP enviado y el CP detectado por coordenadas.

Ejemplo de Implementación en el Payload

Debes incluir el campo en la raíz del objeto de creación del envío o dentro de las opciones de configuración:

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

Errores comunes

404 - `Not found` : `No se encontró un presupuesto`

Causas Posibles

Falta de Tarifas Configuradas: No existen tarifas cargadas en el sistema para la ruta especificada (origen y destino). El sistema no puede calcular un costo si no tiene una tarifa base para ese trayecto.

Datos de Dirección Inválidos: Las direcciones de origen y/o destino son imprecisas, ambiguas o contienen errores. Esto provoca que el sistema no pueda geolocalizar los puntos de manera correcta y, por lo tanto, no encuentra una ruta válida para cotizar.

Pasos para la Solución

Verificar la Configuración de Tarifas: Contacte al equipo Comercial para confirmar que las tarifas para la ruta solicitada (Punto A → Punto B) están activas y correctamente configuradas en el sistema.

Validar las Direcciones de Entrada: Implemente una validación para asegurar que los datos de dirección proporcionados por el usuario final sean precisos antes de enviarlos a la API.

Recomendación: Utilice una herramienta externa como Google Maps para verificar y normalizar las direcciones. Esto reduce la probabilidad de enviar datos que el sistema no pueda interpretar.

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"

🚗 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

Ejemplo básico

Response

Información importante del response:

Services

Codigo de Seguridad en la Entrega

Descripción

Cómo funciona

Campos del objeto validation

Validación Estricta de Código Postal (postalCodeStrict)

Descripción

Funcionamiento

Parámetros de Configuración

Ejemplo de Implementación en el Payload

Errores comunes

404 - Not found : No se encontró un presupuesto

404 - Budget not found

addressErrors en la respuesta

Tipos de envío (`type`)

Flujos (`flow`)

`from` y `to`: estructuras flexibles

Ejemplos de uso de `to`

Campos del objeto `validation`

Validación Estricta de Código Postal (`postalCodeStrict`)

404 - `Not found` : `No se encontró un presupuesto`

404 - `Budget not found`

`addressErrors` en la respuesta