Saltar al contenido principal
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, órdenes, 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 un tenant 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 Generar un token de autenticación para ver la forma exacta de la solicitud, además del resto del grupo de Autenticación en la barra lateral. Para obtener credenciales M2M, escribe a developers@tread.io.

​
Encabezados obligatorios

EncabezadoObligatorioValor
AuthorizationSíBearer <token>
Content-TypeEn POST, PUT, PATCHapplication/json
AcceptNoapplication/json (predeterminado)
Accept-LanguageNoen-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" }
    ]
  }
}
HTTPcodeCuándo lo verás
400bad_requestSolicitud malformada.
401unauthorizedToken ausente o expirado.
403forbiddenEl usuario no tiene permiso para esta acción.
404object_not_foundEl recurso no existe o no es visible.
409conflictLa acción viola una regla de la máquina de estados.
415unsupported_media_typeContent-Type es incorrecto.
422unprocessable_contentLa validación falló. El arreglo errors indica el campo.
500internal_server_errorContacta a soporte.
503service_unavailableReintenta 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:
FamiliaNotas
Projects, Orders, Jobs, LoadsLa jerarquía de despacho. Un proyecto contiene órdenes. Una orden contiene trabajos. Un trabajo es la labor de un conductor. Una carga es un ciclo.
Tickets, Timesheets, DriverDaysPrueba del trabajo. Los tickets capturan material. Los DriverDays capturan horas.
Users, Drivers, ForemenPersonas con acceso, definidas por Roles y Permisos.
SitesUbicaciones de recogida y entrega con geocercas.
Companies, CompanySharesLa empresa con la que operas, más las relaciones padre/hijo.
Equipment, EquipmentTypesCamiones y el tipo al que pertenecen. La capacidad vive en el Tipo.
Materials, MaterialRatesLo que acarreas y cómo se cotiza.
Rates, AddOns, FuelSurchargesEl modelo de precios: tarifas base, cargos, ajustes por combustible.
Settlements, InvoicesPago a conductores/proveedores y facturación a clientes.
Integrations, Telematics, AgaveConexiones a QuickBooks, Sage, Samsara, Geotab, telemetría de pavimentadoras 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: órdenes aceptadas, 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 hijas y multi-entidad

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 se establece en la creación y no puede cambiarse. 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.

Estado

Disponibilidad en vivo e historial de incidentes.