Vero
DevelopersDashboard

Facturas recorrentes API

Avenças, rendas, mensalidades: uma FT repetida no dia X, de N em N meses. O Vero emite-a no próprio dia (a AGT exige a data da emissão, por isso nunca sai com data futura) e, se quiseres, envia o PDF ao cliente.

Já tens o calendário no teu sistema?

Não precisas destas rotas: um cron que chama POST /invoices com uma idempotencyKey por período (ex.: avenca:CLIENTE:2026-11) dá o mesmo resultado, e uma repetição nunca cria duas facturas. Estas rotas servem para deixar o calendário do lado do Vero, visível e gerível no dashboard (Facturas → Recorrentes).

Criar recorrência

POST/v1/organisations/:orgId/recurring-invoices

Só com chave live: com chave de teste a resposta é 403 not_available_in_test, porque a recorrência emitiria depois facturas reais.

TypeScript
const rec = await vero.recurringInvoices.create(ORG_ID, {
  customerId: customer.id,
  items: [{ description: 'Avença de manutenção', quantity: 1, unitPrice: 5000000 }],
  dayOfMonth: 13,
  intervalMonths: 1,
  startDate: '2026-11-01',
  mode: 'auto',
  sendEmail: true,
})
rec.upcoming // ['2026-11-13', '2026-12-13', '2027-01-13']
CampoTipoDescrição
customerIdstring (uuid)Cliente - obrigatório
itemsInvoiceItem[]Linhas, no mesmo formato de POST /invoices - obrigatório
dayOfMonth1–31Dia de cada factura - obrigatório. 31 = último dia nos meses mais curtos
startDateAAAA-MM-DDA partir de quando - obrigatório. Se a primeira data for hoje, fica logo pronta (ou emitida, com mode auto)
intervalMonths1 | 3 | 6 | 12Mensal (default), trimestral, semestral, anual
endDateAAAA-MM-DD?Terminar nesta data
maxCountinteger?Terminar ao fim de N facturas
mode'confirm' | 'auto'confirm (default): no dia fica pronta e espera por /issue · auto: emite sozinha
sendEmailbooleanEnviar o PDF ao cliente por email ao emitir (default: true)
notesstring?Notas da factura

Resposta (201 Created)

JSON
{
  "id": "5f1c...",
  "customerId": "b2c3...",
  "customerName": "Empresa ABC",
  "description": "Avença de manutenção",
  "total": 5700000,
  "intervalMonths": 1,
  "dayOfMonth": 13,
  "startDate": "2026-11-01",
  "endDate": null,
  "maxCount": null,
  "generatedCount": 0,
  "nextRunDate": "2026-11-13",
  "upcoming": ["2026-11-13", "2026-12-13", "2027-01-13"],
  "mode": "auto",
  "sendEmail": true,
  "status": "active",
  "pendingRuns": 0,
  "firstRun": null
}

total é o valor de cada factura, com IVA, em kwanzas × 100. firstRun só vem preenchido quando a primeira data é hoje.

Como corre

  • A partir das 07h (Luanda) do dia marcado, o Vero gera a factura dessa data - uma só vez por data, mesmo com repetições.
  • Com mode: 'auto' emite a FT na AGT (com idempotencyKey recurring:<id>:<data>) e envia-a ao cliente se sendEmail. Se falhar, tenta de novo (até 5 vezes, uma por hora) e avisa o dono por email.
  • Com mode: 'confirm' fica pronta: o dono recebe um email e emite com um clique, ou tu pela API.
  • Se o servidor estiver parado vários meses, gera só uma factura atrasada e salta para a próxima data futura.
  • Os webhooks invoice.issued disparam como em qualquer factura.

Prontas a emitir

GET/v1/organisations/:orgId/recurring-invoices-pending

Facturas que chegaram ao dia: ready (à espera de confirmação) ou failed (com error).

POST/v1/organisations/:orgId/recurring-invoices-pending/:runId/issue
POST/v1/organisations/:orgId/recurring-invoices-pending/:runId/skip
TypeScript
for (const run of await vero.recurringInvoices.pending(ORG_ID)) {
  const { invoiceId, emailed } = await vero.recurringInvoices.issue(ORG_ID, run.id)
}

A factura sai com a data de hoje. Emitir duas vezes a mesma dá 409 already_done; se a AGT recusar, 422 issue_failed com a mensagem.

Gerir

GET/v1/organisations/:orgId/recurring-invoicesLista ({ data: [...] })
GET/v1/organisations/:orgId/recurring-invoices/:idDetalhe, com o histórico em runs[] (data, estado, número e estado AGT de cada factura)
PATCH/v1/organisations/:orgId/recurring-invoices/:idMudar linhas, calendário, fim, modo ou email - só as próximas facturas mudam
POST/v1/organisations/:orgId/recurring-invoices/:id/pausePausar
POST/v1/organisations/:orgId/recurring-invoices/:id/resumeRetomar a partir da próxima data futura (não gera as que passaram)
POST/v1/organisations/:orgId/recurring-invoices/:id/endTerminar de vez (409 recurring_ended depois)

SDK: vero.recurringInvoices.list / get / update / pause / resume / end (@veroao/node 1.5+). Ainda não disponível para apps OAuth.