> ## Documentation Index > Fetch the complete documentation index at: https://docs.tread.ai/llms.txt > Use this file to discover all available pages before exploring further. # Introducción > Construye sobre Tread Horizon, el sistema operativo para el transporte de materiales a granel. 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](mailto: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`. ```bash theme={null} Authorization: Bearer ``` 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](mailto:developers@tread.io). ## Encabezados obligatorios | Encabezado | Obligatorio | Valor | | ----------------- | ------------------------- | ---------------------------------------------------------- | | `Authorization` | Sí | `Bearer ` | | `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`. ```bash theme={null} 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: ; 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. ```json theme={null} { "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](mailto:support@tread.io). | | 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](/es/concepts/orders-projects), Jobs, Loads | La jerarquía de despacho. Un Proyecto contiene Pedidos. Un Pedido contiene Trabajos. Un Trabajo es la labor de un [Conductor](/es/concepts/driver-lifecycle). Una Carga es un ciclo. | | [Tickets](/es/concepts/tickets-timesheets), 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](/es/concepts/roles-permissions). | | [Sites](/es/concepts/sites-geofences) | Ubicaciones de recogida y entrega con geocercas. | | [Companies](/es/concepts/companies-hierarchy), 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](/es/concepts/equipment) | Registros individuales de camión o remolque. La capacidad y la unidad de medida viven en el Equipment Type. | | [Materials, MaterialRates](/es/concepts/materials) | El registro de Material para lo que mueve un Pedido. Un MaterialRate cotiza un Material. | | [Rates, AddOns, FuelSurcharges](/es/concepts/rates-add-ons) | El modelo de precios: Tarifas base, Add-Ons y recargos por combustible. | | [Settlements](/es/concepts/settlements-driver-pay), 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](/es/integrations/quickbooks), [Sage](/es/integrations/sage), Vista, Foundation, Spectrum), [telemática](/es/integrations/telematics) (Samsara, Geotab), [Paver Tracker](/es/integrations/paver-tracker) y [HCSS](/es/integrations/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](/es/integrations/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](/es/concepts/companies-hierarchy). 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. ```bash theme={null} curl https://api.tread-horizon.com/v1/companies/{company-id}/projects \ -H "Authorization: Bearer $TREAD_TOKEN" \ -H "Accept: application/json" ``` Respuesta de ejemplo: ```json theme={null} { "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 Inicia sesión e intercambia credenciales por un token bearer. Suscríbete a eventos y recíbelos en tiempo real. Inicia sesión en la plataforma que respalda esta API. Carga masiva de Órdenes, Proyectos, Tickets y Archivos con endpoints de ingest asíncronos. Disponibilidad en vivo e historial de incidentes.