Do zero à primeira factura real

Regista-te em /register com nome, email e palavra-passe. Confirmas o email e entras directamente no dashboard.

Logo após o registo, o dashboard pede para criares a tua empresa - os dados que a identificam perante a AGT:

Se tiveres mais do que uma empresa (ex: és contabilista com vários clientes), repete este passo para cada uma - trocas entre elas no seletor de empresa no topo do dashboard.

Este é o passo mais importante e o único que não é feito no Vero: precisas de um par de chaves RSA (pública/privada) atribuído pela AGT à tua empresa (não ao Vero), gerido em quiosqueagt.minfin.gov.ao → Facturação Electrónica. Sem isto, os documentos fiscais (FT, FR, NC, ND) não podem ser submetidos com valor legal.

Depois de teres as chaves, vai a Definições → Segurança e cola-as nos respectivos campos (chave privada e chave pública). Guarda, pronto: a empresa já pode emitir documentos com valor fiscal real.

Ainda não tens as chaves? Usa o ambiente de sandbox para testar o resto do fluxo sem bloqueios. Nenhum documento de sandbox precisa de chaves configuradas.

Se quiseres que a conta bancária apareça nas facturas (para o cliente saber para onde transferir), configura em Definições → Dados Bancários - nome do banco, IBAN, número de conta. Até 3 contas por empresa. Não é obrigatório para emitir documentos.

Se vais usar o Vero apenas pelo dashboard (emitir facturas manualmente, como a maioria dos contabilistas e pequenos negócios faz), podes saltar este passo - os passos seguintes explicam sempre a via do dashboard primeiro.

Se fores integrar programaticamente (ex: a tua loja online a emitir facturas automaticamente), gera uma chave em Chaves de API → Nova Chave de API (barra lateral). Escolhe o ambiente:

A chave só é mostrada uma vez - guarda-a nesse momento. Todos os exemplos "via API" abaixo usam esta chave.

No dashboard: Clientes → Novo Cliente. Todos os campos são opcionais individualmente, mas é preciso pelo menos um de: nome, NIF, ou marcar como Consumidor Final.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/customers \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Manuel",
    "taxId": "5417163169",
    "phone": "923456789",
    "email": "joao@exemplo.ao",
    "addressLine1": "Rua Amílcar Cabral, 45",
    "city": "Luanda"
  }'

# Ou, para venda a dinheiro sem identificar o cliente:
curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/customers \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "isConsumidorFinal": true }'

No dashboard: Produtos → Novo Produto. Útil para reutilizar preços e taxas de IVA e controlar stock - mas também podes escrever os itens directamente na factura, sem catálogo.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/products \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "CONSULTORIA-TI",
    "name": "Serviços de Consultoria TI",
    "unitPrice": 15000000,
    "taxRate": 14
  }'

No dashboard: Facturas → Nova Factura. Escolhe o cliente, adiciona os itens (do catálogo ou manuais) e o tipo de documento:

FT - factura a crédito, o cliente paga depois. FR - já vem quitada, ideal para venda a pronto pagamento.

Depois de emitida, descarrega o PDF certificado ou envia por email directamente da lista de Facturas.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/invoices \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "documentType": "FT",
    "items": [
      { "description": "Serviços de Consultoria TI", "quantity": 1, "unitPrice": 15000000, "taxRate": 14 }
    ]
  }'
# Resposta: { "number": "FT FT6326S62896N/1", "pdfUrl": "...", "atcud": "...", "agtStatus": "pending" }

Ver todos os campos e erros em Invoices API.

No dashboard: abre a factura em Facturas, menu de ações (⋯) → Anular factura (NC). A factura original passa automaticamente a "cancelada". Só pode existir uma NC por factura.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/invoices/INVOICE_ID/credit-note \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Anulação por erro de facturação" }'

Detalhes em Credit Notes API.

Ao contrário da NC, a ND não exige uma factura de origem - serve para qualquer cobrança adicional a um cliente. No dashboard tens duas formas de a emitir:

Notas de Débito → Nova Nota de Débito (autónoma, escolhes o cliente e o motivo), ou a partir de uma factura já emitida - menu de ações (⋯) → Emitir nota de débito (ND) - neste caso a referência à factura é preenchida automaticamente e correctamente, sem risco de erro.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/debit-notes \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "items": [{ "description": "Custos administrativos", "quantity": 1, "unitPrice": 500000, "taxRate": 14 }],
    "invoiceId": "INVOICE_ID"
  }'
# invoiceId é opcional - quando indicado, o Vero usa o número real dessa factura como referência

Detalhes em Debit Notes API.

Documento logístico (sem valor fiscal, não vai à AGT). No dashboard: abre a factura já emitida, menu de ações (⋯) → Nota de entrega - os itens e o cliente são copiados automaticamente.

curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/invoices/INVOICE_ID/delivery-note \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Entregar na receção, 2º piso" }'

Detalhes em Delivery Notes API.

A Proforma não tem valor fiscal - serve para enviar um orçamento ao cliente antes de emitir a factura real. No dashboard: Pro-forma → Nova Pro-forma. Quando o cliente aceita, abre a proforma e converte-a numa factura (FT/FR) com um clique.

# 1. Criar proforma
curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/proformas \
  -H "Authorization: Bearer vero_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "CUSTOMER_ID", "items": [...] }'

# 2. Depois de aceite, converter em factura (sem corpo - usa os dados já na proforma)
curl -X POST https://api.vero.ao/v1/organisations/ORG_ID/proformas/PROFORMA_ID/convert \
  -H "Authorization: Bearer vero_live_sk_..."

Detalhes em Proformas API e no Fluxo Proforma.

No dashboard, cada tipo de documento tem a sua própria página - Facturas, Proforma, Notas de Crédito, Notas de Débito, Notas de Entrega e Recibos - todas com pesquisa, filtro por estado e download de PDF.

Se estiveres a integrar por API, cada tipo tem um endpoint de listagem equivalente:

Para saber se uma factura, NC ou ND já foi validada pela AGT, consulta o campo agtStatus (pending → validated/rejected), visível também na coluna de estado AGT em cada lista do dashboard - a submissão à AGT acontece em segundo plano, não bloqueia a emissão. (Proforma e Nota de Entrega não têm este campo - não têm valor fiscal.)