- v2.2 · actual
- v2.1 · anterior
- v2 · deprecado
- v1 · descontinuada
- v0 · descontinuada
Estás viendo el contrato actual (v2.2) de
order.cancelled. v2.2 agrega data.fiscalRepresentation: la numeración fiscal que el punto de venta obtuvo antes de inyectar la orden. Viaja siempre: en null cuando no se intentó numerar, y con contenido cuando sí —numberingStatus dice cómo terminó—. Que traiga contenido no significa que el comprobante esté autorizado. Solo aditivo — nada de lo que ya leías cambió.El bloque lleva el documento fiscal vigente de la orden: los campos que significan lo mismo en todo país arriba, los identificadores del ente dentro de countryData con el vocabulario de su país, y los documentos anteriores en history. Cuando una anulación numera, la nota de crédito pasa arriba y la factura baja al histórico — con compensates apuntando a ella.order.cancelled dispara cuando se cancela una orden previamente inyectada — desde la UI del backoffice de Fire, un adaptador externo o una llamada a la API de cancelación. No retrae un order.completed previo de la misma orden; ambos eventos se emiten independientes.
Condición de disparo
Fire emiteorder.cancelled una vez cuando el status de una orden transiciona a CANCELLED, sin importar el estado de pago previo. La cancelación se registra con contexto completo de auditoría (quién, cuándo, por qué, fuente).
Qué hay en trigger.data
Mismo snapshot V4 que order.completed — todos los campos documentados ahí están presentes acá, con tres diferencias:
statuses"CANCELLED"(no"COMPLETED").paymentStatusqueda igual a cuando la orden se completó (típicamente"SUCCEEDED"si la orden había sido pagada antes de cancelar).- Un bloque top-level nuevo
cancellationlleva la metadata de auditoría.
Ejemplo — payload real de producción (BR, sanitizado)
Referencia de data.cancellation
object
Bloque de auditoría que describe cómo, cuándo y por quién se canceló la orden.
Lifecycle relativo a otros eventos
Para una orden brasileña fiscal-enabled que se cancela, espera esta secuencia:order.cancelledse emite inmediatamente cuando ocurre la cancelación, antes de contactar cualquier autoridad fiscal externa.order.reversedse emite después — una vez que SEFAZ confirma vía tu proveedor fiscal. Puede llegar segundos o minutos después deorder.cancelled, según el tiempo de respuesta de SEFAZ.- Para órdenes no brasileñas o tiendas sin emisión fiscal, solo dispara
order.cancelled.
Variaciones por país
order.cancelled es global — dispara para todos los países y todos los canales cuando una orden se cancela (Argentina, Brasil, Chile, Colombia, Ecuador, Venezuela y cualquier otro país con Integration Flows activos). El bloque de auditoría de cancelación (cancellation.{cancellationId, cancelledAt, cancelledBy, cancellationReason, cancellationSource}) es idéntico para todos los países.
El único campo específico por país es cancellation.metadata.fiscal, que se popula solo para tiendas brasileñas que tenían un documento fiscal previamente autorizado (es decir, se emitió un order.invoiced para esta orden antes). Para todos los demás países — y para órdenes BR canceladas antes de la autorización fiscal — cancellation.metadata.fiscal es null y no seguirá ningún evento order.reversed.
Para tiendas no-BR (Argentina, Chile, Colombia, Ecuador, Venezuela, otros), el bloque cancellation se ve así:
Cancelación no-BR
data.store sí varían por país — consulta order.completed → Variaciones por país para country.code, currencyCode y storeFiscalConfig.govIdType (CNPJ / CUIT / RUT / NIT / RUC / RIF) por país.
Handler de ejemplo
data.policy y data.lastKnown
Todos los eventos de orden llevan estos dos bloques, no solo este. Se agregaron
junto con el ciclo de pago diferido y son agregados en v2.1, aditivos: los consumidores
existentes siguen funcionando sin cambios.
order.opened,
el evento donde estos bloques más importan.
Errores comunes
status === "CANCELLED", nopaymentStatus. Las órdenes pagadas canceladas mantienenpaymentStatus === "SUCCEEDED"; la cancelación vive en el campostatusmás el bloquecancellation.order.cancelled≠ refund. Fire reporta la cancelación; el refund (si lo hay) lo inicia el canal/procesador y no está en este payload.- No asumas que
order.completedllegó primero. Es posible la entrega fuera de orden — tu handler debería tolerar recibirorder.cancelledpara unorderIdque aún no conoce (p. ej. log + crea un placeholder; reconcilia cuando llegueorder.completed). cancellation.metadata.fiscales el doc original, no el resultado de cancelación. Para la confirmación SEFAZ, escuchaorder.reversed.
Eventos relacionados
order.completed
El evento que verás para la misma orden antes de la cancelación.
order.reversed
Solo Brasil — dispara cuando SEFAZ confirma la cancelación.
data.fiscalRepresentation
La numeración fiscal que el punto de venta obtuvo antes de inyectar la orden:
cobra, pide los identificadores, imprime el comprobante y recién después inyecta.
Por eso viaja en la orden y no en un evento fiscal aparte — cuando la orden nace,
esto ya ocurrió.
La clave viaja siempre. Llega en null cuando no se intentó numerar
—agregadores, países sin representación fiscal, o comercios con la numeración
desactivada— y con el bloque cuando sí se intentó.
Que traiga bloque significa que se intentó numerar, no que se numeró:
numberingStatus dice cómo terminó el intento, y failure por qué cuando no
terminó bien.
Ramificá por valor, no por presencia de la clave:
lastKnown.fiscal, que es lo que sí se mueve.
Lo que sí lo reemplaza es un documento nuevo. El bloque lleva el documento
fiscal vigente de la orden. Mientras solo hubo uno, era siempre la factura;
cuando una anulación produce una nota de crédito, arriba queda la nota —
documentType dice cuál es— y la factura baja a history, entera y con sus
propios identificadores del ente. No se pierde: se mueve. compensates apunta a
ella por su número, así que la relación entre los dos queda explícita.
Cuando la numeración falla
Una venta puede cobrarse y quedarse sin comprobante fiscal. Ese caso también viaja, y hay que contemplarlo: los identificadores vienen ennull y el motivo
en failure.
failure.scope:
TECHNICAL— imprimí “en trámite” y seguí. Puede resolverse solo.FUNCTIONAL— hay un dato mal y reintentar no lo arregla. Requiere corrección.
lastKnown.fiscal.sourceEvent ahora informa la procedencia real. Antes se
deducía del estado, y un processing sembrado al inyectar se reportaba como
fiscal.callback sin que ningún callback hubiera ocurrido. Ahora ese caso dice
order.injected. Si ramificás por este campo, contemplá el valor nuevo.