La API de Trackberry

Objetivo #

Leer los datos de envíos de su organización desde un script, una herramienta de hojas de cálculo, un panel de BI o su propio sistema, sin exportar archivos a mano.

La API es de solo lectura. Devuelve lo que usted ya ve en Trackberry, en formato JSON, para una organización a la vez. Los envíos se siguen creando y modificando por correo electrónico, mediante carga de archivos o en la aplicación.

Para agentes de IA y generadores de código #

Toda la API se describe en un único archivo OpenAPI 3.1 que no requiere token: https://trackberry.com/api/v1/openapi.json. Entregue esa URL a su agente de programación, o cárguela en un generador de código o en un cliente de API como Postman o Insomnia, y tendrá cada endpoint, parámetro, valor de enumeración y campo, cada uno con una descripción en lenguaje sencillo de lo que significa para el negocio (por ejemplo, en qué se diferencian effective_eta, eta, original_eta y predicted_eta). Siempre describe la versión más reciente de la API.

Algunos datos útiles antes de generar código:

• Todos los campos están siempre presentes. Un campo sin valor es null, nunca falta, así que declare tipos que admitan nulos en lugar de tipos opcionales.
• Ignore los campos y valores de enumeración que no reconozca. Los nuevos se agregan sin crear una versión nueva.
• Las listas de envíos, alertas y verificaciones se paginan con limit y starting_after; las demás listas no se paginan.
• El archivo también está enlazado desde llms.txt, para los agentes que empiezan por ahí.

El resto de esta página es el mismo contrato, escrito para personas.

Crear un token #

1. Vaya a Configuración → Tokens de API (/your-slug/settings/api).
2. Haga clic en Crear token, asígnele un nombre que indique dónde se usará (“Actualización de Power BI”, “Sincronización ERP”) y elija cuándo vence.
3. Copie el token. Se muestra una sola vez. Trackberry solo guarda una huella del token, así que nadie, ni siquiera nuestro equipo, puede volver a mostrárselo. Si lo pierde, revóquelo y cree uno nuevo.

Un token le pertenece a usted y a una organización. Puede leer todo lo que usted puede leer en esa organización, y nada más. Cualquier miembro puede crear tokens para sí mismo; los administradores y propietarios pueden ver y revocar todos los tokens de la organización.

Puede tener hasta 10 tokens activos por organización. Los tokens vencidos y revocados no cuentan. Si intenta crear el número 11, el formulario muestra “Ya tiene 10 tokens activos para esta organización. Revoque uno primero.” Haga clic en Revocar junto a un token que ya no use y vuelva a intentarlo.

Un token deja de funcionar cuando:

• vence (en 30 días, 90 días, 1 año o nunca, según lo que elija al crearlo),
• alguien lo revoca en la configuración,
• usted sale de la organización o lo retiran de ella.

Los tokens empiezan con tb_ seguido de 40 letras y dígitos. Si usa un escáner de secretos, este patrón los detecta: \btb_[A-Za-z0-9]{40}\b. Trate un token como una contraseña: guárdelo en su gestor de secretos, nunca en una celda de una hoja de cálculo ni en un repositorio público.

Hacer una solicitud #

La URL base es https://trackberry.com/api/v1. Envíe el token en el encabezado Authorization:

curl https://trackberry.com/api/v1/organization \
  -H "Authorization: Bearer tb_your_token"

{
  "object": "organization",
  "id": "org_42",
  "name": "Fresh Imports Ltd",
  "slug": "fresh-imports",
  "api_version": "2026-10-01",
  "token": { "id": "tok_7", "name": "ERP sync", "scopes": ["read"], "expires_at": "2027-09-29T10:00:00Z", "user_email": "you@freshimports.com" }
}

Las URL no llevan el slug de la organización: el token ya indica qué organización está leyendo.

Versiones #

La API está versionada, así que una integración que escriba hoy seguirá funcionando a medida que la API crezca.

• Cada versión lleva el nombre del día en que se publicó, por ejemplo 2026-10-01.
• Su organización queda fijada en la versión más reciente la primera vez que llama a la API sin un encabezado Trackberry-Version. Todas las respuestas posteriores usan ese formato hasta que un administrador pase la organización a una versión más nueva desde Configuración → Tokens de API.
• Para probar una versión más nueva antes de cambiar, envíela en una sola solicitud: Trackberry-Version: 2026-10-01. Eso no cambia la versión fijada.
• Las respuestas correctas incluyen un encabezado Trackberry-Version con la versión con la que se generaron.

