Eventos

Cada evento que OrderFast envía a tu endpoint sigue una estructura consistente. En v2, todos los payloads incluyen api_version: "v2" para que tu ERP pueda distinguirlos de eventos de otras versiones.

Estructura base

Campo	Tipo	Descripción
`id`	`string`	Identificador único del evento (ej. `evt_01J...`)
`type`	`string`	Tipo de evento (ej. `order.created`)
`api_version`	`string`	Siempre `"v2"`
`created_at`	`string`	Fecha ISO-8601 en que ocurrió el evento
`location_id`	`string`	UUID de la location donde ocurrió
`data`	`object`	Payload del recurso afectado

{
  "id": "evt_01J...",
  "type": "order.created",
  "api_version": "v2",
  "created_at": "2026-07-07T12:00:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {}
}

Catálogo de eventos

Órdenes

Evento	Cuándo se dispara
`order.created`	Se crea una nueva orden
`order.updated`	Se modifica una orden existente
`order.cancelled`	Una orden es cancelada
`order.completed`	Una orden se completa
`order.status_changed`	Cambia el estado de una orden (más granular que `order.updated`)

Pagos

Evento	Cuándo se dispara
`payment.created`	Se registra un nuevo pago
`payment.updated`	Se actualiza un pago
`payment.completed`	Un pago se confirma como completado
`payment.rejected`	Un pago es rechazado

Catálogo e inventario

Evento	Cuándo se dispara
`product.created`	Se crea un producto
`product.updated`	Se actualiza un producto
`product.deleted`	Se elimina un producto
`stock.updated`	Cambia el stock de un producto
`catalog.updated`	Se publica o modifica el catálogo completo

Sync y operaciones

Evento	Cuándo se dispara
`sync.completed`	Un job batch de sincronización termina exitosamente
`sync.failed`	Un job batch de sincronización falla
`turn.closed`	Se cierra un turno operativo
`settlement.created`	Se genera un settlement de conciliación

Ejemplos de payloads

sync.completed

Se dispara cuando un sync job termina. Revisá failed_items para detectar ítems que no se sincronizaron.

{
  "id": "evt_01JSYNCCOMPLETED",
  "type": "sync.completed",
  "api_version": "v2",
  "created_at": "2026-07-07T12:00:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {
    "job_id": "sync_123",
    "status": "completed",
    "total_items": 100,
    "success_items": 98,
    "failed_items": 2
  }
}

sync.failed

Se dispara cuando un sync job falla completamente. Usalo para alertar al operador y reintentar.

{
  "id": "evt_01JSYNCFAILED",
  "type": "sync.failed",
  "api_version": "v2",
  "created_at": "2026-07-07T12:05:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {
    "job_id": "sync_123",
    "status": "failed",
    "total_items": 100,
    "success_items": 0,
    "failed_items": 100,
    "error": "Validation failed for batch"
  }
}

catalog.updated

Se dispara cuando se publica o modifica el catálogo. Invalidá tu cache local y volvé a consultar GET /v2/catalog si necesitás el estado completo.

{
  "id": "evt_01JCATALOGUPDATED",
  "type": "catalog.updated",
  "api_version": "v2",
  "created_at": "2026-07-07T11:00:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {
    "version": 4,
    "published_at": "2026-07-07T11:00:00.000Z"
  }
}

order.status_changed

Se dispara cuando cambia el estado de una orden. Más específico que order.updated — ideal para ERPs que reaccionan a transiciones de estado.

{
  "id": "evt_01JSTATUSCHANGED",
  "type": "order.status_changed",
  "api_version": "v2",
  "created_at": "2026-07-07T12:30:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {
    "id": "ord_123",
    "previous_status": "pending",
    "status": "ready",
    "external_id": "erp-order-5001"
  }
}

settlement.created

Se dispara al generar un settlement de conciliación financiera.

{
  "id": "evt_01JSETTLEMENT",
  "type": "settlement.created",
  "api_version": "v2",
  "created_at": "2026-07-07T18:00:00.000Z",
  "location_id": "4f0c8810-6881-4674-96be-880fc32176a7",
  "data": {
    "id": "stl_123",
    "period_start": "2026-07-01T00:00:00.000Z",
    "period_end": "2026-07-07T23:59:59.000Z",
    "total_amount": 1250000,
    "total_orders": 342
  }
}