> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Actualizar estado del pedido

> Reporta el siguiente estado de fulfillment desde tu POS.

Envía el siguiente estado de fulfillment de un pedido ya placed. Usa las etiquetas configuradas para este comercio (por ejemplo `PREPARING` o `DELIVERED`). Fire spark no acepta un enum fijo de cocina.

> [!NOTE]
>
> Requiere un access token con el scope `orders:write`. Consulta
> [Token](https://firespark.cloud/docs/es/integrations-api/oauth/token/post.md) para obtener un token.

## Cómo encaja en el flujo

1. Tras el checkout, Fire spark envía un [webhook](https://firespark.cloud/docs/es/integrations-api/orders/webhooks.md) cuando el pedido llega a un estado al que te suscribiste.
2. Tu POS crea el ticket cuando llega `order.status.changed` con `data.status` `injecting` (o el estado que uses para el traspaso).
3. Cada evento posterior de cocina debe hacer PATCH del **siguiente** estado de fulfillment. Fire spark actualiza el pedido y puede enviar otro webhook.
4. La llamada es asíncrona. Reclama el avance mientras el fulfillment está en `WAITING` y responde sin esperar al siguiente nodo, así que puedes llamarla desde el manejador del webhook. El pedido de la respuesta puede seguir siendo el snapshot de antes de este avance. Un `409` significa que la fila no estaba en `WAITING`.

## Cuándo llamar este endpoint

Las etiquetas de abajo son ejemplos. Usa los estados de fulfillment de **tu** comercio.

| Evento en el POS | Ejemplo de `fulfillment_status` |
| - | - |
| Ticket aceptado en cocina | `PREPARING` |
| Empaquetado / listo para retiro | `PREPARED` |
| Repartidor despachado | `DELIVERING` |
| Entregado al cliente | `DELIVERED` (puede poner también `status: COMPLETED`) |

> [!NOTE]
>
> Un pedido puede estar en más de un estado de fulfillment a la vez (por
> ejemplo cocina y delivery). Envía el siguiente estado del trabajo que
> avanzas. Los demás estados en curso siguen hasta que los actualices.

## Parámetros de ruta

| Parámetro | Requerido | Descripción |
| - | - | - |
| `id` | Sí | Identificador externo del pedido. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. |

## Cuerpo de la solicitud

| Campo | Requerido | Tipo | Descripción |
| - | - | - | - |
| `fulfillment_status` | Sí | string | Siguiente estado de fulfillment **no terminal** |
| `status` | No | string | `COMPLETED`, `VOIDED`, `REVERSED` o `REFUNDED` — se aplica cuando Fire spark entra solo a un terminal que coincida |
| `tenders` | No | object\[] | Solo con `fulfillment_status` `PAID`. Cada elemento es `{ "id": string, "completed": boolean }`. Ver [Marcar el pedido como pagado](#marcar-el-pedido-como-pagado) |

```bash theme={null}
curl -X PATCH "https://firespark.cloud/api/integrations/v1/orders/ord-48291/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_status": "PREPARING"
  }'
```

## Marcar el pedido como pagado

Mientras el pedido está en `PAYING`, envía `fulfillment_status` `PAID` cuando tu POS haya cobrado. Fire spark marca como pagados los tenders de ese paso (una captura por tender, como si marcaras cada uno como cobrado). El pedido avanza a `PAID` solo cuando todos los tenders del paso están saldados. Un canje reservado cuenta como saldado; Fire spark confirma los canjes.

* **Sin `tenders`:** se marcan como pagados todos los tenders que el paso aún espera, y el pedido avanza. Es el camino de todos a la vez.
* **Con `tenders`, y el paso tiene un solo tender:** ese tender se marca pagado si `completed` es `true`, y el pedido avanza. El mismo comportamiento de antes.
* **Con `tenders`, y el paso tiene más de un tender:** solo cambian los elementos con `completed: true`. Los que no envías se quedan como están. El pedido no avanza hasta que cada tender del paso está en `PAID`, contando los de esta llamada. Repite la misma llamada para cada tender. La última avanza el pedido. Las anteriores responden `200`, no un error.

Solo puedes marcar tenders `IDLE` o `PENDING` que cobran dinero. Un tender que ya está `PAID` no se captura otra vez. Un id desconocido, o uno que no es de este pedido, responde `404` `TENDER_NOT_FOUND`.

Mientras queden tenders pendientes, la respuesta trae el pedido en `data` y además:

```json theme={null}
{
  "message": "Tender updated. 2 tenders still pending to reach PAID.",
  "tenderUpdated": true,
  "pendingTenders": 2,
  "targetState": "PAID",
  "transitioned": false
}
```

`pendingTenders` es una cantidad. Si queda uno, el mensaje dice "1 tender still pending". Cuando la llamada que completa el conjunto avanza el pedido, los mismos campos vuelven con `pendingTenders` `0`, `transitioned` `true` y el mensaje `Tender updated. Order transitioned to PAID.`

Actualizar solo un tender no envía un webhook del pedido ni un evento de realtime. Esos salen solo cuando el pedido sí avanza, después de que ese paso terminó su propio trabajo.

```bash theme={null}
curl -X PATCH "https://firespark.cloud/api/integrations/v1/orders/ord-48291/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_status": "PAID",
    "tenders": [{ "id": "tnd_cash01", "completed": true }]
  }'
```

Repetir la misma solicitud es seguro: cada intento de un tender se captura una sola vez. La respuesta trae el pedido actual. El avance es asíncrono, así que ese body puede seguir siendo el snapshot de antes del estado que acabas de enviar.

> [!NOTE]
>
> Combina este endpoint con los [webhooks de pedidos](https://firespark.cloud/docs/es/integrations-api/orders/webhooks.md):
> el webhook entrega el pedido cuando llega a un estado suscrito; este endpoint
> es cómo tu POS reporta el resto del camino en cocina. No envíes un estado
> terminal (`FULFILLED`, `VOIDED`, `REVERSED`, `REFUNDED`) — esos nodos se
> entran solos. Tras el último estado de cocina o entrega (por ejemplo
> `DELIVERED`), Fire spark entra a `FULFILLED`. Si un callback agota los
> reintentos, entra a `VOIDED` (sin pago) o `REVERSED` (pagado). Cancelar y
> reembolsar desde el dashboard sí llegan a esos terminales.

## Errores

| Estado | Descripción |
| - | - |
| `401` | Token ausente o inválido |
| `403` | El token no incluye el scope `orders:write` |
| `404` | No existe pedido con este id, o `TENDER_NOT_FOUND` para un id desconocido en `tenders` |
| `409` | El pedido no está esperando el siguiente estado. Con `PAID`: `PAYMENT_NOT_SETTLED` si omites `tenders` y un tender no se puede marcar, o si el pedido no está en `PAYING` y un tender sigue sin pagar. `TENDER_NOT_MARKABLE` si el tender no está `IDLE` / `PENDING`. Nombrar algunos tenders en un paso con varios no devuelve este error mientras otros sigan pendientes |
| `422` | `fulfillment_status` es un estado terminal, o no es un siguiente paso válido |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.