Vero
DevelopersDashboard

Notas de Débito API

Cobranças adicionais a um cliente - autónomas ou associadas a uma factura já emitida. Cada ND é registada na AGT em tempo real e recebe ATCUD próprio.

Emitir Nota de Débito

POST/v1/organisations/:orgId/debit-notes

Ao contrário da Nota de Crédito, a ND não exige uma factura de origem - pode ser usada para qualquer cobrança adicional a um cliente. A ND não leva IVA: pela lei, não liquida imposto (Decreto Presidencial 71/25, art. 3.º). As linhas vão a 0% como não sujeitas (M02, ou outro motivo indicado em taxExemptionCode); um pedido com taxRate 5 ou 14 é recusado. Se o valor a cobrar tem IVA, emita uma factura. Se invoiceId for indicado, o número real dessa factura é usado como referência perante a AGT (substitui qualquer valor passado em invoiceRef), evitando referências inválidas.

Request Body

JSON
{
  "customerId": "b2c3d4e5-...",
  "items": [
    {
      "description": "Custos administrativos",
      "quantity": 1,
      "unitPrice": 500000
    }
  ],
  "reason": "Cobrança de custos adicionais",
  "invoiceId": "a1b2c3d4-..."
}
customerIdstringUUID do cliente a debitar
itemsarrayLinhas do documento (descrição, quantidade, preço unitário em cêntimos). Sem IVA: taxRate omitido ou 0; taxExemptionCode opcional, por omissão M02 (não sujeita)
reasonstring?Motivo da ND - aparece no PDF
invoiceRefstring?Referência livre (ignorada se invoiceId for indicado)
invoiceIdstring?UUID de uma factura desta organização - usa o número real como referência AGT

Resposta (201 Created)

JSON
{
  "id": "f1a2b3c4-...",
  "orgId": "779b90ce-...",
  "invoiceId": "a1b2c3d4-...",
  "invoiceRef": "FT FT6326S62896N/1",
  "customerId": "b2c3d4e5-...",
  "number": "ND ND6326S15899N/2",
  "displayCode": "84A75P",
  "status": "issued",
  "subtotal": 50000000,
  "taxAmount": 0,
  "total": 50000000,
  "currency": "AOA",
  "atcud": "ND6326S15899N-2",
  "hash": "9pQ2Lr...",
  "pdfUrl": "/v1/organisations/779b90ce-.../debit-notes/f1a2b3c4-.../pdf",
  "agtStatus": "pending",
  "agtErrors": null,
  "issuedAt": "2026-07-01T10:00:00.000Z"
}

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

  • number - Número AGT certificado no formato ND {série}/{sequencial}.
  • atcud - Código único de validação AGT. Aparece no PDF com QR code verificável.
  • hash - Elo da cadeia de integridade dos documentos da série ND.
  • 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.

Listar Notas de Débito

GET/v1/organisations/:orgId/debit-notes

Devolve todas as notas de débito emitidas por esta organização, mais recentes primeiro.

Anular Nota de Débito

POST/v1/organisations/:orgId/debit-notes/:id/cancel

Para uma ND emitida por engano. A AGT só permite anular por um de dois motivos legais (DS-120 documentCancelReason; Decreto Presidencial 71/25, art. 8.º n.º 8 e 9). Se a ND já foi entregue ao cliente e os dados estão certos, não pode ser anulada.

  • A ND fica status: "cancelled", sai dos totais e relatórios, e o PDF passa a ter a marca ANULADO.
  • No SAF-T sai com estado A e fora de TotalCredit.
  • Se a ND já estava validada pela AGT, a anulação é comunicada à AGT (o mesmo documento com estado "A"). Acompanhe em agtCancelStatus: pending → validated (ou error / timeout). Sem nada a comunicar: not_required.

Request Body

JSON
{
  "reason": "I",
  "note": "emitida para o NIF errado"
}
reason'N' | 'I'Obrigatório. N: não foi enviada ao cliente · I: cliente identificado incorrectamente
notestringOpcional. Nota interna (máx. 500 caracteres)

Com o SDK (@veroao/node 1.3+)

TypeScript
const dn = await vero.debitNotes.cancel(orgId, debitNoteId, { reason: 'I' })
dn.status          // 'cancelled'
dn.agtCancelStatus // 'pending' → 'validated'

Resposta (200 OK)

JSON
{
  "id": "f1a2b3c4-...",
  "number": "ND ND6326S15899N/2",
  "total": 50000000,
  "status": "cancelled",
  "cancelledAt": "2026-10-02T10:00:00.000Z",
  "cancelReason": "I",
  "cancelNote": "emitida para o NIF errado",
  "agtStatus": "validated",
  "agtCancelStatus": "pending"
}

Erros comuns

400no_itemsO documento não tem linhas
404customer_not_foundCliente não encontrado nesta organização
404invoice_not_foundinvoiceId indicado não existe nesta organização
422agt_keys_not_configuredCredenciais AGT não configuradas na organização
422agt_series_errorErro ao obter/validar a série da AGT
422debit_note_tax_not_allowedLinha com taxRate 5 ou 14 - a ND não liquida IVA
400invalid_reasonAnulação: motivo diferente de 'N' ou 'I'
404debit_note_not_foundAnulação: nota de débito não encontrada nesta organização
409already_cancelledAnulação: a nota de débito já estava anulada
409agt_pendingAnulação: a AGT ainda está a validar a ND - tente daqui a alguns minutos