Skip to content

feat: add NFS-e invoice cancellation - #6

Open
paulodutra wants to merge 1 commit into
mainfrom
feat/nfse-cancellation
Open

paulodutra wants to merge 1 commit into
mainfrom
feat/nfse-cancellation

Conversation

@paulodutra

@paulodutra paulodutra commented Oct 20, 2026 •

Copy link
Copy Markdown

O que muda

Adiciona ao SDK o cancelamento de NFS-e, usando o endpoint POST /v1/invoices/{id}/cancel da API.

  • Novo método cancel no recurso de notas. Recebe { reason, description? } e devolve a nota atualizada no mesmo formato do get. O nome segue a convenção da linguagem (cancel, Cancel, CancelAsync).
  • Motivos de cancelamento: issue_error, service_not_provided e other, como enum, constantes ou tipo literal, conforme o padrão do SDK.
  • Modelo da nota: novos status cancelling e cancelled e quatro campos novos, todos podendo vir nulos: cancellationReason, cancellationDescription, cancelledAt e cancellationRequestedAt.
  • Webhooks: inclui nfse.invoice.cancelled e nfse.invoice.cancellation_rejected na lista de eventos, que passa de 9 para 11. Os dois estão em PUBLIC_WEBHOOK_EVENT_TYPES no backend.
  • Erros: 409 (ERROR_INVOICE_NOT_CANCELLABLE) e 422 (descrição inválida) usam o mecanismo de erro que o SDK já tinha. Nenhuma classe de erro nova.
  • Documentação: nova seção "Cancel an invoice" no README, com os motivos, a regra da descrição e um exemplo de cancelar e depois conferir o resultado pelo get. Também atualiza a tabela de recursos, os comentários de documentação e o CHANGELOG, quando o repositório tem um.

Como o usuário confere o resultado

O cancelamento pode ser assíncrono. O usuário consulta a nota com get e olha o status:

Status Significado
cancelled Cancelada (cancelledAt preenchido)
cancelling A Sefin está processando o cancelamento
processing com cancellationRequestedAt Pedido registrado; a nota será cancelada assim que for autorizada
authorized com lastErrorCode A Sefin rejeitou o cancelamento; dá para tentar de novo

Os webhooks nfse.invoice.cancelled e nfse.invoice.cancellation_rejected dão o mesmo retorno sem precisar consultar a nota.

Decisões

  • Sem idempotency key no cancel: o OpenAPI não declara esse header para o endpoint, e a API trata um pedido repetido como "o primeiro vale".
  • Sem validação no cliente: o SDK não confere o tamanho da descrição (15–255 caracteres). Quem valida é a API, que responde 422.
  • Sem helper de espera: o usuário confere o resultado pelo get ou pelos webhooks.
  • Versão sem bump.

Como testar

  1. Rodar a suíte do repositório. Os testes novos cobrem:
    • cancel com 200 (cancelled), conferindo método, path e body
    • cancel sem description: o campo fica fora do body
    • cancel com 202 (cancelling, e processing com cancellationRequestedAt)
    • cancel com 409 e 422, chegando como o erro do SDK com o código
    • get de uma nota cancelled e de uma cancelling, lendo o status e os campos novos
    • lista de eventos de webhook com os 2 eventos novos
  2. Opcional, contra a API local: emitir uma nota, chamar cancel com reason: "issue_error" e uma descrição de 15 caracteres ou mais, e consultar com get até o status ficar cancelled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paulodutra
paulodutra requested a review from pedrohrod October 20, 2026 12:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant