E-commerce
Melhor Envio no seu produto e nos seus agentes de IA, por uma API
O toolkit do Melhor Envio cobre cotação de frete entre CEPs, o carrinho de etiquetas, pagamento e geração de etiquetas, impressão, busca e cancelamento de etiquetas e o saldo da carteira. Seu cliente conecta o Melhor Envio uma vez por OAuth, e sua loja, ferramenta de marketplace ou agente de IA executa cada operação pelo Connect, que guarda e renova as credenciais e registra cada execução.
15 dias para testar. Sem cartão 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": []
}
}Como funciona
Do cliente conectado à primeira chamada no Melhor Envio.
- 1
O cliente conecta a conta
Seu sistema abre uma sessão do Connect para o toolkit e o cliente conecta a conta do Melhor Envio. Você recebe o id da conexão.
- 2
Seu produto chama a tool
Um POST em /api/tools/{tool}/execute com o id da conexão e os argumentos. Em caso de sucesso, o Connect preserva o status e o corpo da resposta do app.
- 3
O Connect cuida do resto
Guarda a credencial criptografada, renova tokens quando a conexão usa OAuth com suporte a renovação e registra as execuções numa trilha de auditoria consultável pela API.
Para que usar
O que o seu produto faz com o Melhor Envio.
Cotação de frete no checkout
Chame Calcular frete com os produtos e os dois CEPs para mostrar preço e prazo de cada transportadora antes de o comprador pagar.
Despache um pedido de ponta a ponta
Crie um item no carrinho, compre com a carteira, gere a etiqueta e imprima, tudo na sua própria tela de pedidos.
Agente responde onde está meu pedido
Um agente de IA encontra uma etiqueta pelo código de rastreio ou CPF e lê o status e as datas de postagem e entrega.
Tools
12 tools do Melhor Envio
- Calcular fretePOSTCota o frete de produtos entre dois CEPs e retorna uma entrada por serviço, com id, transportadora, preço, prazo de entrega, os pacotes e um error quando o serviço não atende a rota. custom_price e custom_delivery_time incluem as taxas e descontos da conta. Só os serviços habilitados para a integração no painel do Melhor Envio são cotados.
- Criar item no carrinhoPOSTAdiciona uma etiqueta ao carrinho da conta e a retorna. O id dela é o id da etiqueta nas outras ferramentas. Nada é pago até Comprar etiquetas. Correios, J&T e Loggi aceitam um volume por chamada: para mais pacotes, adicione um item por pacote.
- Listar itens do carrinhoGETLista as etiquetas do carrinho que ainda não foram pagas, com id, serviço, preço, remetente, destinatário e volumes. As etiquetas ficam 20 dias no carrinho. 10 por página: passe page para as próximas, até last_page.
- Excluir item do carrinhoDELETERemove do carrinho uma etiqueta que ainda não foi paga.
- Comprar etiquetasPOSTPaga etiquetas do carrinho com o saldo da carteira do Melhor Envio e retorna a compra, com o total e as etiquetas, já liberadas. A carteira precisa ter saldo suficiente: confira com Obter saldo. Etiquetas pagas ainda precisam de Gerar etiquetas.
- Gerar etiquetasPOSTGera etiquetas pagas, o que é necessário antes de Imprimir etiquetas, e retorna o resultado de cada id. Uma etiqueta gerada deve ser postada em até 20 dias, ou 7 dias com os Correios.
- Imprimir etiquetasPOSTRetorna um link para imprimir etiquetas geradas. Um link privado abre só para quem está logado na conta do Melhor Envio; um link público abre para qualquer pessoa que o tenha.
- Listar etiquetasGETLista as etiquetas da conta com id, protocolo, status, serviço, preço, código de rastreio e as datas de pagamento, geração, postagem e entrega. 10 por página: passe page para as próximas, até last_page.
- Obter etiquetaGETRetorna uma etiqueta com status, serviço, preço, remetente, destinatário, volumes, código de rastreio e as datas de pagamento, geração, postagem e entrega.
- Buscar etiquetasGETEncontra etiquetas por um valor exato: o id, o protocolo, o código de rastreio, o código de autorização, ou o CPF ou CNPJ do remetente ou do destinatário.
OAuth com o app do seu produto
Você cadastra o app OAuth do seu produto uma vez, em POST /api/merchants/credentials/melhor_envio, e o cliente autoriza a conta numa tela de consentimento. O Connect renova o token quando ele está para vencer.
Perguntas sobre o toolkit do Melhor Envio
Preciso implementar a API do Melhor Envio?
Não. O Connect já traz 12 tools do Melhor Envio descritas e prontas. Seu cliente conecta a conta e o seu sistema chama cada tool pelo mesmo endpoint, com o mesmo formato de requisição.
Como o cliente conecta a conta do Melhor Envio?
Pelo modo que o toolkit aceita: OAuth com o app do seu produto. O Connect guarda a credencial criptografada e nunca a devolve ao seu sistema.
Funciona com agentes de IA?
Sim. O input de cada tool é descrito em JSON Schema, que o seu agente usa direto como definição de tool. O agente escolhe a tool e os argumentos, e o seu sistema faz a chamada ao Connect.
Meu cliente precisa ter conta no Reportei?
Não. O cliente conecta a conta numa tela do Connect, ou o seu sistema envia a credencial pela API, e ele continua usando só o seu produto.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
