Recibos e pagamentos

Quando emitir um recibo

A AGT não sabe que o cliente pagou: só o recibo (RC) emitido pela empresa o diz. O recibo é assinado e comunicado à AGT como qualquer outro documento, e não se apaga.

1. Pagamento total

Sem amount, o recibo liquida tudo o que falta pagar. É o caso mais comum.

# Factura
curl -X POST https://api.vero.ao/v1/organisations/$ORG_ID/invoices/$INVOICE_ID/receipt \
  -H "Authorization: Bearer $VERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethod": "transfer" }'

# Nota de débito
curl -X POST https://api.vero.ao/v1/organisations/$ORG_ID/debit-notes/$DEBIT_NOTE_ID/receipt \
  -H "Authorization: Bearer $VERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethod": "cash" }'

Com o SDK (@veroao/node 1.4+)

await vero.receipts.create(orgId, invoice.id, { paymentMethod: 'transfer' })
await vero.receipts.createForDebitNote(orgId, debitNote.id, { paymentMethod: 'cash' })

2. Onde e quando entrou o dinheiro

Os três campos são opcionais e servem a tesouraria e a conciliação bancária da empresa:

• receivedIn: a conta (banco, caixa ou TPA) onde o dinheiro entrou.
• receivedAt: a data do recebimento (AAAA-MM-DD). Por omissão, agora.
• paymentMethod: transfer, cash, check ou card. Com receivedIn, deduz-se da conta. Sem ele, numerário vai para a Caixa, cartão para o TPA e transferência ou cheque para o banco por omissão.

3. Pagamento parcial

O cliente pagou só uma parte. Envie o valor recebido em amount (cêntimos, com IVA). Cada prestação é um recibo; o documento fica pago quando a soma dos recibos chega ao total.

Funciona em todas as empresas, sem nada para activar.

// ND de 12 000 Kz (1 200 000 cêntimos). O cliente paga 5 000 Kz hoje...
const first = await vero.receipts.createForDebitNote(orgId, dn.id, { amount: 500000 })
first.paymentInfo
// { invoiceNumber: 'ND 2026/000003', invoiceTotal: 1200000, paidBefore: 0, remainingAfter: 700000 }

// ...e o resto na semana seguinte (sem amount = o que falta)
const second = await vero.receipts.createForDebitNote(orgId, dn.id, { receivedAt: '2026-10-26' })
second.paymentInfo?.remainingAfter // 0

O PDF de cada recibo parcial mostra o total do documento, o que já tinha sido pago e o que falta. Um amount maior do que o que falta devolve 400 invalid_amount.

4. Saber o que falta receber

Facturas e notas de débito trazem paidAmount: a soma dos recibos não anulados. O que falta é total - paidAmount. A ND não muda de status quando é paga; use sempre paidAmount.

const dn = await vero.debitNotes.get(orgId, debitNoteId)
const remaining = dn.total - (dn.paidAmount ?? 0)
const state = remaining <= 0 ? 'paga' : dn.paidAmount ? 'parcialmente paga' : 'por pagar'

5. Recibo errado

Um recibo emitido por engano anula-se com POST /receipts/:id/cancel, só pelos motivos N (não foi enviado ao cliente) ou I (cliente errado). O valor volta a ficar por pagar e pode emitir o recibo certo a seguir.

Uma ND com recibo activo não pode ser anulada (409 debit_note_has_receipts): anule primeiro o recibo.

Apps OAuth

Os dois recibos precisam da permissão invoices:write ("Emitir facturas e recibos em nome da empresa"). Detalhes de cada campo e todos os erros em Receipts API.