Los campos nuevos, los endpoints nuevos y los valores nuevos en una lista de estados se agregan a todas las versiones, así que su código debe ignorar los campos que no reconozca. Todo lo que elimine un campo, le cambie el nombre o cambie su significado recibe una versión nueva, y el registro de cambios explica qué cambió y cómo adaptarse.

ID, listas y formatos #

• Los ID son cadenas con un prefijo que indica el tipo de objeto: shp_ para envíos, ctr_ contenedores, doc_ documentos, alr_ alertas, chk_ verificaciones, pkl_ listas de empaque, lbl_ etiquetas, org_ organizaciones, tok_ tokens, leg_ tramos de ruta, evt_ eventos de seguimiento, eta_ revisiones de ETA, plt_ pallets y pln_ líneas de empaque. Trátelos como opacos y devuélvalos exactamente como los recibió. Un ID con el prefijo incorrecto, o de otra organización, da un 404 cuando está en la ruta.
• Las listas llegan como { "object": "list", "data": [...], "has_more": true }, de la más reciente a la más antigua. Pida hasta 100 elementos con limit (25 por defecto). Para obtener la página siguiente, pase el id del último elemento recibido como starting_after, y deténgase cuando has_more sea false. Los elementos que llegan mientras pagina no causan huecos ni repeticiones.
• Las horas están en UTC en formato ISO 8601 (2026-09-29T14:03:00Z); los días calendario son 2026-09-29. Los filtros aceptan ambos.
• Los pesos están en kilogramos (net_weight_kg), las temperaturas en grados Celsius (temperature_celsius) y los estados son cadenas en minúsculas (in_transit).
• Los campos sin valor son null, nunca faltan. Las listas vacías son [].

Endpoints #

Todos los endpoints son GET.

Buscar envíos #

/shipments acepta estos parámetros, todos opcionales:

curl "https://trackberry.com/api/v1/shipments?status=in_transit&eta_before=2026-10-07" \
  -H "Authorization: Bearer tb_your_token"

Errores #

Los errores tienen un solo formato, sea cual sea el problema:

{ "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "limit must be an integer between 1 and 100", "param": "limit" } }

Límites #

Cada token puede hacer 600 solicitudes cada 5 minutos, más que suficiente para una sincronización que se ejecuta cada pocos minutos. Las solicitudes desde una misma dirección IP tienen un tope de 1,200 cada 5 minutos sumando todos los tokens, y las solicitudes sin ningún token (incluida la descarga de openapi.json) tienen un tope de 30 cada 5 minutos por dirección IP. Cuando alcanza un límite, recibe un 429 con un encabezado Retry-After.

Referencia de endpoints #

Toda solicitud acepta el encabezado opcional Trackberry-Version descrito en Versiones. Cada cuerpo de respuesta de abajo muestra todos sus campos: un campo sin valor es null, nunca falta. Las horas están en UTC. Las respuestas correctas llevan un encabezado Trackberry-Version, y también lo lleva un 404 o un 400 causado por un parámetro. Los errores tienen el formato descrito en Errores.

Obtener la organización y el token detrás de la solicitud #

GET /organization (operación get_organization)

Úselo primero para comprobar que un token funciona y para saber qué organización lee, en qué versión de la API está fijada esa organización y cuándo vence el token. Es de solo lectura y no consume casi nada.

Sin parámetros.

Ejemplo de respuesta, 200:

{
  "object": "organization",
  "id": "org_42",
  "name": "Fresh Imports Ltd",
  "slug": "fresh-imports",
  "api_version": "2026-10-01",
  "token": {
    "id": "tok_7",
    "name": "ERP sync",
    "scopes": [
      "read"
    ],
    "expires_at": "2027-09-29T10:00:00Z",
    "user_email": "you@freshimports.com"
  }
}

Errores: 400, 401, 429.

Listar y buscar envíos #

GET /shipments (operación list_shipments)

Úselo para encontrar envíos, sincronizar toda su cartera o responder preguntas como “qué llega la próxima semana” (eta_after y eta_before) o “qué envíos están en tránsito” (status). Del más reciente al más antiguo, con paginación por cursor. Los envíos que aún esperan aprobación nunca aparecen. Los envíos archivados se excluyen salvo que archived indique lo contrario. Cada elemento es el objeto de envío completo, igual que en get_shipment. Todos los parámetros son opcionales y se combinan con AND.

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "shipment",
      "id": "shp_812",
      "reference": "SHIP-20260915-K7QX",
      "erp_reference": "PO-88231",
      "transport_reference": "MEDURU156671",
      "transport_reference_type": "bill_of_lading",
      "transport_type": "ocean",
      "load_type": null,
      "house_bl": null,
      "forwarder_reference": null,
      "forwarder_eta": null,
      "cargo_type": "reefer",
      "temperature_celsius": 2.0,
      "status": "in_transit",
      "archived": false,
      "archived_at": null,
      "validated_at": "2026-09-16T08:30:00Z",
      "approved_at": "2026-09-15T12:05:00Z",
      "origin": {
        "location": "Callao",
        "country": "Peru",
        "timezone": "-05:00"
      },
      "destination": {
        "location": "Rotterdam",
        "country": "Netherlands",
        "timezone": "+02:00"
      },
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z",
      "effective_eta": "2026-10-05T06:00:00Z",
      "original_eta": "2026-10-02T06:00:00Z",
      "predicted_eta": null,
      "carrier": {
        "name": "MSC",
        "scac": "MSCU"
      },
      "tracking": {
        "state": "available",
        "status": "in_transit",
        "unavailable_reason": null,
        "halted_reason": null,
        "last_tracked_at": "2026-09-29T09:41:00Z",
        "carrier_updated_at": "2026-09-29T06:12:00Z"
      },
      "parties": {
        "consignor": "Agro Andes SAC",
        "consignee": "Fresh Imports Ltd",
        "notify_party": null
      },
      "produce": [
        "Grapes"
      ],
      "organic": false,
      "cargo": {
        "pallets": 20,
        "boxes": 2400,
        "net_weight_kg": 9600.0,
        "gross_weight_kg": 10320.0
      },
      "containers": [
        {
          "object": "container",
          "id": "ctr_1301",
          "number": "MSCU1234567",
          "seal_number": "ES123456",
          "vessel": "MSC AURORA",
          "voyage": "2609W",
          "port_of_loading": "Callao",
          "port_of_discharge": "Rotterdam",
          "etd": "2026-09-10T18:00:00Z",
          "eta": "2026-10-05T06:00:00Z",
          "cargo_type": "reefer",
          "temperature_celsius": 2.0
        }
      ],
      "labels": [
        {
          "object": "label",
          "id": "lbl_3",
          "name": "Priority",
          "color": "red",
          "color_hex": "#ef4444"
        }
      ],
      "checks": {
        "total": 6,
        "passed": 4,
        "failed": 1,
        "warnings": 1,
        "skipped": 0,
        "pending": 0
      },
      "notes": null,
      "created_at": "2026-09-15T12:00:00Z",
      "updated_at": "2026-09-29T09:41:00Z"
    }
  ]
}

