Cancelar pedido

Cancela un pedido del cliente autenticado. Fire spark actualiza estados, detiene un workflow de fulfillment en curso si lo hay, y notifica a las integraciones para que el POS anule el ticket. La fila del pedido permanece con status: VOIDED (nada cobrado) o status: REVERSED (hubo cobro, aunque un dispositivo ya lo haya devuelto). Sus tenders quedan CANCELLED. No se borra.

Requiere un access token de Storefront API de Intercambio de token.

En @fire-spark/storefront, llama order.cancel(). Lee el pedido, decide VOID o REVERSE, anula los cobros del dispositivo y llama una sola vez a este endpoint con los resultados. Un pedido entregado lanza error: usa order.refund(). order.cancelOrder() sigue llamando a este endpoint sin body.

La cancelación se rechaza si el pedido ya está fulfilled. Usa Reembolsar pedido dentro de las 24 horas posteriores al fulfillment.

Parámetros de ruta

Parámetro	Requerido	Descripción
`id`	Sí	Identificador externo del pedido

Body

Opcional. Sin body la llamada funciona como antes. Cada campo se valida solo si se envía.

Campo	Descripción
`device`	`{ kind: "KIOSK" \| "POS", uid, secret }`. El dispositivo que cancela. `401` con secreto incorrecto o dispositivo no vinculado, `403` si es de otro workspace. Se guarda en `metadata.cancellation`
`type`	`VOID` (nada cobrado) o `REVERSE` (hubo cobro). Debe coincidir con el pedido; si no, `422` con `details.code`
`reason`	Texto libre, se guarda en `metadata.cancellation`
`idempotency_key`	Clave de la llamada
`tenders`	Lo que hizo el dispositivo con cada cobro: `{ tender_id, attempt_reference, result: "REVERSED" \| "NOT_REVERSED", provider_reference?, metadata? }`. `REVERSED` deja el tender `CANCELLED`; `NOT_REVERSED` lo deja `PAID` con `metadata.reversal_pending`

Un pedido ya VOIDED o REVERSED responde 200 y solo toma los tenders informados; así un dispositivo que anula un cobro más tarde lo reporta con la misma llamada.

Solicitud

curl -X POST "https://firespark.cloud/api/storefront/v1/orders/ord-48291/cancel" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": { "kind": "KIOSK", "uid": "DEVICE_UID", "secret": "DEVICE_SECRET" },
    "type": "REVERSE",
    "reason": "Cliente desiste",
    "tenders": [
      { "tender_id": "tnd_1", "attempt_reference": "01M641K2", "result": "REVERSED" }
    ]
  }'

Respuesta

Devuelve 200 con el pedido anulado o revertido.

Si el pedido ya se envió al POS por order.status.changed, tu integración también recibe order.voided u order.reversed para anular el ticket de cocina.

{
  "data": {
    "id": "ord-48291",
    "status": "REVERSED",
    "fulfillment_status": "REVERSED",
    "payment_status": "CANCELLED"
  }
}

Errores

Estado	Descripción
`400`	Body mal formado o `type` desconocido
`401`	Token ausente o inválido, o `device` con secreto incorrecto o no vinculado
`403`	`device` de otro workspace (`DEVICE_SCOPE_MISMATCH`)
`404`	Pedido no encontrado
`422`	Pedido ya fulfilled (`ORDER_FULFILLED`) o no cancelable; `type` no coincide (`ORDER_CAPTURED`, `ORDER_NOT_CAPTURED`, `TYPE_STATUS_MISMATCH`, `TYPE_ENDPOINT_MISMATCH`); tender informado desconocido (`TENDER_NOT_FOUND`, `TENDER_NOT_DEVICE`, `TENDER_ATTEMPT_MISMATCH`)

Documentación de API

Endpoints

Guías

Recursos

Parámetros de ruta

Body

Solicitud

Respuesta

Errores

​Parámetros de ruta

​Body

​Solicitud

​Respuesta

​Errores

Parámetros de ruta

Body

Solicitud

Respuesta

Errores