Guia direto pra integrador. Se você precisa puxar dado do Chronyx pro seu ERP, CRM ou BI, segue o caminho mais curto.
Conceitos básicos
Duas formas de pegar dado: pull (você pergunta, a API responde) e push (a API te avisa quando algo acontece via webhook). Use pull pra dados que mudam pouco (lista de veículos), push pra eventos em tempo real (frenagem, cerca, alarme).
Pegando a chave
Painel → Configurações → API. Cria chave nova, define escopo (read-only ou full), copia o token. Formato: cnyx_live_ seguido de string aleatória. Guarda no cofre de segredos, nunca commita em repositório.
Primeira chamada (curl)
Pra confirmar que sua chave funciona, bate em /v1/positions/latest. Retorna a última posição de cada veículo da frota. Header: Authorization: Bearer SUA_CHAVE.
Estrutura típica de integração
Cenário comum: você quer que cada nova posição GPS apareça no painel do seu ERP. Caminho:
- Você expõe um endpoint POST no seu sistema, ex: /webhooks/chronyx
- Configura no painel Chronyx: URL de webhook + eventos desejados (position.update)
- Cada nova posição chega como JSON no seu endpoint, assinada com HMAC-SHA256
- Sua aplicação valida a assinatura e processa
Validando assinatura do webhook
Todo webhook chega com header X-Chronyx-Signature: sha256=... Você calcula o HMAC do body usando seu webhook secret e compara. Se bate, é a gente. Se não bate, descarta — pode ser tentativa de injeção.
Paginação
Endpoints de listagem usam cursor-based pagination. Resposta inclui next_cursor — você passa ele no próximo request via query param. Não confunda com page/offset (que não usamos). Vantagem: estável mesmo se a base crescer durante a paginação.
Rate limits
Plano Free: 60 requests/min. Plano Pro: 600/min. Cabeçalho de resposta inclui X-RateLimit-Remaining. Se estourar, recebe HTTP 429 com Retry-After. Implementa backoff exponencial.
Idempotência
Todo POST aceita header Idempotency-Key. Reentrega de webhook não duplica nada — você guarda o ID do evento e ignora se já viu. Padrão da indústria, evita bug grosseiro.
“Webhook que não valida assinatura e não tem idempotência é problema esperando pra acontecer.”
Exemplos completos
A documentação completa em /recursos/api-docs tem exemplos de payload, schemas OpenAPI e snippets em Node.js e Python. Se você precisar do Postman collection ou de sandbox dedicado, fala com o time pelo /contato.