Errores: 400, 401, 429.

Obtener un envío #

GET /shipments/{id} (operación get_shipment)

Úselo cuando ya tiene el ID de un envío y quiere su estado actual: estado, ETA, ruta, naviera o transportista, salud del seguimiento, partes, producto, totales de carga, contenedores, etiquetas y conteo de verificaciones. Los envíos archivados también se encuentran. Para los eventos de seguimiento y el historial de ETA, use get_shipment_timeline; para la demora y la detención, use get_shipment_free_time.

Ejemplo de respuesta, 200:

{
  "object": "shipment",
  "id": "shp_812",
  "reference": "SHIP-20260915-K7QX",
  "erp_reference": "PO-88231",
  "transport_reference": "MEDURU156671",
  "transport_reference_type": "bill_of_lading",
  "transport_type": "ocean",
  "load_type": null,
  "house_bl": null,
  "forwarder_reference": null,
  "forwarder_eta": null,
  "cargo_type": "reefer",
  "temperature_celsius": 2.0,
  "status": "in_transit",
  "archived": false,
  "archived_at": null,
  "validated_at": "2026-09-16T08:30:00Z",
  "approved_at": "2026-09-15T12:05:00Z",
  "origin": {
    "location": "Callao",
    "country": "Peru",
    "timezone": "-05:00"
  },
  "destination": {
    "location": "Rotterdam",
    "country": "Netherlands",
    "timezone": "+02:00"
  },
  "etd": "2026-09-10T18:00:00Z",
  "eta": "2026-10-05T06:00:00Z",
  "effective_eta": "2026-10-05T06:00:00Z",
  "original_eta": "2026-10-02T06:00:00Z",
  "predicted_eta": null,
  "carrier": {
    "name": "MSC",
    "scac": "MSCU"
  },
  "tracking": {
    "state": "available",
    "status": "in_transit",
    "unavailable_reason": null,
    "halted_reason": null,
    "last_tracked_at": "2026-09-29T09:41:00Z",
    "carrier_updated_at": "2026-09-29T06:12:00Z"
  },
  "parties": {
    "consignor": "Agro Andes SAC",
    "consignee": "Fresh Imports Ltd",
    "notify_party": null
  },
  "produce": [
    "Grapes"
  ],
  "organic": false,
  "cargo": {
    "pallets": 20,
    "boxes": 2400,
    "net_weight_kg": 9600.0,
    "gross_weight_kg": 10320.0
  },
  "containers": [
    {
      "object": "container",
      "id": "ctr_1301",
      "number": "MSCU1234567",
      "seal_number": "ES123456",
      "vessel": "MSC AURORA",
      "voyage": "2609W",
      "port_of_loading": "Callao",
      "port_of_discharge": "Rotterdam",
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z",
      "cargo_type": "reefer",
      "temperature_celsius": 2.0
    }
  ],
  "labels": [
    {
      "object": "label",
      "id": "lbl_3",
      "name": "Priority",
      "color": "red",
      "color_hex": "#ef4444"
    }
  ],
  "checks": {
    "total": 6,
    "passed": 4,
    "failed": 1,
    "warnings": 1,
    "skipped": 0,
    "pending": 0
  },
  "notes": null,
  "created_at": "2026-09-15T12:00:00Z",
  "updated_at": "2026-09-29T09:41:00Z"
}

