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
| Rota | Para quê |
|---|---|
POST /orders/{orderNumber}/messages | Envia uma mensagem; a primeira abre a conversa. |
POST /orders/{orderNumber}/close | Encerra a conversa sem mensagem (pode repetir). |
GET /orders/{orderNumber} | Consulta o estado da conversa do pedido. |
GET /inbound | Lista 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:
Authorization: Bearer pt_xxxxxxxxLimite: 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:
| Campo | Regra |
|---|---|
phone | Formato E.164 (+5511999999999). Obrigatório na primeira mensagem do pedido. Depois, se enviado, precisa ser o mesmo do cliente (senão 409 PHONE_MISMATCH). |
referenceName | Obrigatório na primeira mensagem, até 100 caracteres. O título da conversa vira "pedido · referenceName". |
customerName | Opcional (2 a 80 caracteres); usado só se o cliente ainda não existir. |
title | Opcional, até 120 caracteres. Exibido em destaque acima do texto. |
body | Opcional, até 4.000 caracteres. Texto normal. |
trackingUrl | Opcional, URL https (até 2.048 caracteres). Entra numa linha própria no fim do texto. |
images | Opcional, até 10 URLs https de imagens já hospedadas (S3 ou CDN). O servidor não baixa as imagens. |
finalize | true grava a mensagem e encerra a conversa. |
Envie ao menos um entre title, body, trackingUrl e images. A resposta é 201:
{
"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.
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).
{
"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çalho | Conteúdo |
|---|---|
X-PushTrack-Timestamp | Momento do envio, em segundos. |
X-PushTrack-Signature | sha256=<hex>: HMAC-SHA256 de "<timestamp>.<corpo bruto>" com o segredo do webhook. |
X-PushTrack-Delivery | Identificador 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).
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
$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ódigo | Quando |
|---|---|
400 | Corpo 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. |
401 | Chave ausente, inválida, girada ou de credencial desativada. |
403 | Flavor desativado. |
404 | Pedido inexistente (GET e close). |
409 | PHONE_MISMATCH, CONVERSATION_CLOSED ou REQUEST_IN_PROGRESS. |
422 | Idempotency-Key reutilizada com outro conteúdo. |
429 | Mais 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-Keyem todo envio, para poder repetir sem duplicar. - Ao receber
429, espere o tempo deRetry-Afterantes 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.