Documentação da API de integração

Para ERPs, sistemas de estoque e e-commerces de lojas de autopeças: envie as atualizações dos pedidos aos clientes e receba as respostas deles.

Visão geral

A API de integração permite que o sistema da loja abra a conversa de um pedido, envie as mensagens de cada etapa (separação, faturamento, entrega…) e leia o que o cliente responde pelo aplicativo. Tudo em JSON, por HTTPS.

URL base: https://pushtrack.ativmob.com.br/api/integration/v1

RotaPara quê
POST /orders/{orderNumber}/messagesEnvia uma mensagem; a primeira abre a conversa.
POST /orders/{orderNumber}/closeEncerra a conversa sem mensagem (pode repetir).
GET /orders/{orderNumber}Consulta o estado da conversa do pedido.
GET /inboundLista as respostas dos clientes (polling).

O número do pedido (orderNumber) é o identificador do pedido no seu sistema, com até 60 caracteres. Há uma conversa por pedido.

Credencial e autenticação

No painel do PushTrack, abra Credenciais de API e crie uma credencial (nome e flavor). A chave, que começa com pt_, aparece uma única vez: guarde em local seguro. Uma credencial vale para um flavor e só enxerga as conversas dele. Para trocar a chave, use Girar chave: a anterior deixa de funcionar na hora.

Toda chamada envia a chave no cabeçalho:

Cabeçalho
Authorization: Bearer pt_xxxxxxxx

Limite: 120 requisições por minuto por credencial. Acima disso a API responde 429 com retryAfterSeconds no corpo e o cabeçalho Retry-After.

Enviar mensagens de um pedido

POST /orders/{orderNumber}/messages: a primeira mensagem abre a conversa; as seguintes entram nela. Corpo em JSON:

CampoRegra
phoneFormato E.164 (+5511999999999). Obrigatório na primeira mensagem do pedido. Depois, se enviado, precisa ser o mesmo do cliente (senão 409 PHONE_MISMATCH).
referenceNameObrigatório na primeira mensagem, até 100 caracteres. O título da conversa vira "pedido · referenceName".
customerNameOpcional (2 a 80 caracteres); usado só se o cliente ainda não existir.
titleOpcional, até 120 caracteres. Exibido em destaque acima do texto.
bodyOpcional, até 4.000 caracteres. Texto normal.
trackingUrlOpcional, URL https (até 2.048 caracteres). Entra numa linha própria no fim do texto.
imagesOpcional, até 10 URLs https de imagens já hospedadas (S3 ou CDN). O servidor não baixa as imagens.
finalizetrue grava a mensagem e encerra a conversa.

Envie ao menos um entre title, body, trackingUrl e images. A resposta é 201:

Resposta
{
  "conversationId": "b3c1…",
  "messageId": "9f2a…",
  "created": true,
  "status": "open"
}

Se o cliente ainda não usou o aplicativo, a conversa espera por ele: ao entrar com esse telefone, ela já aparece. Uma conversa encerrada responde 409 CONVERSATION_CLOSED: a API não reabre conversas; só o painel.

POST /orders/{orderNumber}/close encerra sem enviar mensagem e devolve { conversationId, status }. GET /orders/{orderNumber} devolve { conversationId, status, customerHasApp, createdAt, lastMessageAt }; pedido inexistente responde 404.

Exemplo: ciclo de um pedido

Quatro chamadas contam a vida de um pedido. Troque a chave e o telefone pelos seus valores.

curl
KEY=pt_xxxxxxxx
BASE=https://pushtrack.ativmob.com.br/api/integration/v1

# 1. Em separação (abre a conversa)
curl -X POST $BASE/orders/PED-1234/messages -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: ped-1234-separacao' \
  -d '{"phone":"+5511999999999","referenceName":"Oficina do Zé","title":"Em separação","body":"Estamos separando as peças do seu pedido."}'

# 2. Faturado
curl -X POST $BASE/orders/PED-1234/messages -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: ped-1234-faturado' \
  -d '{"title":"Pedido faturado","body":"Nota fiscal emitida."}'

# 3. Saiu para entrega, com rastreio
curl -X POST $BASE/orders/PED-1234/messages -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: ped-1234-entrega' \
  -d '{"title":"Saiu para entrega","body":"Chega hoje até as 18h.","trackingUrl":"https://rastreio.exemplo.com/abc123"}'

