Vero
DevelopersDashboard

Webhooks

Receba notificações em tempo real sobre eventos de facturação, pagamentos e estado de documentos.

Estrutura do Evento

O Vero envia um POST HTTPS para o URL configurado com o seguinte payload JSON:

Payload Example

JSON
{
  "event": "invoice.issued",
  "orgId": "779b90ce-...",
  "timestamp": "2026-07-07T10:00:00.000Z",
  "data": {
    "id": "a1b2c3d4-...",
    "number": "FR FR6326S47071N/1",
    "status": "issued",
    "total": 15000000,
    "pdfUrl": "https://api.vero.ao/v1/public/invoices/a1b2c3d4-.../pdf"
  }
}

data.pdfUrl em eventos de factura é um link público, sem necessidade de autenticação - pode ser usado directamente num email ou aberto pelo utilizador final. Gerado na hora a cada pedido, não fica em storage.

data é o próprio documento (mesma forma da resposta da API), não um objecto aninhado.

Eventos Suportados

invoice.issuedEmitido quando uma factura é assinada e certificada.
invoice.cancelledEmitido quando uma factura é anulada (gera Nota de Crédito).
invoice.agt_validatedA AGT validou a factura (FT, FR, FA...). Chega alguns segundos depois do invoice.issued.
invoice.agt_rejectedA AGT rejeitou a factura. Os motivos vêm em data.agtErrors (código e mensagem da AGT).
credit_note.issuedA nota de crédito foi emitida (tem número). data.kind é cancel (anulação) ou advance (regularização de uma FA; data.invoiceId é a FA e data.regularizedInvoiceId a factura final). A de adiantamento pode sair depois da factura final, se a AGT estiver em baixo.
credit_note.agt_validatedA AGT validou a nota de crédito. data.invoiceId é a factura de origem; data.kind e data.regularizedInvoiceId como em credit_note.issued.
credit_note.agt_rejectedA AGT rejeitou a nota de crédito, com os motivos em data.agtErrors.
proforma.convertedEmitido quando um orçamento é convertido em factura.
proforma.cancelledEmitido quando um orçamento é anulado.

Estado na AGT

A validação pela AGT acontece em segundo plano. Em vez de consultar cada documento com GET, subscreve invoice.agt_validated e invoice.agt_rejected. Cada evento é enviado uma vez por documento, com a mesma assinatura X-Vero-Signature e as mesmas novas tentativas dos outros eventos. O campo idempotencyKey é a chave que enviaste ao emitir, para ligares o evento à venda no teu sistema.

{
  "event": "invoice.agt_rejected",
  "orgId": "5f1c…",
  "data": {
    "id": "a3b9…",
    "number": "FR FR27X/1452",
    "documentType": "FR",
    "total": 11400000,
    "currency": "AOA",
    "agtStatus": "rejected",
    "agtErrors": [{ "idError": "E12", "descriptionError": "NIF do adquirente inválido" }],
    "agtRespondedAt": "2026-11-05T10:15:02.000Z",
    "idempotencyKey": "venda-001"
  },
  "timestamp": "2026-11-05T10:15:10.000Z"
}