1. Consigue una key
Inicia sesión y crea una key en /my/api-keys. Las keys tienen el aspecto tjk_live_… y se muestran una sola vez — guárdalas en el servidor, nunca en código de front-end.
2. Primera llamada (60 segundos)
`` curl -H "Authorization: Bearer $TRACKJET_API_KEY" \ "https://trackjet.world/api/v1/track/TJTEST-DELIVERED" ``
TJTEST-DELIVERED es una fixture de sandbox — determinista, segura e idéntica cada vez, así que tu primera llamada funciona antes de tener un envío real.
3. El envoltorio (envelope)
Cada respuesta JSON tiene la misma forma:
`` { "ok": true, "data": { … }, "meta": { "request_id": "…", "api_version": "v1" } } ``
Los errores son ok:false con un objeto de problema (code, message, status). Registra siempre meta.request_id — cítalo en las solicitudes de soporte y podremos encontrar la petición exacta.
4. Los endpoints que de verdad usarás
GET /api/v1/detect?number=…— ¿qué formato tiene este número?GET /api/v1/track/{number}— detección + transportista + superficies de seguimiento.GET /api/v1/track/{number}/stream— eventos en vivo por SSE donde existe un feed licenciado (si no, cierra honestamente conno_live_feed).GET /api/v1/carriers— el catálogo.POST /api/v1/webhooks— consulta webhooks.
La referencia completa (OpenAPI 3.1, GraphQL, EPCIS) está en /developers/api.
5. Idempotencia y reintentos
Los endpoints de escritura respetan una cabecera Idempotency-Key: reintenta con la misma key un POST que dio timeout y nunca crearás por duplicado. Los límites de tasa son por key — consulta límites y planes.
6. Límites de consultas GraphQL
El endpoint GraphQL está autenticado (envía tu clave de API) y acota cada consulta para que una consulta hostil o accidental no agote el servidor:
- Profundidad máxima: 8. Las selecciones anidadas más allá de ocho niveles se rechazan antes de ejecutarse.
- Complejidad máxima: 1000. Cada campo resuelto cuesta 1; una consulta —incluyendo campos con alias en lote— puede resolver como máximo 1000 campos. Una consulta por encima del tope se rechaza con un error de validación, no se ejecuta.
El uso de alias en lote (pedir el mismo campo muchas veces bajo alias distintos) se permite hasta ese tope de complejidad, así que una sola petición nunca puede desplegarse a trabajo ilimitado. Junto con el límite de tasa por clave (límites de tasa y planes), el rendimiento total queda acotado por complejidad × peticiones por minuto.