# 4. Finalizado (encerra a conversa)
curl -X POST $BASE/orders/PED-1234/messages -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: ped-1234-final' \
  -d '{"title":"Pedido entregue","body":"Obrigado pela preferência!","finalize":true}'

Idempotência

Envie Idempotency-Key (até 100 caracteres, único por mensagem lógica, por exemplo pedido-evento). Repetir a mesma chave em até 24 horas devolve a resposta original com o cabeçalho Idempotent-Replayed: true e não cria outra mensagem. Assim, reenvios depois de um timeout não duplicam.

A mesma chave com conteúdo diferente responde 422; chave ainda em processamento, 409 REQUEST_IN_PROGRESS. Se a primeira tentativa falhou (4xx ou 5xx), a chave pode ser reutilizada.

Receber as respostas dos clientes

Polling (garantido): GET /inbound?cursor=…&limit=50 devolve as respostas dos clientes das conversas do flavor, em ordem cronológica (limit de 1 a 200, padrão 50).

Resposta
{
  "items": [
    {
      "id": "4d7e…",
      "type": "message.customer",
      "occurredAt": "2026-11-15T18:06:41.293Z",
      "orderNumber": "PED-1234",
      "conversationId": "b3c1…",
      "phone": "+5511999999999",
      "body": "Obrigado!"
    }
  ],
  "nextCursor": "eyJ…"
}

Guarde o nextCursor e envie-o na próxima consulta (por exemplo, a cada 30 a 60 segundos). Sem novidades, o cursor volta igual. Sem cursor, a leitura começa a partir da criação da credencial.

Webhook e assinatura

Webhook (aviso imediato, opcional): na credencial, informe uma URL https pública. A cada resposta de cliente, o PushTrack faz um POST com o mesmo evento do polling. Resposta 2xx em até 5 segundos conta como entregue; senão tenta de novo (até 3 vezes: na hora, depois de 10 s e depois de 60 s). As tentativas ficam em memória: se o servidor reiniciar no meio, a resposta continua disponível no polling. O endereço não pode ser interno ou privado (localhost, 10.x, 192.168.x…), e redirecionamentos não são seguidos.

Cada entrega traz estes cabeçalhos:

CabeçalhoConteúdo
X-PushTrack-TimestampMomento do envio, em segundos.
X-PushTrack-Signaturesha256=<hex>: HMAC-SHA256 de "<timestamp>.<corpo bruto>" com o segredo do webhook.
X-PushTrack-DeliveryIdentificador da entrega.

O segredo do webhook aparece uma vez, ao informar a URL na credencial. Confira a assinatura e rejeite timestamps com mais de 5 minutos. Use o corpo bruto (antes de converter para objeto).

Node.js
const crypto = require('crypto');

// rawBody: corpo BRUTO da requisição (string), antes de converter para objeto.
function assinaturaValida(rawBody, headers, secret) {
  const ts = headers['x-pushtrack-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // 5 minutos
  const esperada =
    'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const recebida = headers['x-pushtrack-signature'] || '';
  return (
    recebida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada))
  );
}
PHP
<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_PUSHTRACK_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_PUSHTRACK_SIGNATURE'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$ok = abs(time() - (int)$ts) <= 300 && hash_equals($esperada, $sig);

Erros

CódigoQuando
400Corpo inválido, URL ou imagem inválida, título ou texto grande demais, pedido com mais de 60 caracteres, falta phone ou referenceName na primeira mensagem.
401Chave ausente, inválida, girada ou de credencial desativada.
403Flavor desativado.
404Pedido inexistente (GET e close).
409PHONE_MISMATCH, CONVERSATION_CLOSED ou REQUEST_IN_PROGRESS.
422Idempotency-Key reutilizada com outro conteúdo.
429Mais de 120 requisições por minuto (retryAfterSeconds).

Boas práticas

  • Guarde a chave e o segredo do webhook em cofre de segredos, nunca no código nem no navegador.
  • Use Idempotency-Key em todo envio, para poder repetir sem duplicar.
  • Ao receber 429, espere o tempo de Retry-After antes de tentar de novo.
  • Valide a assinatura do webhook com o corpo bruto e rejeite timestamps antigos.
  • Mantenha o polling como garantia: o webhook é um aviso, o polling é a fonte confiável.

Dúvidas sobre a integração? Escreva para suporte@ativmob.com.br. Veja também a política de privacidade.