API: Notificações e Atualizações de Status

Estes métodos do módulo orders gravam um evento no histórico do pedido e mudam o status. Servem para ERP, transportadora e automação avisarem a loja e, quando você pedir, o comprador.

⚠️ A API precisa estar habilitada para utilizá-la. Veja o passo a passo em API - Como habilitar.

Endpoint: https://app.interago.com.br/App/Api/index.php

Todas as chamadas são POST com:

• Cabeçalho Authorization: Bearer SEU_TOKEN
• websiteId no corpo
• module e method identificando o recurso

Ative a API e gere o token em #api.main?general (veja API - Como habilitar). Limite: 60 requisições autenticadas por minuto por website. Trate o token como senha.

No painel, o testador e a documentação do método ficam em #api.main?{módulo}&{método}.

Métodos

Qual pedido

Informe apenas um entre orderId e document. O documento é o CPF (11 dígitos) ou o CNPJ (14), com ou sem pontuação. Se o documento tiver vários pedidos, a API responde MULTIPLE_ORDERS (HTTP 409): repita com o orderId.

Gravar um evento

addOrderNotification grava o texto em OrderTransaction. Essa lista volta em transactions no getOrder.

• description — obrigatório. Texto do evento.
• location — opcional. Entra no texto como (local).
• eventDate — opcional. YYYY-MM-DD ou data e hora. Vazio usa o horário da chamada.
• notifyCustomer — opcional. 1 envia e-mail ao comprador. O padrão é não avisar. Também aceita 0.
• codigo e tipo — opcionais, e os dois juntos. Evento dos Correios, por exemplo BDE e 01.

O texto gravado cabe em 255 caracteres, já com local e código. O e-mail só sai depois que o histórico foi gravado. Se a gravação falha, a resposta é HTTP 500 e notified fica false. transactionNotification fica 1 só quando o e-mail do evento é enviado.

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=orders&method=addOrderNotification&orderId=45678&description=Saiu%20para%20entrega&location=Campinas-SP&notifyCustomer=0'

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=orders&method=addOrderNotification&orderId=45678&description=Seu%20pedido%20est%C3%A1%20a%20caminho&notifyCustomer=1'

Eventos dos Correios

codigo é a sigla da API Rastro. Vale em maiúsculas ou minúsculas, e espaços são ignorados. tipo é o número do evento: 1, 01 e 001 são o mesmo tipo. A decisão olha só esse par, nunca o texto de description. Informe os dois campos juntos.

• BDE/01 e BDI/01 — marcam Entregue (7), pelo mesmo fluxo de updateOrderStatus. E-mail de status, avaliação e fila do ERP só disparam se o status mudar. Se notifyCustomer=1 e o e-mail do evento sair, o aviso genérico de status não se repete; a avaliação continua. eventDate, se vier, vira orderRealDeliveryDate.
• BDR/01 — acrescenta a nota Entrega a confirmar. e liga o alerta do pedido para o lojista. O status não muda. Abrir o pedido no painel marca o alerta como visto.
• Outros tipos de BDE, BDI e BDR (23 devolvido, 24 caixa postal, 26 não retirado, 25, 46 e 47 tentativa) e os códigos LDI e OEC — só entram no histórico.

O evento fica no histórico mesmo quando o status não muda (pedido cancelado, reembolsado ou status que não pode voltar). A resposta continua HTTP 200, com changed: false e reason explicando o motivo.

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=orders&method=addOrderNotification&orderId=45678&description=Objeto%20entregue%20ao%20destinat%C3%A1rio&codigo=BDE&tipo=01&notifyCustomer=0'

Na resposta 200: transactionId, transactionDate, transactionData, notified, carrierCode, carrierType, carrierEffect (none, record, provisional ou delivered), merchantAlert, changed, reason, orderStatus, orderStatusExplain, orderRealDeliveryDate, statusNotified, reviewRequested e erpQueued.

Mudar o status

updateOrderStatus recebe orderStatus:

Se o status já for o mesmo, a resposta vem com changed: false e nada é enviado. Pedido cancelado (1) ou reembolsado (2) não muda (ORDER_STATUS_LOCKED, HTTP 409). O status não volta na sequência 0, 3, 4, 5, 6, 7 (ORDER_STATUS_REGRESSION, HTTP 409). Passar a cancelado ou reembolsado a partir de outro status é permitido, sem estorno no gateway e sem devolver estoque.

deliveredAt só vale com status 7 (YYYY-MM-DD ou data e hora). Vazio usa agora e grava orderRealDeliveryDate.

Quando o status muda de verdade: a loja envia o e-mail de status; a avaliação da compra só na passagem para Entregue, e só se esse e-mail sair; a fila do ERP entra nos status 1, 4 e 7, quando a loja sincroniza. Integrações conectadas recebem o mesmo anúncio do painel: cancelado (order.cancelled), pago (order.paid), enviado e entregue (order.shipped).

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=orders&method=updateOrderStatus&orderId=45678&orderStatus=6'

curl -X POST 'https://app.interago.com.br/App/Api/index.php' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'websiteId=SEU_WEBSITE_ID&module=orders&method=updateOrderStatus&orderId=45678&orderStatus=7&deliveredAt=2026-11-04%2015:30:00'

Na resposta 200: changed, reason (updated ou unchanged), previousStatus, orderStatus, orderStatusExplain, orderRealDeliveryDate, notified, reviewRequested e erpQueued.

Ver também

• API: Módulo Pedidos (orders) — consulta, listagem, cliente PF/PJ e rastreio.

• API : Adicionando código de rastreio a um pedido via Curl — grava o rastreio e promove o pedido para Enviado (6).