Introducción - Tread Docs

La API de Horizon es una API REST que devuelve JSON. Cumple con OpenAPI 3.0.3 y cubre los mismos datos que tu equipo administra en la app Tread Horizon: Proyectos, Pedidos, despacho, Tickets, Liquidaciones y más. Cada endpoint listado en esta referencia se genera automáticamente a partir del spec en vivo.

URL base

Todas las solicitudes van a un único host. Actualmente hay un servidor de producción.

https://api.tread-horizon.com

El acceso al sandbox se aprovisiona por cliente. Contacta a developers@tread.io para solicitar una cuenta de sandbox.

Autenticación

La API usa tokens bearer. Existen dos flujos según quién esté llamando.

Tokens de sesión de usuario: para usuarios humanos. Stytch emite un JWT de corta duración después de que un usuario inicia sesión (correo + contraseña, magic link o SSO). Úsalo cuando construyas herramientas que actúan en nombre de un usuario con sesión iniciada.
Tokens de máquina a máquina (M2M): para integraciones servidor a servidor. Tread emite un Client ID y un Client Secret. Intercámbialos en el endpoint de autenticación por un token de acceso usando el flujo de OAuth 2.0 client credentials.

Envía el token en cada solicitud como un encabezado Bearer.

Authorization: Bearer <access_token>

Los tokens expiran. Cuando obtengas un 401 unauthorized, solicita uno nuevo. Consulta Generate an auth token en el grupo de Autenticación de la barra lateral para ver la forma exacta de la solicitud. Para obtener credenciales M2M, escribe a developers@tread.io.

Encabezados obligatorios

Encabezado	Obligatorio	Valor
`Authorization`	Sí	`Bearer <token>`
`Content-Type`	En `POST`, `PUT`, `PATCH`	`application/json`
`Accept`	No	`application/json` (predeterminado)
`Accept-Language`	No	`en-ca`, `es-us` o `fr-ca`. Traduce los mensajes de error.

Un Content-Type inválido devuelve 415 unsupported_media_type. Un Accept inválido devuelve 406 not_acceptable.

Paginación

Los endpoints de listado usan paginación basada en cursor. Pasa page[limit] para definir el tamaño de página. El valor predeterminado es 25 y el máximo es 100.

GET /v1/companies/{company-id}/projects?page[limit]=25

La respuesta incluye un encabezado Link con URLs next y prev cuando existen más resultados.

Link: <https://api.tread-horizon.com/v1/companies/abc/projects?page[limit]=25&page[after]=Ij...>; rel="next"

Sigue el enlace next hasta que el encabezado ya no lo incluya. El cursor page[after] es opaco: no lo analices.

Errores

Cada respuesta de error usa el mismo envoltorio. El code refleja el estado HTTP.

{
  "error": {
    "code": "unprocessable_content",
    "errors": [
      { "model": "User", "field": "email", "message": "email is required" }
    ]
  }
}

HTTP	`code`	Cuándo lo verás
400	`bad_request`	Solicitud malformada.
401	`unauthorized`	Token ausente o expirado.
403	`forbidden`	El usuario no tiene permiso para esta acción.
404	`object_not_found`	El recurso no existe o no es visible.
409	`conflict`	La acción viola una regla de la máquina de estados.
415	`unsupported_media_type`	`Content-Type` es incorrecto.
422	`unprocessable_content`	La validación falló. El arreglo `errors` indica el campo.
500	`internal_server_error`	Contacta a soporte.
503	`service_unavailable`	Reintenta tras un breve backoff. Las solicitudes expiran a los 60 segundos.

Las respuestas 409 y 422 incluyen un arreglo errors con campos model, field y message que puedes mostrar a los usuarios finales.

Recursos

La API expone la mayor parte de lo que Horizon administra. Familias principales de recursos:

