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

Owned by Marcos Detry
Last updated: Jun 07, 2021
55 min read

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

{ "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"

Response

 

 

Ejemplo de payload donde envío a dirección a través de un Google Place ID y también ejemplo de settings.

 

Response

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.

Response

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.

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.

 

Aquí la response del payload de creación completo.

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.

 

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

 

 

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

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.

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:

La ubicación de esta opción debe estar dentro del cuerpo principal del payload.

 


Error messages

 

Error de validación de datos 

Servicio no disponible entre las direcciones provistas

 

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.

 

 

Y una devolución con error

 

 

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.

Ejemplos de Payloads para cada uno de los casos.

Payload

Parameters

Body

Response

Payload

Response

Payload

Response

 

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.

 

Response

 

Cambio de estado de un shipping

a) Cambio a READY

Response

a) Cambio a CANCEL.

Response

 

Como pedir información sobre un shipping por API

Response

 

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:

 

 

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.

 

 

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.

 

 

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.