En este artículo explicaremos los conceptos básicos de la integración con la API B2B de Moova y como realizarla.
Requisitos
Es necesarios tener estos requisitos cumplidos para poder avanzar en el desarrollo de la integración.
Haberse dado de alta en producción y en el entorno de testing. Si no lo hiciste aún ver las instrucciones aquí.
Tener el APP ID y la KEY de Testing y Producción para poder realizar las pruebas.
La documentación formal de la API la encontrarás en swagger aquí
Índice de contenidos de ejemplo de como se interactúa con la API de Moova
TABLE OF CONTENTS
- Requisitos
- Índice de contenidos de ejemplo de como se interactúa con la API de Moova
- Introducción
- Estados en la vida de un envío
- Creación de un Envío
- Headers:
- Query:
- Campos:
- Ejemplo de payload mas habitual
- Ejemplo de payload con la dirección en una sola linea
- Ejemplo de payload donde envío a dirección a través de un Google Place ID y también ejemplo de settings.
- Ejemplo de payload con coordenadas en lugar de direcciones
- Ejemplo de payload con pedido de Escaneo de nro de serie.
- Ejemplo de payload para un envío para dentro de 2 días que debe entregarse durante la mañana.
- Ejemplo de payload especificando la cantidad de bultos en un shipping.
- Ejemplo de payload de un pedido ida y vuelta
- Ejemplo de setting para exigir que solo se entregue a la persona que figura como destinatario (OnlyDeliverToAddressee)
- Ejemplo de setting para exigir que solo se escanee la mancha del DNI Argentino (ScanReiceiverId)
- Ejemplo para exigir que el moover le exiga al usuario final un código para realizar la entrega
- Error messages
- Información sobre depósitos
- Cotización de un shippings
- Actualización de un shippings
- Cambio de estado de un shipping
- Como pedir información sobre un shipping por API
- Cargar un envio de Mercado libre en Moova
- Como enviar a un usuario final una URL para su seguimiento
- Como imprimir una etiqueta de un shipping por API
- Definición de settings en un envío.
Introducción
La solución de integración de Moova, permitirá automatizar el pedido de logística de última milla.
A través de la integración se podrá requerir cotizaciones, crear envíos, anular envíos y se recibirán eventos (mediante webhooks) o se requerirá la información sobre el estado de los mismos.
Para facilitar el testing de la integración hemos creado una plataforma donde se podrán ver los pedidos creados por API y generar todos los eventos posibles de manera de poder comprobar las respuestas de los endpoints.
Estados en la vida de un envío
Para conocer todo el flujo de los estados de un envio, podes leer mas en este articulo: Estados de vida de un envio
Creación de un Envío
La documentación de la API la encontrarás en swagger aquí. Este es un documento que explica casos de uso para un mejor entendimiento sobre como utilizar la api.
Headers:
Authorization: Key( ID de aplicación provisto)
Query:
appId: ID de aplicación provisto
Campos:
scheduledDate: null o fecha (UTC) en la que se debe realizar el envío cuando el envío se tiene que realizar en una fecha exacta en el futuro. Únicamente poner la fecha en caso que tenga un día determinado. En general debiera ser null o simplemente no estar en el payload, lo que significa que se procesará cuando entre en el sistema. En caso de ser tener una fecha el formato debiera ser: "2023-02-20". Asegurarse que han acordado con la parte comencial para hacer envíos en fechas especificas a futuro
deliveryTimeRange: En este campo permite definir el rango horario en que se quiere realizar el envío. Las opciones son "AM" o "PM". Para que este parámetro sea tenido en cuenta, scheduledDate tiene que tener una fecha mayor al día donde se está creando el envío. Este paramentro sirve para envío que serán realizados en el futuro no para envíos sameday.
packagesCount: valor numérico que especifica la cantidad de bultos que contiene el envío. Cuando se pidan etiquetas se imprimiran tantas etiquetas para este envío como cantidad de paquetes haya. OJO: no confundir con los items de un envío. Por ejemplo un envío puede tener 9 items (5 vasos y 4 platos) dentro de 2 cajas. Este valor de 2 cajas es el valor en packagesCount. Si es un solo paquete se puede omitir directamente en el payload.
type : tipo de envío. Pueden ser :
regular: Envío que se debiera utilizar normalmente.minutes_90: Envío que se necesite hacer en 2-3 horas desde que sube al sistema o desde un horario especifico en el futuro por ejemplo (mañana a las 10 Am). Si un envío es del tipominutes_90debe ir con el parámetro flow:automatic. El tipo de envíominutes_90tiene un costo mas elevado que elregular.mercado_flex: para envíos del tipo Mercado Libre Flex.Existen otros tipos de envíos que tienen una operatoria muy especial como
pickup: Este último únicamente debiera utilizarse luego de haber confirmado con Moova el uso que se le va a dar.food: Envío de comida o bebida que requiere un tiempo rápido de resolución y que el moover disponga de una mochila térmica para su traslado. Este envío suele ir con el parámetro flow:automatic
flow:
manual Este es el flow normal de un envío. Este envío no se irá a buscar hasta que se pase al estado READY. Se puede crear este envío para generar etiquetas y luego cuando esté listo el paquete entonces pasarlo a READY. (recien en ready un operador de moova lo irá a buscar). Otro ejemplo típico de este uso es para una empresa que tiene muchos envíos y que luego juntan todos los envíos que están draft y se envían o buscan para llevarlos a un deposito de moova. Cuando llegue al deposito Moova los pasará al estado READY y se realizará el envío.
Si no se van a entregar todos los envios en deposito Moova, tener en cuenta que flow ‘manual’ pone el estado en DRAFT y que el envío no sera pasado a buscar hasta que lo pases a READY. Mas información de esto mas adelante.
semi-automatic Es flow crea un envío y deja el envío en moova en estado READY para que los operadores de moova coordinen con los mensajeros la búsqueda de los mismos.
automatic Utilizar este tipo de flow cuando se está realizando un envío del tipo minutes_90 o food. En envío entrará al sistema de manera automática y buscará un mensajero de manera automática para realizarlo de manera inmediata. Solo utilizar este tipo de flow antes coordinandolo con Moova.
Use el tipo de envio ‘manual’ si necesita tiempo para procesar el envio. Ejemplo, tiene que esperar a comprobar stock. Use ‘automatico’ si quiere que el envio se asigne tan pronto como fue creado
warehouse Utilizar este flow para los casos en que haya un acuerdo comercial en el cual Moova realiza un pickup 1 o mas veces por día para que esta mercadería vaya a los depósitos de moova para luego ser re-distribuida.
currency: string de 3 letras que define el tipo de moneda según el ISO 4217. Ejemplo: ars para Argentina.
from: objeto con los datos de la dirección. Si “googlePlaceId” es null, se deben completar el resto de los valores de la dirección. Si se envía el “googlePlaceId” se deberá completar además “floor" y “apartment”. En contact, va la persona de contacto en caso que tengamos alguna duda sobre este envio.
to: objeto con los datos de la dirección. Si “googlePlaceId” es null, se deben completar el resto de los valores de la dirección. Si se envía el “googlePlaceId” se deberá completar además “floor" y “apartment”. En contact, va la persona de a quien se le va a entregar el envío. En caso de tener el teléfono es muy importante que se incluya dado que ayudará a que la entrega sea mas rápida y efectiva.
to.message: mensaje particular para dejar en ese destino (no es lo mismo que las instrucciones para la dirección).
internalCode: código interno de la empresa que pide el envío para este envío. En caso de ingresarlo los operadores podrán ubicar en búsquedas este envío por su código interno.
comments: comentario general sobre el envío.
extra: objeto con cualquier valor extra que se quiera agregar.
settings: los settings son características especiales de un shipping en particular. Lo normal es que NO haya ningún setting. Hay un endpoint para ver los setting disponibles: /shipping-setting-options
{
"id":1,
"name":"PickupSignature",
"description":"Requiere firma en el pickup",
},
{
"id":2,
"name":"PickupPhoto",
"description":"Requiere foto en el pickup",
}El caso de uso mas habitual utilizar los settings (1 y 2) es en la logística inversa donde se quiere tener firma y foto del pickup.
conf: información sobre el paquete que se va a transportar.
conf.assurace: relativo al seguro. Por el momento ponerlo en null. No implementado por el momento.
conf.item : información sobre el precio, peso (gramos), largo (cm), ancho(cm) y alto del objeto(cm). En caso de no tener el dato poner null.
Ejemplo de payload mas habitual
{
"currency": "ARS",
"type": "regular",
"flow": "manual",
"from": {
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "xxxxxx@gmail.com",
"phone": "+54 9 11 6576 3432"
}
},
"to": {
"street": "Blas Parera",
"number": "51",
"floor": "7to",
"apartment": "C",
"city": "Florida",
"state": "Buenos Aires",
"postalCode": "B1602",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": "+54 11 7658 3443"
},
"message": ""
},
"internalCode": "XX475738YY",
"extra": {},
"conf": {
"assurance": false
},
"items": [
{
"description": "Tarjeta",
"referenceCode": "18-X0-99",
"serialNumber": null,
"price": 150,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
},
{
"description": "Libro X",
"price": 140,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
},
{
"description": "Auriculares",
"price": 140,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
]
}Response
{
"id": "25debfd0-fd12-11ea-b375-87a079a4fb9e",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$329,86",
"price": "329.86",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "xxxxxx@gmail.com",
"phone": "+54 9 11 6576 3432",
"instructions": "No funciona el timbre. Llamar antes",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"to": {
"placeId": 56994,
"googlePlaceId": "ChIJg5OihcO2vJURAjUW8Qjjd0c",
"address": "Blas Parera 51, B1602 Florida, Provincia de Buenos Aires, Argentina",
"addressExtra": "7to C",
"contact": "Juan Perez",
"email": "",
"phone": "+54 11 7658 3443",
"instructions": "No funciona el timbre. Llamar antes",
"coords": {
"lat": "-34.54533850",
"lng": "-58.49378440"
}
},
"status": "DRAFT",
"secretCode": "7062",
"internalCode": "XX475738YY",
"internalOrderId": null,
"description": null,
"hash": "6a7fd49208808962fbe1c4fe7525546aa9bd46745725f5c6fcd77ea0c20305e1",
"message": "",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DRAFT",
"details": null,
"createdAt": "2020-09-22 20:28:17"
}
],
"activeSettings": [
{
"id": 5,
"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 saca una foto al DNI de la persona que recibe el pedido",
"created_at": "2020-03-17 11:33:16",
"updated_at": "2020-03-17 11:33:16",
"deleted_at": null,
"laravel_through_key": "25debfd0-fd12-11ea-b375-87a079a4fb9e"
},
{
"id": 6,
"name": "DeliveryUserIdentification",
"apply_to_all": 1,
"description": "Request user identification when shipping is delivered",
"message": "Documento de identidad",
"created_at": "2020-03-17 11:33:16",
"updated_at": "2020-03-17 11:33:16",
"deleted_at": null,
"laravel_through_key": "25debfd0-fd12-11ea-b375-87a079a4fb9e"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"description": "Tarjeta",
"refenceCode": "18-X0-99",
"serialNumber": null,
"price": 150,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
},
{
"description": "Libro X",
"refenceCode": null,
"serialNumber": null,
"price": 140,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
},
{
"description": "Auriculares",
"refenceCode": null,
"serialNumber": null,
"price": 140,
"currency": "ARS",
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
],
"createdAt": "2020-09-22 20:28:17"
}Ejemplo de payload con la dirección en una sola linea
La dirección se pueden enviar en una sola linea en el campo address, pero es muy importante que el piso y/o departament vengan por separado en sus campos floor y apartment
Correcto : "address": "Vidal 1432, CABA, Argentina"
Incorrecto: "address": "Vidal 1432 4 Piso B, CABA, Argentina"
Correcto: "address": "Blas Parera 51, B1602 Florida, Provincia de Buenos Aires, Argentina" Incorrecto: "address": "Blas Parera 51, 7 Piso B, B1602 Florida, Provincia de Buenos Aires, Argentina"
{
"currency": "ARS",
"type": "regular",
"flow": "manual",
"from": {
"address": "Vidal 1432, CABA, Argentina",
"floor": "6to",
"apartment": "C",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "xxxxxx@gmail.com",
"phone": "+54 9 11 6576 3432"
}
},
"to": {
"street": "Blas Parera",
"number": "51",
"floor": "7to",
"apartment": "C",
"city": "Florida",
"state": "Buenos Aires",
"postalCode": "B1602",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "mdetry@gmail.com",
"phone": "+54 11 7658 3443"
},
"message": ""
},
"internalCode": "XX475738YY",
"extra": {},
"conf": {
"assurance": false
},
"items": [
{
"description": "iPhone",
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
]
}Response
{
"id": "e8d81630-e2fc-11ea-93b6-4f30710e95ea",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$ 193,88",
"price": "193.88",
"currency": "ARS",
"from": {
"placeId": 56596,
"googlePlaceId": "ChIJJ_OkZNq1vJURVabDMiYvaQU",
"address": "Vidal 1432, C1426AMA CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "xxxxxx@gmail.com",
"phone": "+54 9 11 6576 3432",
"instructions": "No funciona el timbre. Llamar antes",
"coords": {
"lat": "-34.56933510",
"lng": "-58.45482860"
}
},
"to": {
"placeId": 1980,
"googlePlaceId": "EjBCbGFzIFBhcmVyYSA1MSwgRmxvcmlkYSwgQnVlbm9zIEFpcmVzLCBBcmdlbnRpbmEiMBIuChQKEgnR77OAw7a8lRHZx32lt3aghxAzKhQKEgnJ3Dcf1rC8lRHpL69Ch_vv-w",
"address": "Blas Parera 51, Florida, Buenos Aires, Argentina",
"addressExtra": "7to C",
"contact": "Juan Perez",
"email": "mdetry@gmail.com",
"phone": "+54 11 7658 3443",
"instructions": "No funciona el timbre. Llamar antes",
"coords": {
"lat": "-34.54535620",
"lng": "-58.49378980"
}
},
"status": "DRAFT",
"secretCode": "1089",
"internalCode": "XX475738YY",
"internalOrderId": null,
"description": null,
"hash": "79c8682ad30725ea3fc2f69c73528e34ddfe2236ce5f8520cb1cba69cd9dc49d",
"message": "",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DRAFT",
"details": null,
"createdAt": "2020-08-20 15:50:45"
}
],
"activeSettings": [
{
"id": 5,
"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 saca una foto al DNI de la persona que recibe el pedido",
"created_at": "2020-03-17 11:33:16",
"updated_at": "2020-03-17 11:33:16",
"deleted_at": null,
"laravel_through_key": "e8d81630-e2fc-11ea-93b6-4f30710e95ea"
},
{
"id": 6,
"name": "DeliveryUserIdentification",
"apply_to_all": 1,
"description": "Request user identification when shipping is delivered",
"message": "Documento de identidad",
"created_at": "2020-03-17 11:33:16",
"updated_at": "2020-03-17 11:33:16",
"deleted_at": null,
"laravel_through_key": "e8d81630-e2fc-11ea-93b6-4f30710e95ea"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"description": "iPhone",
"referenceCode": null,
"serialNumber": null,
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
],
"createdAt": "2020-08-20 15:50:45"
}Ejemplo de payload donde envío a dirección a través de un Google Place ID y también ejemplo de settings.
{
"scheduledDate": "2021-02-20 15:00:00",
"currency": "ARS",
"type": "minutes_90",
"flow": "automatic",
"from": {
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": "+54 11 8786 1232"
},
"message": ""
},
"to": {
"googlePlaceId": null,
"street": "Avenida Córdoba",
"number": "1500",
"floor": "3to",
"apartment": "F",
"city": "CABA",
"state": "CABA",
"postalCode": "1055",
"country": "AR",
"instructions": "Entregar al Portero",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": "+54 11 6765 8765"
},
"message": ""
},
"internalCode": "X23454",
"description": "string",
"label": "string",
"extra": {},
"settings": [1, 2],
"conf": {
"assurance": false
},
"items": [
{
"description": "iPhone",
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
]
}Response
{
"id": "b9255870-6166-11ea-914b-ff471ce5170b",
"scheduledDate": "2021-02-20 15:00:00",
"type": "minutes_90",
"priceFormatted": "$ 200,00",
"price": 200,
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "+54 11 8786 1232",
"instructions": "No funciona el timbre. Llamar antes"
},
"to": {
"placeId": 258,
"googlePlaceId": "ChIJGTa0WcfKvJUReHvuhmo0zpE",
"address": "Av. Córdoba 1500, C1055AAR CABA, Argentina",
"addressExtra": "3to F",
"contact": "Juan Perez",
"email": "",
"phone": "+54 11 6765 8765",
"instructions": "Entregar al Portero"
},
"status": "WAITING",
"secretCode": "6975",
"internalCode": "X23454",
"internalOrderId": null,
"description": "string",
"hash": "eff81c0aaefe7a39e43e1c5ff52762eda533fd77aad5d743d3841b5ba1e90d0d",
"message": "",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "WAITING",
"details": null,
"createdAt": "2020-03-08 18:00:40"
}
],
"activeSettings": [
{
"id": 1,
"name": "PickupSignature",
"description": "In order to pick up this shipping the sender must provide a signature",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
},
{
"id": 2,
"name": "PickupPhoto",
"description": "In order to pick up this shipping is mandatory to take a picture of the package",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"description": "iPhone",
"referenceCode": null,
"serialNumber": null,
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
],
"createdAt": "2020-03-08 18:00:40"
}Ejemplo de payload con coordenadas en lugar de direcciones
En ocasiones hay zonas o calles que no son fácilmente detectadas por los servicios de direcciónes, en dicho caso se soporta la opción de enviar las coordenadas para identificar los puntos de origen y/o destino. En dicho caso ademas de las coordenadas deben enviarse una descripción de la dirección, la cual quedará adjunta a las indicaciones para el moover que realizará el envio.
{
"currency": "ARS",
"type":"regular",
"flow":"manual",
"from": {
"coords": {
"lat":-34.55943430,
"lng":-58.45851540
},
"addressDescription":"Av. Cabildo 2351",
"floor": "6to",
"apartment": "C",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "xxxxx@gmail.com",
"phone": "+54 9 11 6576 3432"
}
},
"to": {
"coords": {
"lat":-34.58267030,
"lng":-58.41209520
},
"addressDescription":"French 4351",
"floor": "6to",
"apartment": "C",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Antonio",
"lastName": "Prieto",
"email": "aprieto@mailcatch.com",
"phone":"4765-5213"
},
"message": "Es su cumpleaños"
},
"internalCode": "A4564",
"comments": "XX475738YY",
"extra": {},
"conf": {
"assurance": false
},
"items": [
{
"description": "iPhone",
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
]
}Response
{
"id": "0ca4d500-c609-11ea-aa08-a3105663f0ef",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$ 146,56",
"price": "146.56",
"currency": "ARS",
"from": {
"placeId": 2,
"googlePlaceId": "EiFBdi4gQ2FiaWxkbyAyMzUxLCBDQUJBLCBBcmdlbnRpbmEiMRIvChQKEgmvrIk2K7S8lRFSNGBPm1HSlxCvEioUChIJ9X8d7yy0vJURVSdwKFqas7E",
"address": "Av. Cabildo 2351, C1428AAF CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "xxxxx@gmail.com",
"phone": "+54 9 11 6576 3432",
"instructions": "Av. Cabildo 2351\nNo funciona el timbre. Llamar antes"
},
"to": {
"placeId": 1,
"googlePlaceId": "EhxGcmVuY2ggNDM1MSwgQ0FCQSwgQXJnZW50aW5hIjESLwoUChIJxZUInX61vJURnhyZgdEY_1IQ_yEqFAoSCQHOKOqcyryVEbWOcarIKUH1",
"address": "French 4351, C1425AXC CABA, Argentina",
"addressExtra": "6to C",
"contact": "Antonio Prieto",
"email": "aprieto@mailcatch.com",
"phone": "4765-5213",
"instructions": "French 4351\nNo funciona el timbre. Llamar antes"
},
"status": "DRAFT",
"secretCode": "3258",
"internalCode": "A4564",
"internalOrderId": null,
"description": null,
"hash": "b0235123ea75989f2b2ee7bf400ec0530f3df7bccea37256f5d937574a46fcd6",
"message": "Es su cumpleaños",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DRAFT",
"details": null,
"createdAt": "2020-07-14 19:34:35"
}
],
"activeSettings": [],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"description": "iPhone",
"referenceCode": null,
"serialNumber": null,
"price": 150,
"currency": "ARS",
"weight": 900,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
}
],
"createdAt": "2020-07-14 19:34:35"
}Donde
id : id del envío de moova de este pedido.
price : el costo del envío
from: los datos de la recogida del pedido.
to: los datos del destino del pedido.
status: el estado del pedido.
secretCode : código secreto de este envío que podrá ser utilizado por el receptor del envío para verificar la autenticidad del mismo con el mensajero.
hash: hash de este envío que será utilizado para visualizar y poder realizar cambios a este envío sin estar logeado a moova. Ejemplo: a) que el usuario verifique la dirección y en caso que no sea correcta que la pueda cambiar. B) enviar una URL al usuario para que pueda seguir el estado del envío.
Ejemplo de payload con pedido de Escaneo de nro de serie.
Este es un caso muy particular, donde el objetivo es que cuando el mensajero realice la entrega, escanee una etiqueta con el nro de serie del producto para que este se guarde y se pueda pedir luego con un GET del shipping.
Para pedir que se escanee el número de serie setear setting en 6.
"settings": [6]
OJO: todos los items en este envío se les va a pedir el numero de serie. En caso de haber varios item a entregar en un mismo domicilio, unos con necesidad de escanear número de serie y otros que no por favor generar dos envíos distintos separando los item que necesitan escanear el número de serie y los que no.
Aquí vemos un ejemplo de un payload completo para la creación del pedido con necesida de escaneo de número de serie.
{
"currency": "ARS",
"type": "regular",
"flow": "manual",
"from": {
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "Intruciones pickup",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": "Mensaje pickup"
},
"to": {
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "Instrucciones entrega",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": "Mensaje entrega"
},
"internalCode": "string",
"description": "Descripcion del item",
"label": "label del item",
"extra": {},
"settings": [
6
],
"conf": {
"assurance": false
},
"items": [
{
"description": "Tarjeta",
"price": 150,
"weight": 20,
"length": 20,
"width": 20,
"height": 20
},
{
"description": "Post Marca A",
"price": 140,
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1
},
{
"description": "Post Marca B",
"price": 140,
"weight": 20,
"length": 20,
"width": 20,
"height": 20,
"quantity": 2
}
]
}Y aquí la response de la creación del payload. Podemos verificar al final dentro de "activeSettings"
que el que tiene ID = 6 está presente que es el que necesitamos. Puede haber otros "activeSettings"
que no se pusieron el payload pero que el sistema agrega de manera automática.
"activeSettings": [
{
"id": 6,
"name": "UpdateDeliveredItems",
"apply_to_all": 0,
"description": "Once the shipping is delivered, update the delivered items",
"message": null,
"created_at": "2021-01-05 19:01:27",
"updated_at": "2021-01-05 19:01:27",
"deleted_at": null,
"laravel_through_key": "b07ae420-5456-11eb-848c-b95db72a2751"
}
]
Aquí la response del payload de creación completo.
{
"id": "b07ae420-5456-11eb-848c-b95db72a2751",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$100,00",
"price": "100.00",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Intruciones pickup",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"to": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Instrucciones entrega",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"status": "DRAFT",
"secretCode": "6063",
"internalCode": "string",
"internalOrderId": null,
"description": "Descripcion del item",
"hash": "15528bb4ff6cf51695390725a0e7bc24e483b5242ff7e50097ceca53abb272b6",
"message": "Mensaje entrega",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DRAFT",
"details": null,
"createdAt": "2021-01-11 21:48:06"
}
],
"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": "b07ae420-5456-11eb-848c-b95db72a2751"
},
{
"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": "b07ae420-5456-11eb-848c-b95db72a2751"
},
{
"id": 6,
"name": "UpdateDeliveredItems",
"apply_to_all": 0,
"description": "Once the shipping is delivered, update the delivered items",
"message": null,
"created_at": "2021-01-05 19:01:27",
"updated_at": "2021-01-05 19:01:27",
"deleted_at": null,
"laravel_through_key": "b07ae420-5456-11eb-848c-b95db72a2751"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"price": 150,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"description": "Tarjeta",
"referenceCode": null,
"serialNumber": null,
"quantity": 1
},
{
"price": 140,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"description": "Post Marca A",
"referenceCode": null,
"serialNumber": null,
"quantity": 1
},
{
"price": 140,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"quantity": 2,
"description": "Post Marca B",
"referenceCode": null,
"serialNumber": null,
}
],
"createdAt": "2021-01-11 21:48:06"
}Luego de que se haya entregado el producto y se haya escaneado el numero de serie se puede hacer un get del shipping y nos encontraremos con la informacion del shippping pero incluyendo el nro de serie.
{
"id": "b07ae420-5456-11eb-848c-b95db72a2751",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$100,00",
"price": "100.00",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Intruciones pickup",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"to": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Instrucciones entrega",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"status": "DELIVERED",
"secretCode": "6063",
"internalCode": "string",
"internalOrderId": null,
"description": "Descripcion del item",
"hash": "15528bb4ff6cf51695390725a0e7bc24e483b5242ff7e50097ceca53abb272b6",
"message": "Mensaje entrega",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": "Thomas Jefferson",
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DELIVERED",
"details": {
"receiverUid": "12369580",
"receiverPhone": "",
"courierPosition": {
"lat": "-34.59561000",
"lng": "-58.39461000"
},
"receiverTypeId": 0,
"receiverLastName": "",
"receiverSignature": "https://s3.amazonaws.com/develop.files.moova.io/404/w2LgxTbv6oHfRHH887v4QXSH0ia5C4TZT8FxKxtV.jpg",
"receiverFirstName": "Juan Perez",
"receiverAddressExtra": "6to C",
"receiverAddressNumber": "",
"receiverAddressStreet": "Av. Santa Fe 2678, C1425BGO CABA, Argentina"
},
"createdAt": "2021-01-12 10:55:46"
},
{
"status": "INTRANSIT",
"details": {
"courierPosition": {
"lat": "-34.59564000",
"lng": "-58.39462300"
}
},
"createdAt": "2021-01-12 10:52:37"
},
{
"status": "PICKEDUP",
"details": null,
"createdAt": "2021-01-12 10:52:37"
},
{
"status": "ATPICKUPPOINT",
"details": {
"courierPosition": {
"lat": "-34.59564000",
"lng": "-58.39462300"
}
},
"createdAt": "2021-01-12 10:52:33"
},
{
"status": "CONFIRMED",
"details": null,
"createdAt": "2021-01-12 10:44:46"
},
{
"status": "WAITING",
"details": null,
"createdAt": "2021-01-12 10:39:45"
},
{
"status": "READY",
"details": null,
"createdAt": "2021-01-12 10:39:38"
},
{
"status": "DRAFT",
"details": null,
"createdAt": "2021-01-11 21:48:06"
}
],
"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": "b07ae420-5456-11eb-848c-b95db72a2751"
},
{
"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": "b07ae420-5456-11eb-848c-b95db72a2751"
},
{
"id": 6,
"name": "UpdateDeliveredItems",
"apply_to_all": 0,
"description": "Once the shipping is delivered, update the delivered items",
"message": null,
"created_at": "2021-01-05 19:01:27",
"updated_at": "2021-01-05 19:01:27",
"deleted_at": null,
"laravel_through_key": "b07ae420-5456-11eb-848c-b95db72a2751"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"price": 150,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"quantity": 1,
"description": "Tarjeta",
"referenceCode": null,
"serialNumber": "12345678998765432111"
},
{
"price": 140,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"quantity": 1,
"description": "Post Marca A",
"referenceCode": null,
"serialNumber": "12345678998765432222"
},
{
"price": 140,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"quantity": 2,
"description": "Post Marca B",
"referenceCode": null,
"serialNumber": "12345678998765432333"
},
{
"price": 140,
"currency": "ARS",
"width": 20,
"height": 20,
"length": 20,
"weight": 20,
"quantity": 2,
"description": "Post Marca B",
"referenceCode": null,
"serialNumber": "12345678998765432444"
}
],
"createdAt": "2021-01-11 21:48:06"
}Ejemplo de payload para un envío para dentro de 2 días que debe entregarse durante la mañana.
Para poder generar un envío el cual queremos que se realice en el futuro en un rango horario determinado en el payload tenemos que especificar lo siguiente:
scheduledDate: fecha (UTC) en la que se debe realizar el envío (es una fecha en el futuro). El formato de la fecha debiera ser: "2023-02-20". Asegurarse que han acordado con la parte comencial para hacer envíos en fechas especificas a futuro
y
deliveryTimeRange: En este campo permite definir el rango horario en que se quiere realizar el envío. Las opciones son "AM" o "PM". Para que este parámetro sea tenido en cuenta, scheduledDate tiene que tener una fecha mayor al día donde se está creando el envío. Este paramentro sirve para envío que serán realizados en el futuro no para envíos sameday.
Ejemplo de payload
{
"scheduledDate": "2023-03-15",
"deliveryTimeRange":"AM",
"flow":"manual",
"currency": "ARS",
"type":"regular",
"from": {
"street": "Amenabar",
"number": 1444,
"floor": "6to",
"apartment": "C",
"city": "CABA",
"state": "CABA",
"postalCode": "1425",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": ""
},
"to": {
"street": "Vidal",
"number": 4134,
"floor": "6to",
"apartment": "C",
"city": "CABA",
"state": "CABA",
"postalCode": "1426",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Antonio",
"lastName": "Prieto",
"email": "prueba@prueba.com",
"phone":"4765-5213"
},
"message": "Es su cumpleaños"
},
"comments": "Super Importante",
"extra": {},
"deliveryInfo": {},
"conf": {
"items":[
{"width":10, "height":5, "length":"S", "quantity":3},
{"width":10, "height":5, "length":12, "quantity":3}
]
}
}Ejemplo de payload especificando la cantidad de bultos en un shipping.
{
"packagesCount":3,
"flow":"semi-automatic",
"currency": "ARS",
"type":"regular",
"from": {
"street": "Amenabar",
"number": 1444,
"floor": "6to",
"apartment": "C",
"city": "CABA",
"state": "CABA",
"postalCode": "1425",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": ""
},
"to": {
"street": "Vidal",
"number": 4134,
"floor": "6to",
"apartment": "C",
"city": "CABA",
"state": "CABA",
"postalCode": "1426",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Antonio",
"lastName": "Prieto",
"email": "prueba@prueba.com",
"phone":"4765-5213"
},
"message": "Es su cumpleaños"
},
"internalCode": "A4564",
"comments": "Super Importante",
"extra": {},
"deliveryInfo": {},
"conf": {
"items":[
{"width":10, "height":5, "length":"S", "quantity":3},
{"width":10, "height":5, "length":12, "quantity":5}
]
}
}Ejemplo de payload de un pedido ida y vuelta
En este caso, donde el objetivo es que cuando el mensajero realice la entrega, recoga algo y esto sea devuelto al origen. Ejemplo de un casos de uso: reemplazo de un celular.
Por favor chequear con la sección comercial de Moova antes de utilizar este tipo de envío.
Para pedir que se que un envío sea “ida y vuelta” setear settings en 5.
"settings": [5]
Los settings se pueden acumular, por ejemplo si quisieramos reemplazar un equipo, al que te tenemos que tomar el numero de serie del que entregamos y a su vez devolver el viejo, entonces usaríamos la siguiente configuración en settings. (6 por nro de serie y 5 para ida y vuelta).
"settings": [6,5]
OJO: Este tipo de envío debiera utilizarse unicamente con 1 item que es el que entregamos y luego devolvemos uno que se recoge en el punto de entrega.
Por otra parte cuando se hace un envío de ida y vuelta, se pueden especificar settings para el retorno, por ejemplo si ponemos
"return_settings": [2]
Significa que le pedimos al mensajero que saque una foto del item que le entregán para la devolución.
Otra opcion que podríamos agregar al "return_settings" podría ser la 1 que significa pedir la firma en pickup.
Aquí vemos un ejemplo de un payload completo para la creación del pedido
{
"currency": "ARS",
"type": "regular",
"flow": "manual",
"from": {
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "Intruciones pickup",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": "Mensaje pickup"
},
"to": {
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "Recoger el Router Viejo",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": "Mensaje entrega"
},
"internalCode": "string",
"description": "Descripcion del item",
"label": "label del item",
"extra": {},
"settings": [
5
],
"conf": {
"assurance": false
},
"items": [
{
"description": "Post Marca A",
"price": 130,
"currency": "ARS",
"weight": 14,
"length": 15,
"width": 16,
"height": 17,
"quantity": 1
}
]
}Y aquí la response de la creación del payload. Podemos verificar al final dentro de "activeSettings"
que el que tiene ID = 5 está presente que es el que necesitamos. Puede haber otros "activeSettings"
que no se pusieron el payload pero que el sistema agrega de manera automática.
La response completa será:
{
"id": "3ace6160-6492-11eb-8d87-cdce34618873",
"scheduledDate": null,
"type": "regular",
"priceFormatted": "$100,00",
"price": "100.00",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Intruciones pickup",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"to": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "",
"instructions": "Recoger el Router Viejo",
"coords": {
"lat": "-34.59361200",
"lng": "-58.40485790"
}
},
"status": "DRAFT",
"secretCode": "6692",
"internalCode": "string",
"internalOrderId": null,
"description": "Descripcion del item",
"hash": "6b17a6b246930a7b781bb217846493ed1d93eb5b4d6920e9ca237a952526538c",
"message": "Mensaje entrega",
"extra": [],
"conf": {
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "DRAFT",
"details": null,
"createdAt": "2021-02-01 13:34:37"
}
],
"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": "3ace6160-6492-11eb-8d87-cdce34618873"
},
{
"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": "3ace6160-6492-11eb-8d87-cdce34618873"
},
{
"id": 5,
"name": "BackAndForth",
"apply_to_all": 0,
"description": "Back and forth shipping",
"message": null,
"created_at": "2021-01-05 19:01:27",
"updated_at": "2021-01-05 19:01:27",
"deleted_at": null,
"laravel_through_key": "3ace6160-6492-11eb-8d87-cdce34618873"
}
],
"relatedShippings": {
"previous": null,
"next": "eb831920-8ca7-11eb-ac1f-af3103d0d3db"
},
"items": [
{
"description": "Post Marca A",
"referenceCode": null,
"serialNumber": null,
"price": 130,
"currency": "ARS",
"weight": 14,
"length": 15,
"width": 16,
"height": 17,
"quantity": 1
}
],
"createdAt": "2021-02-01 13:34:37"
}En “relatedShippings” se tendrá información de la vuelta en el elemento “next”. En caso de pedir información sobre la vuelta, en el campo “previous” se tendrá el ID de envío de “la ida”.
Ejemplo de setting para exigir que solo se entregue a la persona que figura como destinatario (OnlyDeliverToAddressee)
En este caso, donde el objetivo es que cuando el mensajero realice la entrega, únicamente le entregue el paquete a la persona que figura como destinatario. En caso que está persona no esté presente en la casa no se lo va a entregar a ningún familiar.
Por favor chequear con el agente comercial de Moova antes de utilizar este tipo de envío dado que generará un porcentaje mucho mas alto de lo normal de inicidencias que genera costos adicionales.
Para pedir que se que un envío sea “OnlyDeliverToAddressee” setear settings en 8.
"settings": [8]
Los settings se pueden acumular, por ejemplo si quisieramos que solo se entregue al destinatario que figura y que además el scaneo de la “mancha” del DNI (SOLO EN ARGENTINA) sea obligatorio entonces configurariamos los settings de la siguiente manera
"settings": [8,9]
Ejemplo de setting para exigir que solo se escanee la mancha del DNI Argentino (ScanReiceiverId)
En este caso, el objetivo es que cuando el mensajero realice la entrega, sea obligatorio el escaneo de la mancha del DNI de la persona que recibe el paquete. Luego se puede recuperar el string completo de este escaneo a través de un GET del envío.
Este setting solo funciona en Argentina dado que el es único documento que tiene “la mancha”
Por favor chequear con el agente comercial de Moova antes de utilizar este tipo de envío dado que generará un porcentaje mucho mas alto de lo normal de incidenciqs que generan costos adicionales.
Para pedir que se que un envío sea “ScanReiceiverId” setear settings en 9.
"settings": [9]
Los settings se pueden acumular, por ejemplo si quisieramos que solo se entregue al destinatario que figura y que además el scaneo de la “mancha” del DNI (SOLO EN ARGENTINA) sea obligatorio entonces configurariamos los settings de la siguiente manera:
"settings": [8,9]
Ejemplo para exigir que el moover le exiga al usuario final un código para realizar la entrega
Supongamos que estamos entregando un elemento de mucho valor y que queremos asegurarnos que la persona a la cual se la estamos entregando es la persona correcta para realizar la entrega. Para esto podemos exigirle al usuario final que este nos de un código que valide la operación.
Ejemplos:
Queremos que el usuario final nos diga los últimos 4 digitos de la tarjeta de crédito con la cual realizó la compra.
Queremos que el usuario final nos diga los últimos 3 digitos de la factura de la compra.
Un ejemplo de como implementar este requerimiento es incluyendo en el payload de creación de un envío lo siguiente:
"delivery": {
"securityCode": "C212412",
"securityMessage": "Por favor pedir el numero de la factura"
}La ubicación de esta opción debe estar dentro del cuerpo principal del payload.
En caso que exista dentro del payload esta información, será mandatorio que el usuario final le de esta información al moover para que este la ingrese en la app y se verifique. En caso que el usuario no tenga esta info o que no sea correcta las intrucciones el Moover NO entregará este item.
Antes de agregar esta opción en el payload por favor contactar con el comercial de Moova que lo atiende para entender las consecuencias de esta exigencia, dado que generará una cantidad importantes de incidencias en entregas que tendrán un costo económico.
Error messages
Error de validación de datos
{
"errors": [
{
"status": "422",
"code": 0,
"title": "Validation error",
"detail": "The from.city is required when from.street is present."
},
{
"status": "422",
"code": 0,
"title": "Validation error",
"detail": "The to.number is required when to.street is present."
}
]
}Importante, si existiesen errores de direcciónes (Origen o destino no encontrado), el envio quedará en estado DRAFT y no tendra precio independientemente del flow seleccionado. Es importante verificar el estado final del envio creado. Si no se verifica puede surgir demoras hasta que sea corregido.
Servicio no disponible entre las direcciones provistas
{
"status": "error",
"code": 404,
"message": "Budget is not available for the specific places"
}Es importante enviar el campo to.email o sea el email del destinatario. En caso que la dirección no sea interpretada correctamente por Moova, si está el email, le enviaremos una comunicación para que corrija la dirección. Nadie conoce mejor la dirección que uno mismo
Información sobre depósitos
En algunos casos en particular, la mercadería esté en los depositos de Moova. En este caso, existe un endpoint al que le podemos preguntar cual es el depósito mas cercano a la dirección de destino del envío.
Una vez que sabemos el deposito mas cercano luego podemos crear el envío.
Al ser un endpoint B2B, recibe el appId como parámetro y se debe pasar el apiKey en el header Authorization.
Los parámetros pueden ser:
o sea que las opciones para pasar la dirección de destino son las siguientes:
Via place Id de Moova:GET /b2b/warehouses/closest?appId=<APPID>&placeId=444
Via Full Address:GET /b2b/warehouses/closest?appId=<APPID>&address=Amenabar%201444%2C%20CABA%2C%20ArgentinaVia Coordenadas:GET /b2b/warehouses/closest?appId=<APPID>&coords[lat]=-34.568869&coords[lng]=-58.447516Via Dirección compuesta:GET /b2b/warehouses/closest?appId=<APPID>&street=Amenabar&number=1444&city=Colegiales&state=CABA&country=AR
Ejemplo de devolución del endpoint:
Devuelve los datos del warehouse a utilizar como origen al querer hacer un envio a la dirección que vino como destino.
{
"placeId": 258,
"reference": "Sucursal 1",
"address": {
"formatted": "Av. Córdoba 1500, C1055AAR CABA, Argentina",
"extra": null
},
"contact": {
"name": "Marcelo",
"email": "mmm@minegocio.com",
"phone": "+54 11 4567 890"
}
}Y una devolución con error
{
"status": "error",
"code": 0,
"message": "Target address is out of coverage area",
}Cotización de un shippings
La cotización de un shipping permite obtener el costo de un envío.
Hay tres endpoints para obtener esta información.
/b2b/v1/budgets | Cotización cuando la direcciones están en una solo string |
/b2b/v2/budgets | Cotización cuando la direcciones están divididas en (dirección, número, etc) |
/b2b/budgets/estimate | Estimación de cotización basada en código postal. La cotización es un estimado. |
La mejor opción es /b2b/v2/budgets cuando tenemos la dirección con datos separados (calle, número, ciudad, etc)
Ejemplos de Payloads para cada uno de los casos.
La documentación formal de la API la encontrarás en swagger aquí
Actualización de un shippings
Params:
api_key
application_id
Body:
Todos los campos que se enviaron al momento de la creación del envió pueden ser actualizados. En caso de hacer un cambio en alguna de las direcciones el envió se volverá a cotizar según las nuevas distancias.
{
"scheduledDate": "2021-02-20 15:00:00",
"currency": "ARS",
"type": "minutes_90",
"flow": "automatic",
"from": {
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"floor": "6to",
"apartment": "C",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": "+54 11 8786 1232"
},
"message": ""
},
"to": {
"googlePlaceId": null,
"street": "Avenida Córdoba",
"number": "1500",
"floor": "3to",
"apartment": "F",
"city": "CABA",
"state": "CABA",
"postalCode": "1055",
"country": "AR",
"instructions": "Entregar al Portero. Almuerza a la 1",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "jose@gmail.com",
"phone": "+54 11 6765 8765"
},
"message": ""
},
"internalCode": "X23454",
"description": "string",
"label": "string",
"extra": {},
"settings": [1, 2],
"conf": {
"assurance": false,
"items": [
{
"item": {
"description": "iPhone",
"price": 150,
"weight": 2000,
"length": 20,
"width": 20,
"height": 20
}
}
]
}
}Response
{
"id": "b9255870-6166-11ea-914b-ff471ce5170b",
"scheduledDate": "2021-02-20 15:00:00",
"type": "minutes_90",
"priceFormatted": "$ 200,00",
"price": "200.00",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "+54 11 8786 1232",
"instructions": "No funciona el timbre. Llamar antes"
},
"to": {
"placeId": 258,
"googlePlaceId": "ChIJGTa0WcfKvJUReHvuhmo0zpE",
"address": "Av. Córdoba 1500, C1055AAR CABA, Argentina",
"addressExtra": "3to F",
"contact": "Juan Perez",
"email": "jose@gmail.com",
"phone": "+54 11 6765 8765",
"instructions": "Entregar al Portero. Almuerza a la 1"
},
"status": "WAITING",
"secretCode": "6975",
"internalCode": "X23454",
"internalOrderId": null,
"description": "string",
"hash": "eff81c0aaefe7a39e43e1c5ff52762eda533fd77aad5d743d3841b5ba1e90d0d",
"message": "",
"extra": [],
"conf": {
"items": [
{
"item": {
"price": 150,
"width": 20,
"height": 20,
"length": 20,
"weight": 2000,
"description": "iPhone"
}
}
],
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "WAITING",
"details": null,
"createdAt": "2020-03-08 18:00:40"
}
],
"activeSettings": [
{
"id": 1,
"name": "PickupSignature",
"description": "In order to pick up this shipping the sender must provide a signature",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
},
{
"id": 2,
"name": "PickupPhoto",
"description": "In order to pick up this shipping is mandatory to take a picture of the package",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
}
],
"createdAt": "2020-03-08 18:00:40"
}Cambio de estado de un shipping
Los únicos cambios de estado permitidos son :
a) a estado READY lo que significa que el paquete está listo para que se realice el pickup.
o
b) CANCELED. para cancelar un envío
a) Cambio a READY
Response
{
"status": "READY",
"shipping_id": "bf7ef9f0-6165-11ea-a9a8-c5eab9a8e071",
"updated_at": "2020-03-08 23:47:19",
"created_at": "2020-03-08 23:47:19",
"id": 8267
}a) Cambio a CANCEL.
Response
{
"status": "CANCELED",
"details": {
"reason": "Creado por error"
},
"shipping_id": "bf7ef9f0-6165-11ea-a9a8-c5eab9a8e071",
"updated_at": "2020-03-08 23:55:36",
"created_at": "2020-03-08 23:55:36",
"id": 8268
}Como pedir información sobre un shipping por API
Para pedir información de un shipping se puede pedir con el Shipping ID completo o en caso de ser necesario con los primeros 8 caracteres del mismo
Response
{
"id": "b9255870-6166-11ea-914b-ff471ce5170b",
"scheduledDate": "2021-02-20 15:00:00",
"type": "minutes_90",
"priceFormatted": "$ 200,00",
"price": "200.00",
"currency": "ARS",
"from": {
"placeId": 63,
"googlePlaceId": "ChIJYVOqvJrKvJURbO0qQqXC8MA",
"address": "Av. Santa Fe 2678, C1425BGO CABA, Argentina",
"addressExtra": "6to C",
"contact": "Juan Perez",
"email": "",
"phone": "+54 11 8786 1232",
"instructions": "No funciona el timbre. Llamar antes"
},
"to": {
"placeId": 258,
"googlePlaceId": "ChIJGTa0WcfKvJUReHvuhmo0zpE",
"address": "Av. Córdoba 1500, C1055AAR CABA, Argentina",
"addressExtra": "3to F",
"contact": "Juan Perez",
"email": "jose@gmail.com",
"phone": "+54 11 6765 8765",
"instructions": "Entregar al Portero. Almuerza a la 1"
},
"status": "WAITING",
"secretCode": "6975",
"internalCode": "X23454",
"internalOrderId": null,
"description": "string",
"hash": "eff81c0aaefe7a39e43e1c5ff52762eda533fd77aad5d743d3841b5ba1e90d0d",
"message": "",
"extra": [],
"conf": {
"items": [
{
"item": {
"price": 150,
"width": 20,
"height": 20,
"length": 20,
"weight": 2000,
"description": "iPhone"
}
}
],
"assurance": false
},
"deliveryInfo": {
"courier": null,
"lat": null,
"lng": null
},
"statusHistory": [
{
"status": "WAITING",
"details": null,
"createdAt": "2020-03-08 18:00:40"
}
],
"activeSettings": [
{
"id": 1,
"name": "PickupSignature",
"description": "In order to pick up this shipping the sender must provide a signature",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
},
{
"id": 2,
"name": "PickupPhoto",
"description": "In order to pick up this shipping is mandatory to take a picture of the package",
"created_at": "2020-02-10 14:31:44",
"updated_at": "2020-02-10 14:31:44",
"deleted_at": null,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b"
}
],
"relatedShippings": {
"previous": null,
"next": null
},
"items": [
{
"id": 47,
"shipping_id": "b9255870-6166-11ea-914b-ff471ce5170b",
"description": "iPhone",
"referenceCode": null,
"serialNumber": null,
"weight": 2000,
"length": 20,
"width": 20,
"height": 20,
"quantity": 1,
"meta": {
"foo": "bar"
},
"createdAt": "2020-03-08 18:00:40",
"updatedAt": "2020-03-08 18:00:40"
}
]
"createdAt": "2020-03-08 18:00:40"
}Cargar un envio de Mercado libre en Moova
Para este tipo de carga se necesita antes tener la integracion con Mercadolibre hecha, para eso revise la documentacion que esta aqui: Como integrarme con mercadolibre
Una vez hecho esto pueden pegarle al endpoint
Donde {platform} sera reemplazado por el valor MELI en caso de querer realizarlo con mercadolibre
El ‘nickname’ es el nickname del vendedor, y el campo ‘platformShippingId’, corresponde al id del envio de mercadolibre. Marcamos solo los parametros de Origen del envio, porque los datos del destino se obtienen automaticamente desde MELI.
payload:
{
"platformShippingId": "28290877823",
"nickname": "NicknameCreatorUser",
"from": {
"googlePlaceId": "string",
"street": "Av. Santa Fe",
"number": "2678",
"floor": "6to",
"apartment": "C",
"city": "Capital Federal",
"state": "Capital Federal",
"postalCode": "1425",
"country": "AR",
"instructions": "No funciona el timbre. Llamar antes",
"contact": {
"firstName": "Juan",
"lastName": "Perez",
"email": "",
"phone": ""
},
"message": ""
}
}Importante: es el id del envio no enviar el id de la orden
Como enviar a un usuario final una URL para su seguimiento
Para enviar una URL al usuario final para su seguimiento la URL se construye de la siguiente manera:
Para entorno DEV
https://dev.moova.io/external/shipping_ID
Ejemplo:
https://dev.moova.io/external/69324ca0-7aa3-11eb-a68b-ddfcc37e5bae
Para entorno de Producción.
https://dev.moova.io/external/shipping_ID
Como imprimir una etiqueta de un shipping por API
El único parametro necesario es el ID del shipping completo.
Recibiremos como respuesta la URL del PDF de la etiqueta.
{
"label": "https://s3.amazonaws.com/develop.files.moova.io/shippings/labels/b9255870-6166-11ea-914b-ff471ce5170b_15x10.pdf"
}En caso que el shipping tenga un dirección incorrecta dará el siguiente error hasta que esta dirección sea corregida por el usuario final, el cliente que pide el envío o el operador Moova.
{
"status": "error",
"message": "Something went wrong on our side",
"code": 500,
"exception": "ErrorException: Trying to get property 'name' "
}Definición de settings en un envío.
Estos settings se pueden poner en los envíos. Por favor consultar en un ticket si necesitan mayor información para utilizarlos.
{
"data": [
{
"id": 1,
"name": "PickupSignature",
"description": "In order to pick up this shipping the sender must provide a signature",
},
{
"id": 2,
"name": "PickupPhoto",
"description": "In order to pick up this shipping is mandatory to take a picture of the package",
},
{
"id": 3,
"name": "SignaturePhoto",
"description": "Instead of ask for a signature, take a picture of the package.",
},
{
"id": 5,
"name": "BackAndForth",
"description": "Back and forth shipping",
},
{
"id": 7,
"name": "DeliverySurvey",
"description": "Displays company survey when shipping is delivered",
}La documentación formal de la API la encontrarás en swagger aquí
Cualquier duda abrir un ticket aquí