Cómo integrarte con la API REST de iot.cards
La API REST de iot.cards permite gestionar el ciclo de vida completo de cada SIM (alta, baja, suspensión, cambio de plan, alarmas, CDRs) desde tu propio sistema, sin tocar el portal. Esta guía describe la integración mínima viable que el 90% de los clientes implementa, con ejemplos en Python y Node y notas sobre los errores que más se repiten en producción.
- 1
Pide credenciales en el portal
Accede a Portal → Ajustes → API y genera un token de servicio. Asóciale los permisos mínimos necesarios (lectura, gestión, billing). El token se muestra una sola vez — guárdalo en tu gestor de secretos antes de cerrar el modal.
Tip: Genera un token por entorno (dev / staging / prod). Si revocas uno, no rompes los demás.
- 2
Configura autenticación
La API espera el token en la cabecera Authorization: Bearer <token>. Las llamadas no autenticadas devuelven 401 sin filtrado de información. La cuota de rate limit es 60 req/min por defecto y se puede ampliar en planes Enterprise.
Tip: Usa una librería HTTP que respete reintentos exponenciales: 429 (rate limit) y 503 (mantenimiento puntual) son los únicos códigos que conviene reintentar automáticamente.
- 3
Lista tus SIMs y filtra por estado
GET /v1/sims devuelve una lista paginada (cursor en el header X-Next-Cursor). Acepta filtros por status (active, suspended, terminated), country, last_seen_lt y tag. Para flotas grandes (>10k), siempre paginar — no pidas la lista completa.
- 4
Activa, suspende o cambia de plan
POST /v1/sims/<iccid>/activate, POST /v1/sims/<iccid>/suspend y POST /v1/sims/<iccid>/plan permiten gestionar ciclo de vida. Las operaciones son idempotentes por iccid — puedes reintentar sin temor a doble cobro.
Tip: Si vas a hacer 1000+ operaciones, usa los endpoints de batch (/v1/batch/sims/activate, etc.) — son más rápidos y reducen rate limit.
- 5
Suscríbete a eventos vía webhook
POST /v1/webhooks define una URL HTTPS de tu sistema y los eventos a recibir: sim.connected, sim.disconnected, sim.threshold_exceeded, billing.invoice_ready. iot.cards firma cada payload con HMAC-SHA256 (cabecera X-Iotcards-Signature) — verifica la firma antes de procesar.
Tip: Responde 2xx en menos de 5 segundos. Si tu lógica es pesada, encola el evento y procesa async — un webhook lento mete back-pressure en el sistema.
- 6
Consulta CDRs y detalle de tráfico
GET /v1/sims/<iccid>/cdrs devuelve los registros detallados (timestamp, país, operador, MB consumidos). Útil para charge-back interno o para detectar anomalías. Soporta exportación CSV via Accept: text/csv para reporting.
- 7
Maneja errores y reintentos
La API usa códigos HTTP estándar: 4xx son errores del cliente (no reintentar), 5xx son errores del servidor (reintentar con back-off). Cada error trae un body JSON con error.code, error.message y error.request_id — incluye el request_id en cualquier ticket de soporte.
- 8
Pasa a producción con observabilidad
Antes de cortar el sistema legacy: instrumenta latencia y tasa de error de cada llamada, define umbrales de alerta y documenta el plan de fallback (¿qué pasa si la API está caída 30 minutos?). El portal sigue disponible siempre como vía manual.
Errores comunes
- ·Hardcodear el token en el código fuente. Usa variables de entorno o un secret manager.
- ·No verificar la firma HMAC en los webhooks — un atacante puede inyectar eventos falsos.
- ·Hacer polling de /v1/sims cada 30 segundos en lugar de suscribirte a webhooks.
- ·No paginar listas grandes. La API trunca a 1.000 elementos por página.
- ·Reintentar errores 4xx (validación, no encontrado, conflicto). Solo reintenta 429 y 5xx.
- ·Confiar en que un endpoint de batch es atómico. No lo es: cada SIM puede fallar individualmente.
Checklist
- ☐Token generado por entorno (dev/staging/prod)
- ☐Token guardado en secret manager, nunca en repo
- ☐Autenticación Bearer probada con un GET /v1/sims
- ☐Webhook receiver verificando firma HMAC-SHA256
- ☐Reintento exponencial implementado para 429 y 5xx
- ☐Paginación por cursor implementada para listas
- ☐Logging de request_id en errores
- ☐Métricas de latencia y error rate en producción
Preguntas frecuentes
¿Hay SDKs oficiales en Python o Node?+
Hay ejemplos curados en GitHub que cubren los endpoints principales. Para integración productiva, la mayoría de clientes prefiere su propio cliente HTTP delgado: la API es deliberadamente sencilla.
¿Qué pasa si supero el rate limit?+
La API responde 429 con un header Retry-After indicando los segundos de espera recomendados. Tu cliente debe respetar ese header y reintentar después.
¿Los webhooks tienen reintentos?+
Sí. Si tu endpoint responde no-2xx o supera 5 segundos, iot.cards reintenta con back-off (1, 5, 30, 300, 3600 segundos) durante 24 h antes de descartar el evento. Mantén un endpoint dedicado y rápido.
¿Puedo limitar un token a una subred IP?+
Sí, en Portal → Ajustes → API → Allowed IPs. Útil cuando el token vive solo en tus servidores y no quieres que sea válido desde fuera.
Otras guías