Errores: 400, 401, 404, 429.

Obtener la ruta, los eventos de seguimiento y las revisiones de ETA de un envío #

GET /shipments/{shipment_id}/timeline (operación get_shipment_timeline)

Úselo para responder “dónde está y qué pasó” y “cómo se ha movido la ETA”. Devuelve los tramos de la ruta en orden, todos los eventos de seguimiento (tanto los ocurridos como los estimados, del más antiguo al más reciente) y todas las revisiones registradas de la llegada estimada, de la más antigua a la más reciente. Sin paginación.

Ejemplo de respuesta, 200:

{
  "object": "timeline",
  "shipment_id": "shp_812",
  "legs": [
    {
      "object": "shipment_leg",
      "id": "leg_5501",
      "position": 0,
      "transport_type": "ocean",
      "carrier": "MSC",
      "transport_reference": "MEDURU156671",
      "origin": {
        "location": "Callao",
        "country": "Peru",
        "timezone": "-05:00"
      },
      "destination": {
        "location": "Rotterdam",
        "country": "Netherlands",
        "timezone": "+02:00"
      },
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z"
    }
  ],
  "events": [
    {
      "object": "tracking_event",
      "id": "evt_90211",
      "milestone": "loaded",
      "actual": true,
      "occurred_at": "2026-09-10T14:20:00Z",
      "occurred_at_local": "2026-09-10T09:20:00-05:00",
      "container_number": "MSCU1234567",
      "leg_index": 1,
      "location": {
        "name": "Callao",
        "code": "PECLL",
        "country_code": "PE"
      },
      "vessel": {
        "name": "MSC AURORA",
        "imo": "9876543",
        "voyage": "2609W"
      },
      "flight_number": null,
      "position": {
        "latitude": -12.05,
        "longitude": -77.15
      }
    },
    {
      "object": "tracking_event",
      "id": "evt_90233",
      "milestone": "arrived",
      "actual": false,
      "occurred_at": "2026-10-05T06:00:00Z",
      "occurred_at_local": "2026-10-05T08:00:00+02:00",
      "container_number": "MSCU1234567",
      "leg_index": 1,
      "location": {
        "name": "Rotterdam",
        "code": "NLRTM",
        "country_code": "NL"
      },
      "vessel": {
        "name": "MSC AURORA",
        "imo": "9876543",
        "voyage": "2609W"
      },
      "flight_number": null,
      "position": {
        "latitude": null,
        "longitude": null
      }
    }
  ],
  "eta_revisions": [
    {
      "object": "eta_revision",
      "id": "eta_4401",
      "observed_at": "2026-09-11T05:00:00Z",
      "previous_eta": null,
      "new_eta": "2026-10-02T06:00:00Z",
      "slip_seconds": null,
      "first_estimate": true,
      "backfilled": false
    },
    {
      "object": "eta_revision",
      "id": "eta_4470",
      "observed_at": "2026-09-25T05:00:00Z",
      "previous_eta": "2026-10-02T06:00:00Z",
      "new_eta": "2026-10-05T06:00:00Z",
      "slip_seconds": 259200.0,
      "first_estimate": false,
      "backfilled": false
    }
  ]
}

Errores: 400, 401, 404, 429.

Obtener los contadores de demora y detención de un envío #

