Skip to main content
POST
Cancelar pedido (parceiros)
Cancela um pedido que você injetou, buscando-o pelo id externo que você deu a ele. Diferente do endpoint de backoffice, você não precisa guardar o nosso UUID interno.
Este endpoint executa a política de cancelamento: as regras do Fire mais as que a conta tiver configurado. Antes de tentar, você pode perguntar à Elegibilidade de cancelamento, que devolve o mesmo veredito e os mesmos code com um 200 e sem efeitos.

A ordem dos passos depende do gateway fiscal

É a parte que mais se erra ao integrar, e a única em que a ordem importa.
O comprovante é numerado pelo Fire, então o cancelamento fiscal vem primeiro:
1

Anular o comprovante

POST /api/v2/external/fiscal/numbering com operation: "CANCEL". Devolve a nota de crédito. Ver Numeração fiscal v2.
2

Cancelar o pedido

Só agora, este endpoint.
É o mesmo padrão da emissão — primeiro o fato fiscal, depois o pedido —, e por isso é fácil de lembrar: anula-se do mesmo jeito que se emite.Se você inverter os passos, este endpoint responde 409 com FISCAL_REPRESENTATION_NOT_VOIDED. Não é transitório: repetir não resolve.
O Fire resolve sozinho qual dos dois casos se aplica, pela configuração daquela conta, país e vendor. Você não precisa descobrir: se a nota de crédito se aplica a você, o 409 avisa.
string
obrigatório
Bearer <api-key> com o escopo orders:write, restrita a um vendor.
string
padrão:"es"
Idioma do motivo de uma recusa: es, en ou pt. É o mesmo parâmetro que já usam Elegibilidade e Numeração fiscal.Vai na URL:
Só afeta as regras próprias do Fire, que trazem etiquetas nos três idiomas. O texto de uma regra configurada pela conta volta exatamente como a conta escreveu, no idioma em que estiver. Sem este parâmetro, espanhol.
string
obrigatório
O id externo do pedido — o mesmo orderId que você mandou ao injetá-lo. Não é o nosso UUID interno: você não precisa guardá-lo.
string
obrigatório
O motivo. Entre 5 e 500 caracteres. Com catálogo, o texto do motivo escolhido.
string
O id do motivo dentro do catálogo. Para canais de agregador precisa sair do catálogo SAG.
string
Nota livre, até 500 caracteres. Guardada à parte do motivo.
string
O grupo. Não precisa mandar: o backend deriva.

O que uma recusa traz

Além do code, o corpo de um 409 traz o motivo pronto para exibir:
string
A manchete: o nome da regra que recusou. É o que cabe num aviso curto.
string
O porquê, longo. Só vem se a regra tiver. Viaja separado do message para que você possa exibir só a manchete quando não há espaço para mais.
O número por trás da recusa, quando a regra compara um: o limite e o valor real. Permite dizer «passou 17 minutos» sem interpretar o texto.
object
Com quais dados decidiu. É o recibo para diagnosticar, não para mostrar a uma pessoa.

Códigos de recusa

Todos saem com 409. Ramifique por code, nunca pela mensagem: o texto é para uma pessoa ler e pode mudar ou ser traduzido sem aviso.
Um 200 significa que o pedido foi cancelado. Não significa que o documento fiscal já esteja anulado: com gateway você fez isso no passo anterior, e com emissão nativa se resolve depois, pelo callback do provedor.