E-commerce
Melhor Envio en tu producto y en tus agentes de IA, con una API
El toolkit de Melhor Envio cubre cotización de envíos entre CEPs, el carrito de etiquetas, pago y generación de etiquetas, impresión, búsqueda y cancelación de etiquetas y el saldo de la billetera. Tu cliente conecta Melhor Envio una vez con OAuth, y tu tienda, herramienta de marketplace o agente de IA ejecuta cada operación a través de Connect, que guarda y renueva las credenciales y registra cada ejecución.
15 días de prueba. Sin tarjeta de crédito.
POST https://connect.reportei.com/api/tools/melhor_envio_calculate_shipping/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"from": {},
"to": {},
"products": []
}
}Cómo funciona
Del cliente conectado a la primera llamada a Melhor Envio.
- 1
Tu cliente conecta la cuenta
Tu sistema abre una sesión de Connect para el toolkit y tu cliente conecta su cuenta de Melhor Envio. Recibes el id de la conexión.
- 2
Tu producto llama a la tool
Un POST a /api/tools/{tool}/execute con el id de la conexión y los argumentos. Si la llamada tiene éxito, Connect conserva el status y el cuerpo de la respuesta de la app.
- 3
Connect se encarga del resto
Guarda la credencial cifrada, renueva tokens en conexiones OAuth que admiten renovación y registra las ejecuciones en un historial de auditoría disponible por API.
Casos de uso
Qué hace tu producto con Melhor Envio.
Cotización de envío en el checkout
Llama a Calcular envío con los productos y los dos CEPs para mostrar precio y plazo de cada transportista antes de que el comprador pague.
Despacha un pedido de punta a punta
Crea un ítem en el carrito, cómpralo con la billetera, genera la etiqueta e imprímela, todo desde tu propia pantalla de pedidos.
Agente responde dónde está mi pedido
Un agente de IA encuentra una etiqueta por código de seguimiento o CPF y lee su estado y las fechas de postaje y entrega.
Tools
12 tools de Melhor Envio
- Calcular envíoPOSTCotiza el envío de productos entre dos CEPs y devuelve una entrada por servicio, con id, transportista, precio, plazo de entrega, los paquetes y un error cuando el servicio no cubre la ruta. custom_price y custom_delivery_time incluyen las tarifas y descuentos de la cuenta. Solo se cotizan los servicios habilitados para la integración en el panel de Melhor Envio.
- Crear ítem en el carritoPOSTAgrega una etiqueta al carrito de la cuenta y la devuelve. Su id es el id de la etiqueta en las demás herramientas. No se paga nada hasta Comprar etiquetas. Correios, J&T y Loggi aceptan un volumen por llamada: para más paquetes, agrega un ítem por paquete.
- Listar ítems del carritoGETLista las etiquetas del carrito que aún no se pagaron, con id, servicio, precio, remitente, destinatario y volúmenes. Las etiquetas permanecen 20 días en el carrito. 10 por página: pasa page para las siguientes, hasta last_page.
- Eliminar ítem del carritoDELETEQuita del carrito una etiqueta que aún no se pagó.
- Comprar etiquetasPOSTPaga etiquetas del carrito con el saldo de la billetera de Melhor Envio y devuelve la compra, con el total y las etiquetas, ya liberadas. La billetera necesita saldo suficiente: compruébalo con Obtener saldo. Las etiquetas pagadas aún necesitan Generar etiquetas.
- Generar etiquetasPOSTGenera etiquetas pagadas, lo que es necesario antes de Imprimir etiquetas, y devuelve el resultado de cada id. Una etiqueta generada debe postarse en un plazo de 20 días, o 7 días con Correios.
- Imprimir etiquetasPOSTDevuelve un enlace para imprimir etiquetas generadas. Un enlace privado se abre solo para quien inició sesión en la cuenta de Melhor Envio; un enlace público se abre para cualquiera que lo tenga.
- Listar etiquetasGETLista las etiquetas de la cuenta con id, protocolo, estado, servicio, precio, código de seguimiento y las fechas de pago, generación, postaje y entrega. 10 por página: pasa page para las siguientes, hasta last_page.
- Obtener etiquetaGETDevuelve una etiqueta con estado, servicio, precio, remitente, destinatario, volúmenes, código de seguimiento y las fechas de pago, generación, postaje y entrega.
- Buscar etiquetasGETEncuentra etiquetas por un valor exacto: el id, el protocolo, el código de seguimiento, el código de autorización, o el CPF o CNPJ del remitente o del destinatario.
OAuth con la app de tu producto
Registras la app OAuth de tu producto una sola vez, con POST /api/merchants/credentials/melhor_envio, y tu cliente autoriza la cuenta en una pantalla de consentimiento. Connect renueva el token cuando está por vencer.
Preguntas sobre el toolkit de Melhor Envio
¿Necesito implementar la API de Melhor Envio?
No. Connect ya trae 12 tools de Melhor Envio descritas y listas. Tu cliente conecta la cuenta y tu sistema llama a cada tool por el mismo endpoint, con el mismo formato de solicitud.
¿Cómo conecta mi cliente su cuenta de Melhor Envio?
Con el modo que acepta el toolkit: OAuth con la app de tu producto. Connect guarda la credencial cifrada y nunca la devuelve a tu sistema.
¿Funciona con agentes de IA?
Sí. El input de cada tool está descrito en JSON Schema, que tu agente usa directamente como definición de tool. El agente elige la tool y los argumentos, y tu sistema hace la llamada a Connect.
¿Mi cliente necesita una cuenta en Reportei?
No. Tu cliente conecta la cuenta en una pantalla de Connect, o tu sistema envía la credencial por la API, y sigue usando solo tu producto.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