GET /shipments/{shipment_id}/free_time (operación get_shipment_free_time)

Úselo para responder “cuántos días libres le quedan a este envío” o “cuánto nos costará la demora”. Devuelve un contador de demora y uno de detención por contenedor, más el contador que más importa en este momento (active_clock). Los contadores solo existen para envíos marítimos, para cada contenedor que tenga eventos de carga, descarga, salida de terminal (gate out) o devolución del vacío, y se quedan en not_started hasta que el contenedor se descarga; para cualquier otro envío, las listas de contadores están vacías y active_clock es null. Los días libres provienen del propio envío, del aviso de llegada más reciente o de las condiciones de la naviera de la organización, en ese orden (vea free_days_source).

Ejemplo de respuesta, 200:

{
  "object": "free_time_summary",
  "shipment_id": "shp_790",
  "shipment_reference": "SHIP-20260901-B2MD",
  "transport_reference": "MAEU123456789",
  "at_risk": true,
  "terms_unknown": false,
  "demurrage": [
    {
      "object": "free_time_clock",
      "kind": "demurrage",
      "container_number": "TGHU7654321",
      "state": "running",
      "free_days": 5,
      "free_days_source": "carrier",
      "free_days_basis": "calendar",
      "started_on": "2026-09-25",
      "ended_on": null,
      "last_free_day": "2026-09-29",
      "days_left": 1,
      "elapsed_days": null,
      "used_days": null,
      "overdue_days": null,
      "carrier": "Maersk"
    }
  ],
  "detention": [
    {
      "object": "free_time_clock",
      "kind": "detention",
      "container_number": "TGHU7654321",
      "state": "not_started",
      "free_days": 10,
      "free_days_source": "carrier",
      "free_days_basis": "calendar",
      "started_on": null,
      "ended_on": null,
      "last_free_day": null,
      "days_left": null,
      "elapsed_days": null,
      "used_days": null,
      "overdue_days": null,
      "carrier": "Maersk"
    }
  ],
  "active_clock": {
    "object": "free_time_clock",
    "kind": "demurrage",
    "container_number": "TGHU7654321",
    "state": "running",
    "free_days": 5,
    "free_days_source": "carrier",
    "free_days_basis": "calendar",
    "started_on": "2026-09-25",
    "ended_on": null,
    "last_free_day": "2026-09-29",
    "days_left": 1,
    "elapsed_days": null,
    "used_days": null,
    "overdue_days": null,
    "carrier": "Maersk"
  }
}

Errores: 400, 401, 404, 429.

Listar los documentos de un envío #

GET /shipments/{shipment_id}/documents (operación list_shipment_documents)

Úselo para ver qué documentación tiene Trackberry de un envío (conocimiento de embarque, lista de empaque, factura, certificados) y si cada documento se leyó correctamente. Solo se listan los documentos vigentes: se excluyen las versiones reemplazadas, los adjuntos solo de referencia y los registros internos de división de páginas. Del más antiguo al más reciente, sin paginación. Descargue un archivo con download_document_file cuando su downloadable sea true.

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "document",
      "id": "doc_301",
      "shipment_id": "shp_812",
      "type": "packing_list",
      "filename": "PL_MEDURU156671.xlsx",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "byte_size": 48211,
      "source": "email_upload",
      "parse_status": "parsed",
      "downloadable": true,
      "page_range": null,
      "data_available": true,
      "created_at": "2026-09-15T12:01:00Z",
      "updated_at": "2026-09-15T12:03:00Z"
    }
  ]
}

Errores: 400, 401, 404, 429.

Listar las listas de empaque de un envío con pallets y líneas #

GET /shipments/{shipment_id}/packing_lists (operación list_shipment_packing_lists)

