Integración con la API Rest de Moova - 2nd Paso - Conceptos

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.

  1. Haberse dado de alta en producción y en el entorno de testing. Si no lo hiciste aún ver las instrucciones aquí. 

  2. 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

 

 

 

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: API_KEY

application_id: ID de aplicación provisto

API_KEY: clave de aplicación provista.

Content-Type: application/json

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 y horario determinado. En general debiera ser null, lo que significa que se procesará cuando entre en el sistema. En caso de ser tener una fecha el formato debiera ser:  "2019-07-20 15:00:00". Si usan una fecha con horario chequear con moova para asegurarse que el uso es correcto.

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 tipo minutes_90 debe ir con el parámetro flow: automatic. El tipo de envío minutes_90 tiene un costo mas elevado que el regular.

  • 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

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

1 2 3 4 5 6 7 8 9 10 11 { "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

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 { "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"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 { "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

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 { "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.

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 { "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 { "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 { "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 { "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 { "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 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

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { "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á:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 { "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:

1 2 3 4 "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 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 {     "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

1 2 3 4 5 {     "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.

 

1 2 3 4 5 6 7 8 9 10 11 12 13 { "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

 

1 2 3 4 5 { "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.

Payload

Parameters

Body

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "conf": { "assurance": false, "backAndForth":false, "items": [ { "item": { "description": "iPhone", "price": 150, "weight": 2000, "length": 20, "width": 20, "height": 20 } } ] } }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "size_id": 3, "size_name": "M", "price": 200, "billing": { "net_price": 200, "taxes": 42, "gross_price": 242 }, "price_formatted": "$ 200,00", "currency": "ARS", "symbol": "$", "quote_id": 626, "kms": 2.166, "budget_id": 8286, "token": "fd38992f0f915e9f6250a8f05b8f0d40ad25ee03a58ff2ef24a291ff178bfbed" }

Payload

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 { "from": { "street": "Av. Santa Fe", "number": "2678", "floor": "6to", "apartment": "C", "city": "Capital Federal", "state": "Capital Federal", "postalCode": "1425", "country": "AR" }, "to": { "street": "Cordoba", "number": "1500", "floor": "3to", "apartment": "b", "city": "Capital Federal", "state": "Capital Federal", "postalCode": "1425", "country": "AR" }, "conf": { "assurance": false, "backAndForth": false }, "items": [ { "description": "T-Shirt", "referenceCode": "AB-1222", "serialNumber": null, "weight": 1500, "length": 40, "width": 30, "height": 50, "price": 2350.99, "currency": "ARS", "quantity": 1 } ], "shipping_type_id": 1 }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "size_id": 2, "size_name": "S", "price": 200, "billing": { "net_price": 200, "taxes": 42, "gross_price": 242 }, "price_formatted": "$ 200,00", "currency": "ARS", "symbol": "$", "quote_id": 626, "kms": 2.166, "budget_id": 8282, "token": "6f5dce09fbe1c03bf50fa9bafcf89751ef4aa7bfc675e914fff4f74f1bc3b208" }

Payload

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "from": { "placeId": 10, "street": "Av. Santa Fe", "number": "2678", "floor": "6to", "apartment": "C", "city": "Capital Federal", "state": "Capital Federal", "postalCode": "1425", "country": "AR" }, "to": { "postalCode": "1642", "country": "AR" }, "conf": { "assurance": false, "backAndForth": false }, "items": [ { "description": "T-Shirt", "referenceCode": "AB-1222", "serialNumber": null, "weight": 1500, "length": 40, "width": 30, "height": 50, "price": 2350.99, "currency": "ARS", "quantity": 1 } ], "shipping_type_id": 1 }

Response

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "size_id": 1, "size_name": "XS", "price": 323.08, "billing": { "net_price": 323.08, "taxes": 67.84679999999999, "gross_price": 390.92679999999996 }, "price_formatted": "$ 323,08", "currency": "ARS", "symbol": "$", "quote_id": 449, "budget_id": 8290, "token": "408394c10938b97a852ba2df00f51a0888fcfe9bd9ae82a7053fc2cb0daf1269" }

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.

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 { "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" }

 

1 curl -X PUT "https://api-dev.moova.io/b2b/shippings/b9255870-6166-11ea-914b-ff471ce5170b?appId=263c2990-5897-11ea-be4a-07dfc19f6353" -H "accept: application/json" -H "Authorization: ce7964b13c1296489cad5bf1c0629c3711d3db5a" -H "Content-Type: application/json" -d "{ \"scheduledDate\": \"2021-02-20 15:00:00\", \"currency\": \"ARS\", \"type\": \"minutes_90\", \"flow\": \"automatic\", \"from\": { \t\"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\": { \t\"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 } } ] }}"

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

1 2 3 4 5 6 7 { "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 }
1 curl -X POST "https://api-dev.moova.io/b2b/shippings/bf7ef9f0-6165-11ea-a9a8-c5eab9a8e071/READY?appId=263c2990-5897-11ea-be4a-07dfc19f6353" -H "accept: application/json" -H "Authorization: ce7964b13c1296489cad5bf1c0629c3711d3db5a"

 

1 https://api-dev.moova.io/b2b/shippings/bf7ef9f0-6165-11ea-a9a8-c5eab9a8e071/READY?appId=263c2990-5897-11ea-be4a-07dfc19f6353

a) Cambio a CANCEL.

Response

1 2 3 4 5 6 7 8 9 10 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 { "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "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.

 

1 2 3 { "label": "https://s3.amazonaws.com/develop.files.moova.io/shippings/labels/b9255870-6166-11ea-914b-ff471ce5170b_15x10.pdf" }

 

 

1 curl -X GET "https://api-dev.moova.io/b2b/shippings/b9255870-6166-11ea-914b-ff471ce5170b/label?appId=263c2990-5897-11ea-be4a-07dfc19f6353" -H "accept: application/json" -H "Authorization: ce7964b13c1296489cad5bf1c0629c3711d3db5a"

 

1 https://api-dev.moova.io/b2b/shippings/b9255870-6166-11ea-914b-ff471ce5170b/label?appId=263c2990-5897-11ea-be4a-07dfc19f6353

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.

 

1 2 3 4 5 6 { "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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { "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í