Vero
DevelopersDashboard

Notas de Crédito API

Anulação e rectificação legal de facturas emitidas. Cada NC é registada na AGT em tempo real e recebe ATCUD próprio.

Emitir Nota de Crédito

POST/v1/organisations/:orgId/invoices/:invoiceId/credit-note

Emite uma NC que anula a factura original. A factura passa automaticamente para o estado cancelled. Só pode existir uma NC por factura.

Request Body

JSON
{
  "reason": "Anulação por erro de facturação"
}
reasonstring?Motivo da anulação - aparece no PDF da NC

Resposta (201 Created)

JSON
{
  "id": "e5f6g7h8-...",
  "number": "NC NC6326S37645N/1",
  "displayCode": "081D93",
  "status": "issued",
  "invoiceId": "a1b2c3d4-...",
  "subtotal": 13157895,
  "taxAmount": 1842105,
  "total": 15000000,
  "currency": "AOA",
  "atcud": "NC6326S37645N-1",
  "hash": "7mR3Kp...",
  "previousHash": "0",
  "jwsSignature": "eyJhbGciOiJSUzI1NiJ9...",
  "pdfUrl": "https://storage.vero.ao/credit-notes/e5f6g7h8.pdf",
  "agtStatus": "pending",
  "agtErrors": null,
  "issuedAt": "2026-06-25T09:15:00.000Z"
}

Campos de Facturação Electrónica (DFe)

  • number - Número AGT certificado no formato NC {série}/{sequencial}.
  • atcud - Código único de validação AGT. Aparece no PDF com QR code verificável.
  • hash / previousHash - Cadeia de integridade dos documentos da série NC.
  • jwsSignature - Assinatura RS256 submetida à AGT.
  • agtStatus - Estado da validação: pending, validated ou rejected. A submissão à AGT ocorre em segundo plano - faz GET ao documento passado alguns segundos para confirmar o resultado final.
  • agtErrors - Lista de erros devolvidos pela AGT quando agtStatus é rejected.

Notas de crédito de adiantamento

Quando uma factura final desconta uma Factura de Adiantamento (FA), o Vero emite sozinho uma NC sobre a FA, como manda o Decreto Presidencial 71/25 (art. 8.º n.º 10). Aparece emGET /credit-notes com kind: "advance", invoiceId = a FA eregularizedInvoiceId = a factura final. Ao contrário das outras NC (kind: "cancel"), não anula a FA: só abate o valor descontado. Não se emite por esta rota.

Erros comuns

409credit_note_already_existsJá existe uma NC para esta factura
409advance_in_useA factura é uma FA já descontada numa factura final (regularizada por NC)
409invoice_has_advancesA factura descontou adiantamentos: a regularização já foi à AGT, não se anula aqui
400refund_requires_paid_invoicePediste devolução (refund) de uma factura que não foi paga
400invoice_not_issuedA factura não está no estado issued ou paid
404invoice_not_foundFactura não encontrada nesta organização
422agt_keys_not_configuredCredenciais AGT não configuradas na organização