Úselo para leer lo que hay físicamente en el envío: para cada lista de empaque vigente, sus totales declarados, sus pallets y las líneas de producto de cada pallet (producto, variedad, calibre, cantidad de cajas y pesos). Solo se listan las listas de empaque vigentes (no reemplazadas por un documento más nuevo), de la más antigua a la más reciente, sin paginación. Los pallets que no pertenecen a ninguna lista de empaque no se pueden consultar aquí (aunque sí cuentan en cargo.pallets del envío).

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "packing_list",
      "id": "pkl_55",
      "shipment_id": "shp_812",
      "document_id": "doc_301",
      "container_id": "ctr_1301",
      "reference": "PL-2026-0915",
      "declared_box_count": 240,
      "declared_net_weight_kg": 960.0,
      "totals": {
        "pallets": 2,
        "boxes": 240,
        "net_weight_kg": 960.0
      },
      "pallets": [
        {
          "object": "pallet",
          "id": "plt_9001",
          "pallet_number": "PAL0001",
          "container_id": "ctr_1301",
          "lines": [
            {
              "object": "packing_line",
              "id": "pln_70001",
              "line_index": 1,
              "produce_name": "Grapes",
              "produce_type": "Organic",
              "variety": "Sweet Globe",
              "calibre": "L",
              "quality_category": "Class I",
              "pack_format": "4.0 kg carton",
              "label": "Andes Gold",
              "ggn": "4049929123456",
              "box_count": 120,
              "box_weight_kg": 4.0,
              "net_weight_kg": 480.0,
              "gross_weight_kg": 522.0
            }
          ]
        },
        {
          "object": "pallet",
          "id": "plt_9002",
          "pallet_number": "PAL0002",
          "container_id": "ctr_1301",
          "lines": [
            {
              "object": "packing_line",
              "id": "pln_70002",
              "line_index": 1,
              "produce_name": "Grapes",
              "produce_type": "Organic",
              "variety": "Sweet Globe",
              "calibre": "L",
              "quality_category": "Class I",
              "pack_format": "4.0 kg carton",
              "label": "Andes Gold",
              "ggn": "4049929123456",
              "box_count": 120,
              "box_weight_kg": 4.0,
              "net_weight_kg": 480.0,
              "gross_weight_kg": 522.0
            }
          ]
        }
      ]
    }
  ]
}

Errores: 400, 401, 404, 429.

Listar los envíos cuyos días libres de demora están por agotarse o ya se agotaron #

GET /free_time/at_risk (operación list_free_time_at_risk)

Úselo para una vista diaria de “qué tengo que retirar hoy”. Devuelve un resumen de días libres por cada envío que tenga un contador de demora en marcha con 2 días o menos restantes (o ya vencido), los más urgentes primero. Solo se consideran los envíos marítimos que no están archivados, que aún no se recibieron en el almacén y que se descargaron en los últimos 45 días. Sin paginación. Los envíos con condiciones de días libres desconocidas nunca aparecen aquí; terms_unknown en get_shipment_free_time indica cuándo faltan las condiciones.

Sin parámetros.

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "free_time_summary",
      "shipment_id": "shp_790",
      "shipment_reference": "SHIP-20260901-B2MD",
      "transport_reference": "MAEU123456789",
      "at_risk": true,
      "terms_unknown": false,
      "demurrage": [
        {
          "object": "free_time_clock",
          "kind": "demurrage",
          "container_number": "TGHU7654321",
          "state": "running",
          "free_days": 5,
          "free_days_source": "carrier",
          "free_days_basis": "calendar",
          "started_on": "2026-09-25",
          "ended_on": null,
          "last_free_day": "2026-09-29",
          "days_left": 1,
          "elapsed_days": null,
          "used_days": null,
          "overdue_days": null,
          "carrier": "Maersk"
        }
      ],
      "detention": [
        {
          "object": "free_time_clock",
          "kind": "detention",
          "container_number": "TGHU7654321",
          "state": "not_started",
          "free_days": 10,
          "free_days_source": "carrier",
          "free_days_basis": "calendar",
          "started_on": null,
          "ended_on": null,
          "last_free_day": null,
          "days_left": null,
          "elapsed_days": null,
          "used_days": null,
          "overdue_days": null,
          "carrier": "Maersk"
        }
      ],
      "active_clock": {
        "object": "free_time_clock",
        "kind": "demurrage",
        "container_number": "TGHU7654321",
        "state": "running",
        "free_days": 5,
        "free_days_source": "carrier",
        "free_days_basis": "calendar",
        "started_on": "2026-09-25",
        "ended_on": null,
        "last_free_day": "2026-09-29",
        "days_left": 1,
        "elapsed_days": null,
        "used_days": null,
        "overdue_days": null,
        "carrier": "Maersk"
      }
    }
  ]
}

Errores: 400, 401, 429.

Listar las alertas de monitoreo abiertas #

GET /alerts (operación list_alerts)

Úselo para encontrar los envíos que, según el monitoreo de Trackberry, tienen un problema en este momento: seguimiento sin novedades, ETA vencida o atrasada, carga detenida en la terminal y casos similares. Solo se listan las alertas abiertas de los tipos que los clientes pueden ver, de todos los envíos (incluidos los archivados), de la más reciente a la más antigua, con paginación por cursor. Pase shipment para ver un solo envío.

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "monitoring_alert",
      "id": "alr_2210",
      "shipment_id": "shp_812",
      "shipment_reference": "SHIP-20260915-K7QX",
      "key": "eta_drift",
      "group": "schedule",
      "severity": "warning",
      "title": "ETA has slipped",
      "summary": "ETA has moved 3 days later than first quoted (2026-10-02 → 2026-10-05).",
      "since": "2026-10-02T06:00:00Z",
      "first_detected_at": "2026-09-25T03:00:00Z",
      "last_detected_at": "2026-09-29T03:00:00Z",
      "resolved_at": null
    }
  ]
}