Familia	Notas
Projects, Orders, Jobs, Loads	La jerarquía de despacho. Un Proyecto contiene Pedidos. Un Pedido contiene Trabajos. Un Trabajo es la labor de un Conductor. Una Carga es un ciclo.
Tickets, DriverDays	Registros de prueba del trabajo. Un Ticket registra una Carga. Un DriverDay registra las horas de un Conductor en un turno — el Parte de horas en la app.
Users, Drivers, Foremen	Usuarios con acceso, delimitados por Roles y Permisos.
Sites	Ubicaciones de recogida y entrega con geocercas.
Companies, CompanyShares	La cuenta con la que operas y su estructura matriz/hija. Un CompanyShare es una conexión unidireccional que comparte registros entre cuentas.
Equipment, EquipmentTypes	Registros individuales de camión o remolque. La capacidad y la unidad de medida viven en el Equipment Type.
Materials, MaterialRates	El registro de Material para lo que mueve un Pedido. Un MaterialRate cotiza un Material.
Rates, AddOns, FuelSurcharges	El modelo de precios: Tarifas base, Add-Ons y recargos por combustible.
Settlements, Invoices	Una Liquidación es un lote de trabajo aprobado, listo para facturar o pagar. Las Invoices facturan a Clientes.
Integrations, Telematics, Agave	Conexiones a contabilidad (QuickBooks, Sage, Vista, Foundation, Spectrum), telemática (Samsara, Geotab), Paver Tracker y HCSS.

Cada familia tiene su propio grupo en la barra lateral izquierda. Haz clic para ver los endpoints, la forma de la solicitud y una consola de prueba.

Webhooks

Tread puede empujar eventos a tu endpoint cuando cambien registros: Pedidos aceptados, Cargas aprobadas, Tickets creados y más. Los webhooks se configuran por empresa. Consulta la página de integración de Webhooks para la configuración, el comportamiento de reintentos y el catálogo de eventos.

Empresas matrices e hijas

Una empresa puede tener una matriz. Un usuario en la matriz tiene el mismo rol y nivel de permiso en cada hija. La mayoría de los endpoints se acotan a una empresa vía la URL. Por ejemplo, GET /v1/companies/{company-id}/projects lista los Proyectos de una empresa específica. Usa la variante acotada por empresa cuando necesites leer o escribir datos dentro de una hija. parent_company_id es de solo lectura en la API. Las referencias circulares se rechazan. Lista las empresas hijas con GET /v1/companies/{company-id}/children.

Ejemplo rápido

Obtén la primera página de Proyectos para una empresa.

curl https://api.tread-horizon.com/v1/companies/{company-id}/projects \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -H "Accept: application/json"

Respuesta de ejemplo:

{
  "data": [
    {
      "id": "f0a1...",
      "name": "Highway 401 Resurfacing",
      "external_id": "PRJ-2025-014",
      "starts_on": "2025-05-01",
      "ends_on": "2025-09-30",
      "company_id": "abc...",
      "customer_id": "cust...",
      "created_at": "2025-04-12T14:22:10Z"
    }
  ]
}

Continuar

Generar un token de autenticación

Inicia sesión e intercambia credenciales por un token bearer.

Webhooks

Suscríbete a eventos y recíbelos en tiempo real.

App Tread Horizon

Inicia sesión en la plataforma que respalda esta API.

Importer APIs (Beta)

Carga masiva de Órdenes, Proyectos, Tickets y Archivos con endpoints de ingest asíncronos.

Estado

Disponibilidad en vivo e historial de incidentes.

​URL base

​Autenticación

​Encabezados obligatorios

​Paginación

​Errores

​Recursos

​Webhooks

​Empresas matrices e hijas

​Ejemplo rápido

​Continuar

Generar un token de autenticación

Webhooks

App Tread Horizon

Importer APIs (Beta)

Estado

URL base

Autenticación

Encabezados obligatorios

Paginación

Errores

Recursos

Webhooks

Empresas matrices e hijas

Ejemplo rápido

Continuar