API Interago — Ativação e método addTrackingCodeToOrder
Esta documentação descreve como habilitar a API da sua loja no painel Interago e como usar o método addTrackingCodeToOrder para registrar o código de rastreio de um pedido e atualizar automaticamente o status da encomenda.
Ativação da API e geração do token
Antes de chamar qualquer método da API, é necessário ativar o acesso e obter um token de autenticação exclusivo do seu website.
Acesso ao painel
No painel administrativo da Interago, abra a seção API e navegue até a aba Geral. A URL interna do painel é:
#api.main?general
Certifique-se de que um website (loja) esteja selecionado na sessão. Sem website ativo, o painel não permite configurar a API.
Passo a passo
- Gerar o token — Clique em Gerar novo token. O sistema cria um token aleatório de 48 caracteres hexadecimais e o exibe no campo Token (Authorization: Bearer).
Atenção: gerar um novo token invalida imediatamente o token anterior em todas as integrações que o utilizavam. - Ativar a API — Ative o interruptor API ativa.
- Salvar — Clique em Salvar. Para ativar a API, é obrigatório ter um token gerado; sem token, o salvamento com a API ativa é recusado.
Informações exibidas no painel
Na aba Geral você também encontra:
- Endpoint — URL base das requisições: https://www.interago.com.br/App/Api/index.php
- websiteId — Identificador numérico da sua loja; deve ser enviado em toda requisição
- Limite de segurança — 60 requisições autenticadas por minuto por website; ao extrapolar, o website pode ser bloqueado automaticamente
Autenticação nas requisições
Todas as chamadas devem ser feitas com o método POST e incluir:
- Cabeçalho Authorization: Bearer <seu_token>
- Parâmetro websiteId no corpo da requisição (ou na query string)
- Parâmetros module e method identificando o recurso desejado
O token não deve ser enviado na URL nem no corpo da requisição — apenas no cabeçalho Authorization.
Método addTrackingCodeToOrder
O método addTrackingCodeToOrder pertence ao módulo orders. Ele registra o código de rastreio (e, opcionalmente, a URL de acompanhamento) em um pedido elegível e altera o status do pedido para Enviado.
Visão geral
| Módulo | orders |
| Método | addTrackingCodeToOrder |
| HTTP | POST |
| Endpoint | https://www.interago.com.br/App/Api/index.php |
| Efeito principal | Grava rastreio no pedido e define orderStatus = 6 (Enviado) |
Parâmetros da requisição
- websiteId (obrigatório) — ID numérico da loja
- module (obrigatório) — orders
- method (obrigatório) — addTrackingCodeToOrder
- trackingCode (obrigatório) — Código de rastreio da transportadora (ex.: BR123456789BR)
- trackingUrl (opcional) — URL para o cliente acompanhar a entrega (ex.: link dos Correios ou da transportadora)
- orderId ou document (obrigatório um dos dois) — Identificação do pedido:
- orderId — ID numérico do pedido na loja
- document — CPF (11 dígitos) ou CNPJ (14 dígitos) do cliente, apenas números ou com formatação
Regra importante: informe orderId ou document, nunca os dois ao mesmo tempo.
Pedidos elegíveis
Somente pedidos nos seguintes status podem receber rastreio por este método:
- 3 — Autorizado
- 4 — Pago
- 5 — Preparado
Pedidos em outros status (aguardando pagamento, cancelado, reembolsado, já enviado ou entregue) não são elegíveis e retornam erro ORDER_NOT_FOUND.
Quando a busca é feita por document:
- Se existir apenas um pedido elegível para aquele CPF/CNPJ, ele é atualizado automaticamente
- Se existirem vários pedidos elegíveis, a API retorna erro MULTIPLE_ELIGIBLE_ORDERS (HTTP 409) com a lista de pedidos candidatos — nesse caso, envie novamente a requisição informando o orderId desejado
Exemplo de requisição
curl -X POST 'https://www.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=123&module=orders&method=addTrackingCodeToOrder&orderId=45678&trackingCode=BR123456789BR&trackingUrl=https://rastreio.correios.com.br/app/index.php?objetos=BR123456789BR'
Resposta de sucesso (HTTP 200)
{ "status": "success", "module": "orders", "method": "addTrackingCodeToOrder", "orderId": 45678, "trackingCode": "BR123456789BR", "trackingUrl": "https://rastreio.correios.com.br/...", "notified": true, "orderStatus": 6, "orderStatusExplain": "Enviado" }
- notified — Indica se o e-mail de notificação ao cliente foi enviado com sucesso (true ou false). A operação de rastreio é concluída mesmo que o e-mail falhe; verifique este campo se precisar confirmar o envio.
- orderStatus / orderStatusExplain — Sempre refletem o novo estado Enviado (6) após a atualização.
Códigos de erro
- TRACKING_REQUIRED (400) — trackingCode não informado ou vazio
- ORDER_LOOKUP_REQUIRED (400) — Nem orderId nem document foram informados
- ORDER_LOOKUP_AMBIGUOUS (400) — orderId e document enviados juntos
- DOCUMENT_INVALID (400) — CPF/CNPJ inválido (deve ter 11 ou 14 dígitos)
- ORDER_NOT_FOUND (404) — Pedido inexistente ou não elegível para rastreio
- MULTIPLE_ELIGIBLE_ORDERS (409) — Vários pedidos elegíveis para o mesmo documento; use orderId
- UPDATE_FAILED (500) — Falha ao gravar o rastreio no banco de dados
- API_DISABLED (403) — API não ativada no painel para este website
- TOKEN_INVALID / TOKEN_REQUIRED (401) — Token ausente ou incorreto
O que acontece quando o rastreio é inserido
Ao processar com sucesso uma chamada a addTrackingCodeToOrder, o sistema executa automaticamente as etapas abaixo, nesta ordem:
1. Atualização do pedido
O registro do pedido na tabela de pedidos é atualizado com:
- trackingCode — Código informado na requisição
- trackingUrl — URL informada (ou vazio, se omitida)
- orderStatus — Alterado para 6 (Enviado), independentemente do status anterior elegível (3, 4 ou 5)
2. Registro no histórico do pedido
São criadas duas entradas na linha do tempo do pedido (OrderTransaction):
- Uma com a mensagem de mudança de status: “Novo estado da encomenda: Enviado”
- Outra com os dados do rastreio: “Rastreio: [código]” e, se houver URL, “pelo site: [url]”
Esses registros ficam visíveis no histórico do pedido no painel administrativo e nas consultas de detalhe via API.
3. Notificação por e-mail ao cliente
O sistema tenta enviar um e-mail automático ao cliente do pedido com:
- Assunto: “Acompanhe a entrega do pedido #[orderId]”
- Conteúdo: o código de rastreio em destaque e, se informada, um link clicável para a trackingUrl
O e-mail utiliza as configurações de notificação personalizada da loja (CustomNotificationMailData), incluindo remetente, imagem e método de envio (padrão Interago ou SMTP customizado).
Se o cliente não tiver e-mail cadastrado, a configuração de e-mail da loja estiver ausente ou o envio falhar por qualquer motivo, a atualização do rastreio ainda é concluída; apenas o campo notified na resposta virá como false.
4. Registro de log da API
Toda chamada (sucesso ou erro) é registrada nos logs internos da API Interago, associada ao websiteId, módulo, método e, quando aplicável, ao orderId afetado.
Resumo do fluxo
Em uma única requisição bem-sucedida, o método:
- Localiza o pedido elegível (por ID ou documento)
- Grava código e URL de rastreio
- Promove o pedido para status Enviado
- Documenta a alteração no histórico do pedido
- Notifica o cliente por e-mail (quando possível)
- Retorna confirmação JSON com o novo status e indicador de notificação
Esse fluxo permite que ERPs, hubs logísticos e integrações externas informem o rastreio à loja Interago de forma automatizada, mantendo o cliente e o painel administrativo sincronizados com o andamento da entrega.