Errores: 400, 401, 429.

Listar las verificaciones de todos los envíos #

GET /checks (operación list_checks)

Úselo para encontrar problemas de documentación y de datos: documentos faltantes, totales de la lista de empaque que no coinciden con los declarados, números de contenedor no válidos y casos similares. Por defecto solo se listan las verificaciones fallidas o con advertencia; pase status para ver otros. De todos los envíos (incluidos los archivados), del más reciente al más antiguo, con paginación por cursor. Pase shipment para ver un solo envío.

Ejemplo de respuesta, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "shipment_check",
      "id": "chk_9001",
      "shipment_id": "shp_812",
      "shipment_reference": "SHIP-20260915-K7QX",
      "key": "has_commercial_invoice",
      "category": "documents",
      "status": "warning",
      "title": "Commercial invoice",
      "message": "No commercial invoice has been received for this shipment yet.",
      "ran_at": "2026-09-29T03:00:00Z"
    }
  ]
}

Errores: 400, 401, 429.

Obtener un documento #

GET /documents/{id} (operación get_document)

Úselo para describir un documento que encontró con list_shipment_documents: su tipo, nombre de archivo, tamaño, origen, estado de procesamiento y si hay datos extraídos disponibles. download_document_file devuelve el archivo en sí. Solo se encuentran los documentos vigentes; un documento reemplazado o solo de referencia da un 404.

Ejemplo de respuesta, 200:

{
  "object": "document",
  "id": "doc_301",
  "shipment_id": "shp_812",
  "type": "packing_list",
  "filename": "PL_MEDURU156671.xlsx",
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "byte_size": 48211,
  "source": "email_upload",
  "parse_status": "parsed",
  "downloadable": true,
  "page_range": null,
  "data_available": true,
  "created_at": "2026-09-15T12:01:00Z",
  "updated_at": "2026-09-15T12:03:00Z"
}

Errores: 400, 401, 404, 429.

Descargar el archivo de un documento #

GET /documents/{id}/file (operación download_document_file)

Úselo para obtener el archivo original de un documento (el PDF, el escaneo, la hoja de cálculo o la imagen que se cargó o se envió por correo electrónico), para archivarlo o para leer lo que la extracción no cubrió. El cuerpo es el archivo, enviado como adjunto con su propio Content-Type y el nombre de archivo en Content-Disposition. Solo un documento cuyo downloadable es true tiene archivo: un documento sin archivo, o cuyo archivo no ha pasado el análisis de seguridad (porque aún se está analizando o fue bloqueado), da un 404.

curl -H "Authorization: Bearer tb_..." -OJ https://trackberry.com/api/v1/documents/doc_301/file

Errores: 400, 401, 404, 429.

Obtener los datos que Trackberry extrajo de un documento #

GET /documents/{id}/data (operación get_document_data)

Úselo para leer el contenido estructurado que Trackberry extrajo de un documento (las líneas de una lista de empaque, los totales de una factura, las partes y los días de salida y llegada de un conocimiento de embarque, los números de un certificado). Revise primero data_available en el documento, o acepte un resultado vacío: cuando no se extrajo nada, o el tipo de documento no tiene un esquema estructurado, la respuesta sigue siendo un 200 con schema en null y fields como un objeto vacío.

Ejemplo de respuesta, 200:

{
  "object": "document_data",
  "document_id": "doc_301",
  "type": "packing_list",
  "schema": "packing_list",
  "fields": {
    "packing_list_number": "PL-2026-0915",
    "exporter_name": "Agro Andes SAC",
    "exporter_port": "Callao",
    "exporter_country": "Peru",
    "importer_name": "Fresh Imports Ltd",
    "importer_country": "Netherlands",
    "total_net_weight": 960.0,
    "total_boxes": 240,
    "diagram_pallet_numbers": [],
    "container_number": "MSCU1234567",
    "line_items": [
      {
        "pallet_number": "PAL0001",
        "produce_name": "Grapes",
        "variety": "Sweet Globe",
        "size_calibre": "L",
        "quality_category": "Class I",
        "format": "4.0 kg carton",
        "label": "Andes Gold",
        "produce_type": "Organic",
        "ggn": "4049929123456",
        "number_of_boxes": 120,
        "net_weight_kg": 480.0,
        "box_weight_kg": 4.0,
        "gross_weight_kg": 522.0
      }
    ]
  }
}

