APIs de Importador (Beta)

​

URL base y autenticación

https://api.tread-horizon.com/ingest

Authorization: Bearer <access_token>

Content-Type: application/json

{
  "orders": [ /* ... */ ],
  "metadata": { "source_system": "ERP", "batch_id": "2025-06-02-001" }
}

​

El modelo asincrónico

• Reports > API Integrations en la app Tread. Muestra Imported For, Import Received At, State, Last Error, y el payload sin procesar que enviaste. Por defecto los últimos 7 días, los más recientes primero.
• Webhooks de error, si has configurado uno. Tread empuja un evento cuando un payload falla al procesarse. Consulta Webhooks.

​

Pedidos

​

Campos requeridos

​

Solicitud de ejemplo

curl -X POST https://api.tread-horizon.com/ingest/orders \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

{
  "orders": [
    {
      "external_id": "ORD-2025-0142",
      "load_at": "2025-06-02T07:30:00",
      "customer": { "external_id": "CUST-441", "name": "Acme Aggregates" },
      "material": { "external_id": "MAT-GRAVEL-34" },
      "sites": [
        { "waypoint": "pickup", "external_id": "SITE-QUARRY-1", "full_address": "4500 Quarry Rd, Denver, CO" },
        { "waypoint": "drop_off", "external_id": "SITE-JOB-19", "full_address": "800 Main St, Denver, CO" }
      ],
      "truck_count": 4,
      "service": "Hired Truck"
    }
  ]
}

​

Notas de comportamiento

• La coincidencia es por external_id, limitada a tu empresa. Una coincidencia actualiza los campos raíz del pedido — nombre, cantidades, tarifas, notas, y más.
• customer, material, equipment_type, y sites son registros anidados. Tread los crea si no existen pero no los actualiza en una coincidencia — consulta coincidencia external_id.
• foremen y vendors son arrays. Cada payload reemplaza el array completo — no se fusiona con lo que ya está allí. Esto es verdad incluso si omites el campo: omitir foremen no preserva los foremen existentes. Envía el conjunto completo cada vez.
• Si un pedido se cancela y luego envías un payload con el mismo external_id en un estado no cancelado, Tread renombra el external_id del pedido cancelado a X-{N} y crea un nuevo pedido. Esto es automático — no se necesita limpieza de tu parte.

​

Proyectos

​

Campos requeridos

​

Solicitud de ejemplo

curl -X POST https://api.tread-horizon.com/ingest/projects \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

{
  "projects": [
    {
      "external_id": "PRJ-2025-014",
      "name": "Highway 401 Resurfacing",
      "effective_at": "2025-05-01T00:00:00",
      "customer": { "external_id": "CUST-441", "name": "Acme Aggregates" },
      "phases": [
        { "name": "Mobilization", "code": "PH-01" },
        { "name": "Paving", "code": "PH-02" }
      ],
      "materials": [
        { "external_id": "MAT-ASPHALT-12", "total_quantity": 2500, "unit_of_measure": "Ton" }
      ]
    }
  ]
}

​

Notas de comportamiento

• La coincidencia es por external_id. Una coincidencia actualiza campos raíz — nombre, fechas, notas, tarifas.
• La sincronización de fases es destructiva. Cada payload reemplaza la lista de fases completa. Una fase omitida del payload se elimina. Siempre envía el conjunto completo, no solo lo que cambió.
• La sincronización de materiales es igual. Un material omitido del payload se elimina del proyecto.
• Los sitios necesitan una dirección. Cada sitio necesita full_address o lat/lon. Si tus datos de origen solo tienen un nombre de sitio, establece full_address en ese nombre — Tread lo geocodifica automáticamente. Sin uno de estos, el sitio falla la validación y se descarta silenciosamente: el proyecto aún reporta éxito, pero ese recogida o entrega falta y no aparece error. Consulta Coordenadas de Sitios y Geocercas para el formato de coordenadas y cómo se construye la geocerca.
• foremen reemplazan en la actualización, igual que en Pedidos.
• Si el nombre de un proyecto colisiona con el nombre de otro proyecto diferente, Tread le añade -{external_id} para mantener ambos.

​

Tickets

​

Campos requeridos

​

Solicitud de ejemplo

curl -X POST https://api.tread-horizon.com/ingest/tickets \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

{
  "tickets": [
    {
      "ticket_number": "T-88213",
      "service_date": "2025-06-02T14:10:00Z",
      "quantity": 22.4,
      "unit_of_measure": "Ton",
      "truck_id": "T-101",
      "dispatch_number": "DISP-2025-0142",
      "material": { "external_id": "MAT-GRAVEL-34" },
      "customer": { "external_id": "CUST-441" }
    }
  ]
}

​

Notas de comportamiento

• Tread vincula un ticket a un pedido de dos formas: tread_order_id (directo, preferido) o dispatch_number más una fecha de inicio de trabajo coincidente (alternativa). Envía tread_order_id cuando lo tengas.
• La normalización de unit_of_measure es insensible a mayúsculas pero los valores exactos son más seguros. "tons" se convierte en "Ton", pero una cadena que el sistema no reconoce puede caer silenciosamente a la predeterminada (Ton) en lugar de error. Usa el valor enum exacto.
• site es un objeto individual en Tickets — a diferencia de Pedidos y Proyectos, donde sites es un array.

​

Archivos

​

Campos requeridos

​

Solicitud de ejemplo

curl -X POST https://api.tread-horizon.com/ingest/files \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -F "file=@/path/to/scale-ticket.jpg" \
  -F "external_id=ORD-2025-0142" \
  -F "file_attachable_type=Order" \
  -F "category=Scale Ticket (External)"

​

Notas de comportamiento

• 201 Created — el Pedido ya existe. Tread adjunta el archivo inmediatamente.
• 202 Accepted — el Pedido aún no existe. Tread almacena el archivo y lo adjunta automáticamente una vez que llega un Pedido coincidente — los archivos y pedidos pueden llegar en cualquier orden. No se necesita llamada extra.
• 422 — el archivo falló la validación (tipo incorrecto o más de 10 MB).

​

Coincidencia external_id y comportamiento de upsert

​

Referencia de enums

​

Trampa comunes

• 202 no significa que funcionó. Verifica el estado del registro importado antes de tratar un payload como completo.
• Los registros anidados no se actualizan en la coincidencia. Renombrar un cliente o material en tu payload no tiene efecto una vez que ese registro ya existe. Usa el REST API para renombrarlo.
• Los sitios sin dirección se descartan, silenciosamente. Sin full_address o lat/lon en un sitio significa que Tread lo descarta — y el Proyecto u Orden aún reporta éxito. Lo mismo ocurre al enviar una coordenada sin la otra. Consulta Coordenadas de Sitios y Geocercas.
• Los números de teléfono inválidos se descartan, silenciosamente. Un teléfono que no se normaliza a E.164 se elimina del contacto. Sin error, sin entrada de last_error.
• Los payloads duplicados se omiten, no se reprocesa. Enviar el mismo payload exacto dos veces marca el segundo como skipped. Esto es esperado, no un bug.
• La sincronización de fases elimina lo que dejas fuera. Cada payload de Proyecto reemplaza la lista de fases completa, no solo las fases que estés cambiando.
• Los foremen y vendors reemplazan, no se fusionan. Cada payload con un array foremen o vendors intercambia el todo, incluso si omites el campo.
• La unidad de medida es exigente. "tons" se normaliza a "Ton", pero una cadena que el sistema no reconoce cae silenciosamente al predeterminado (Ton) en lugar de error. Usa valores enum exactos.

​

Gestión de registros individuales

​

Continuar