Como integrar-se com a API REST da iot.cards
A API REST da iot.cards permite gerir o ciclo de vida completo de cada SIM (ativação, desativação, suspensão, mudança de plano, alarmes, CDRs) a partir do seu próprio sistema, sem mexer no portal. Este guia descreve a integração mínima viável que 90% dos clientes implementa, com exemplos em Python e Node e notas sobre os erros que mais se repetem em produção.
- 1
Peça credenciais no portal
Aceda a Portal → Definições → API e gere um token de serviço. Associe-lhe as permissões mínimas necessárias (leitura, gestão, billing). O token é mostrado uma única vez — guarde-o no seu gestor de segredos antes de fechar o modal.
Tip: Gere um token por ambiente (dev / staging / prod). Se revogar um, não parte os outros.
- 2
Configure a autenticação
A API espera o token na cabeçalho Authorization: Bearer <token>. As chamadas não autenticadas devolvem 401 sem filtragem de informação. A quota de rate limit é 60 req/min por defeito e pode ser ampliada em planos Enterprise.
Tip: Use uma biblioteca HTTP que respeite tentativas exponenciais: 429 (rate limit) e 503 (manutenção pontual) são os únicos códigos que convém repetir automaticamente.
- 3
Liste os seus SIMs e filtre por estado
GET /v1/sims devolve uma lista paginada (cursor no cabeçalho X-Next-Cursor). Aceita filtros por status (active, suspended, terminated), country, last_seen_lt e tag. Para frotas grandes (>10k), pagine sempre — não peça a lista completa.
- 4
Ative, suspenda ou mude de plano
POST /v1/sims/<iccid>/activate, POST /v1/sims/<iccid>/suspend e POST /v1/sims/<iccid>/plan permitem gerir o ciclo de vida. As operações são idempotentes por iccid — pode repetir sem receio de dupla cobrança.
Tip: Se vai fazer 1000+ operações, use os endpoints de batch (/v1/batch/sims/activate, etc.) — são mais rápidos e reduzem o rate limit.
- 5
Subscreva eventos via webhook
POST /v1/webhooks define um URL HTTPS do seu sistema e os eventos a receber: sim.connected, sim.disconnected, sim.threshold_exceeded, billing.invoice_ready. A iot.cards assina cada payload com HMAC-SHA256 (cabeçalho X-Iotcards-Signature) — verifique a assinatura antes de processar.
Tip: Responda 2xx em menos de 5 segundos. Se a sua lógica for pesada, enfileire o evento e processe async — um webhook lento mete back-pressure no sistema.
- 6
Consulte CDRs e detalhe de tráfego
GET /v1/sims/<iccid>/cdrs devolve os registos detalhados (timestamp, país, operadora, MB consumidos). Útil para charge-back interno ou para detetar anomalias. Suporta exportação CSV via Accept: text/csv para reporting.
- 7
Trate erros e tentativas
A API usa códigos HTTP padrão: 4xx são erros do cliente (não repetir), 5xx são erros do servidor (repetir com back-off). Cada erro traz um body JSON com error.code, error.message e error.request_id — inclua o request_id em qualquer ticket de suporte.
- 8
Passe a produção com observabilidade
Antes de cortar o sistema legacy: instrumente a latência e a taxa de erro de cada chamada, defina limiares de alerta e documente o plano de fallback (o que acontece se a API estiver em baixo 30 minutos?). O portal continua sempre disponível como via manual.
Common pitfalls
- ·Fazer hardcode do token no código-fonte. Use variáveis de ambiente ou um secret manager.
- ·Não verificar a assinatura HMAC nos webhooks — um atacante pode injetar eventos falsos.
- ·Fazer polling de /v1/sims a cada 30 segundos em vez de subscrever webhooks.
- ·Não paginar listas grandes. A API trunca em 1.000 elementos por página.
- ·Repetir erros 4xx (validação, não encontrado, conflito). Só repita 429 e 5xx.
- ·Confiar que um endpoint de batch é atómico. Não é: cada SIM pode falhar individualmente.
Checklist
- ☐Token gerado por ambiente (dev/staging/prod)
- ☐Token guardado num secret manager, nunca no repo
- ☐Autenticação Bearer testada com um GET /v1/sims
- ☐Recetor de webhook a verificar a assinatura HMAC-SHA256
- ☐Tentativa exponencial implementada para 429 e 5xx
- ☐Paginação por cursor implementada para listas
- ☐Logging do request_id nos erros
- ☐Métricas de latência e taxa de erro em produção
FAQ
Há SDKs oficiais em Python ou Node?+
Há exemplos curados no GitHub que cobrem os endpoints principais. Para integração produtiva, a maioria dos clientes prefere o seu próprio cliente HTTP leve: a API é deliberadamente simples.
O que acontece se ultrapassar o rate limit?+
A API responde 429 com um cabeçalho Retry-After a indicar os segundos de espera recomendados. O seu cliente deve respeitar esse cabeçalho e repetir depois.
Os webhooks têm tentativas?+
Sim. Se o seu endpoint responder não-2xx ou ultrapassar 5 segundos, a iot.cards repete com back-off (1, 5, 30, 300, 3600 segundos) durante 24 h antes de descartar o evento. Mantenha um endpoint dedicado e rápido.
Posso limitar um token a uma sub-rede IP?+
Sim, em Portal → Definições → API → Allowed IPs. Útil quando o token vive apenas nos seus servidores e não quer que seja válido a partir de fora.
More guides