Errores: 400, 401, 404, 429.

Obtener esta descripción OpenAPI #

GET /openapi.json (operación get_openapi_document)

Úselo para cargar la descripción de la API, legible por máquinas, en un agente, un generador de código o una herramienta de documentación. Es pública: no necesita token. Describe la versión más reciente de la API y no depende de la organización ni de Trackberry-Version. Cuenta para el límite por IP de las solicitudes sin token. Se puede almacenar en caché durante una hora.

Sin parámetros.

Devuelve 200 con un documento OpenAPI 3.1 en JSON (es el archivo a partir del cual se genera esta referencia).

Errores: 429.

Objetos #

Los objetos que devuelve la API llevan un campo object con el nombre de su tipo, y la mayoría tiene un id. Los objetos anidados se muestran con nombres de campo separados por puntos. La columna de tipo dice o null cuando un campo puede ser null. Place es un componente que se usa dentro de otros objetos; List y Error son los envoltorios de las listas y los errores.

Objeto Error #

El único cuerpo de error que usan todos los fallos.

Objeto List #

El envoltorio que devuelve todo endpoint de lista.

Objeto Organization #

La organización que lee un token, con el token que hizo la solicitud.

Objeto Shipment #

Una partida de mercancía: un conocimiento de embarque o una guía aérea, sus contenedores y todo lo que Trackberry sabe sobre dónde está y qué contiene.

Objeto Place #

Un origen o un destino.

Objeto Container #

Un contenedor de un envío.

Objeto Label #

Una etiqueta de color que la organización usa para agrupar envíos.

Objeto Timeline #

La ruta, los eventos de seguimiento y el historial de ETA de un envío.

Objeto ShipmentLeg #

Un tramo de la ruta planificada de un envío, por ejemplo un tramo marítimo seguido de un tramo terrestre.

Objeto TrackingEvent #

Un hito del recorrido de la carga, real o estimado.

Objeto EtaRevision #

Un cambio observado en la llegada estimada de un envío. Las revisiones solo se registran cuando la ETA se mueve 5 minutos o más.

Objeto FreeTimeSummary #

La situación de demora y detención de un envío. La demora es el cargo por dejar un contenedor en la terminal después de sus días libres; la detención es el cargo por quedarse con el contenedor vacío después de sus días libres. Solo los envíos marítimos tienen contadores.

Objeto FreeTimeClock #

Un contador de demora o de detención para un contenedor. La demora empieza con la descarga del contenedor y se detiene en la salida de la terminal (gate out) o, si no la hay, con la devolución del contenedor vacío. La detención empieza en la salida de la terminal y se detiene con la devolución del contenedor vacío. Los días se cuentan según el calendario local del puerto. Este objeto no tiene id.

Objeto MonitoringAlert #

Un problema que el monitoreo de Trackberry encontró en un envío y que sigue abierto. Una alerta se abre cuando empieza un problema, puede pasar de warning a critical y desaparece de la API una vez resuelta.

Objeto ShipmentCheck #

El resultado de una verificación ejecutada sobre un envío, por ejemplo si hay una lista de empaque o si su cantidad de cajas coincide con el total declarado.

Objeto Document #

Un archivo adjunto a un envío, como un conocimiento de embarque, una lista de empaque, una factura o un certificado, con su estado de procesamiento. La API no entrega el archivo en sí.

Objeto DocumentData #

Los datos estructurados que Trackberry extrajo de un documento. El conjunto de campos depende de schema.

Objeto PackingList #

Una lista de empaque leída de un documento, que indica lo que el exportador declara que hay en el contenedor, por pallet y línea de producto.

Objeto Pallet #

Un pallet de una lista de empaque.

Objeto PackingLine #

Una línea de producto en un pallet: una cantidad de una variedad, un calibre y un formato de empaque.

Lo que la API todavía no hace #

• Sin escritura. No puede crear envíos, aprobarlos ni cargar documentos a través de la API.
• Sin webhooks. Trackberry no puede llamar a su sistema cuando cambia un envío; consulte /shipments o /alerts periódicamente.
• Sin llamadas desde el navegador. La API es para servidores y scripts, así que no envía encabezados CORS.

Si alguna de estas funciones le permitiría avanzar, escriba a support@trackberry.com y cuéntenos qué está construyendo.