Ir al contenido principal

🚗 Creación de un envío

A
Escrito por Axel Candia
Actualizado hoy

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

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",
         "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.

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"

¿Ha quedado contestada tu pregunta?