VeroVero
Começar grátis
API REST + SDK TypeScript

Facturas certificadas
no teu código.

API REST + SDK Node.js para emitires facturas certificadas pela AGT directamente da tua plataforma. Sem redireccionamentos, sem portais externos, sem burocracia.

Obter chave de teste grátisVer documentação
Antes de codificar

3 passos no dashboard, uma vez só.

Os exemplos de código abaixo assumem que já tens uma empresa e uma API key. Se ainda não tens, é rápido:

1

Cria conta e empresa

No dashboard: regista-te e cria a tua empresa (nome, NIF, email).

2

Configura as chaves AGT

Certificado RSA atribuído pela AGT à tua empresa (não ao Vero), gerido em quiosqueagt.minfin.gov.ao → Facturação Electrónica. Cola-o em Definições → Segurança. Sem isto, os documentos não têm valor fiscal.

3

Gera a tua API key

Chaves de API (barra lateral) → Nova Chave de API. Usa vero_test_sk_... para testar sem custo, vero_live_sk_... quando estiveres pronto.

Guia completo, passo a passo
Testar ao vivo

Gera uma factura de teste agora.

Cola a tua chave de teste e o ID da organização. O resto está pré-preenchido. Clica em "Gerar factura" e vê a resposta real da API.

Credenciais

Cliente

Item a facturar

Resposta da API

Preenche as credenciais e clica em "Gerar factura de teste"

Quick start

Da instalação à primeira factura em minutos.

Usa a chave de teste para experimentar sem custos e sem configuração especial. As facturas de teste não chegam à AGT.

TypeScript
// 1. Instalar
npm install @veroao/node

// 2. Configurar (uma vez)
// .env
VERO_API_KEY=vero_test_sk_...
VERO_ORG_ID=uuid-da-tua-empresa

// 3. Emitir factura
import { createVeroClient } from '@veroao/node'

const vero = createVeroClient()
const ORG_ID = process.env.VERO_ORG_ID!

const customer = await vero.customers.ensure(ORG_ID, {
  externalId: 'user_123',
  name: 'João Silva',
  taxId: '003456789LA042',
  phone: '923456789',
  email: 'joao@exemplo.ao',
  addressLine1: 'Rua Amílcar Cabral, 45',
  city: 'Luanda',
})

const product = await vero.products.create(ORG_ID, {
  code: 'SERVICO-01',
  name: 'Consultoria TI',
  description: 'Consultoria técnica mensal',
  unitPrice: 10000000, // 100 000,00 AOA
  taxRate: 14,
  unitOfMeasure: 'UN',
})

const invoice = await vero.invoices.create(ORG_ID, {
  customerId: customer.id,
  items: [{
    description: product.name,
    quantity: 1,
    unitPrice: product.unitPrice,
    taxRate: product.taxRate,
    productId: product.id,
  }],
})

console.log(invoice.pdfUrl) // PDF certificado AGT

Chave de teste vs. chave live

vero_test_sk_... faz facturas marcadas como teste, sem custo, sem submissão à AGT. vero_live_sk_... faz facturas reais e certificadas. O ambiente é detectado automaticamente pelo SDK, não precisas de mudar nenhuma configuração, só a chave.

Retenção na fonte (opcional)

Passa applyWithholdingTax: true em invoices.create() se a tua organização estiver sujeita ao Art. 67º do Código do Imposto Industrial (activável em Definições - desligado por omissão, a maioria não precisa). Não altera o total da factura, só acrescenta o campo withholdingTax na resposta. Podes testar isto já na secção Testar ao vivo acima, ou ver os detalhes na Invoices API.

Todos os documentos

Facturação é mais do que emitir uma factura.

O exemplo acima cobre a Factura (FT). O resto do ciclo de vida do documento também é API, com a mesma lógica de idempotência e autenticação.

Proforma

Orçamento sem valor fiscal, converte-se em factura.

Terminal
POST /v1/organisations/ORG_ID/proformas
{ "customerId": "...", "items": [{ "description": "...", "quantity": 1, "unitPrice": 15000000, "taxRate": 14 }] }
Ver API completa

Factura de Adiantamento

Sinal pago antes de facturar tudo; a factura final desconta-o.

Terminal
POST /v1/organisations/ORG_ID/invoices
{ "documentType": "FA", "customerId": "...", "items": [...] }
// depois, na FT/FR final: "advances": [{ "invoiceId": "FA_ID" }]
Ver API completa

Factura recorrente

Avenças e mensalidades: o Vero emite no dia certo.

Terminal
POST /v1/organisations/ORG_ID/recurring-invoices
{ "customerId": "...", "items": [...], "dayOfMonth": 13, "startDate": "2026-11-01", "mode": "auto" }
Ver API completa

Nota de Crédito

Anula uma factura já emitida.

Terminal
POST /v1/organisations/ORG_ID/invoices/INVOICE_ID/credit-note
{ "reason": "Anulação por erro de facturação" }
Ver API completa

Nota de Débito

Cobrança adicional, com ou sem factura de origem.

Terminal
POST /v1/organisations/ORG_ID/debit-notes
{ "customerId": "...", "items": [...], "invoiceId": "..." }  // invoiceId é opcional
Ver API completa

Nota de Entrega

Acompanhamento de mercadoria, sem valor fiscal.

Terminal
POST /v1/organisations/ORG_ID/invoices/INVOICE_ID/delivery-note
{ "notes": "Entregar na receção, 2º piso" }
Ver API completa

Relatórios

Resumo de facturação por período, receita e impostos.

Terminal
GET /v1/organisations/ORG_ID/reports/billing-summary?year=2026&month=7
Ver API completa
Developer experience

Construído para quem integra por código.

Cada detalhe foi pensado para reduzir o atrito, desde a detecção automática do ambiente até aos erros tipados. Se preferires usar só o dashboard, sem código nenhum, também funciona. Ver Primeiros Passos.

Idempotência automática

O SDK gera uma chave de idempotência por omissão. Passa a tua (ex: order_ID) para garantir que retries não criam facturas duplicadas.

TypeScript
await vero.invoices.create(ORG_ID, {
  customerId: customer.id,
  items: [...],
  idempotencyKey: `order_${order.id}`,
})

Retry automático com backoff

O SDK faz até 3 tentativas em erros 5xx com backoff exponencial (400ms → 800ms → 1600ms). Sem código extra da tua parte.

TypeScript
const vero = createVeroClient({
  secretKey: process.env.VERO_API_KEY!,
  maxRetries: 3,   // default
  timeout: 30000, // ms
})

customers.ensure(), sem duplicados

Upsert pelo teu externalId: cria o cliente se não existir, actualiza se existir. Seguro chamar em cada pedido.

TypeScript
// Seguro chamar sempre - nunca cria duplicados
const customer = await vero.customers.ensure(ORG_ID, {
  externalId: req.user.id,
  name: req.user.name,
  taxId: req.user.taxId,
})

Erros tipados

Sem try/catch genérico. Cada tipo de erro tem a sua classe, trata autenticação, not found e rate limit de forma granular.

TypeScript
import { VeroAuthError, VeroNotFoundError, VeroRateLimitError } from '@veroao/node'

try {
  await vero.invoices.create(ORG_ID, input)
} catch (err) {
  if (err instanceof VeroRateLimitError) {
    await sleep(err.retryAfter ?? 60000)
  }
}
SDKs

Para qualquer stack.

Sem SDK para a tua linguagem? Usa a API REST directamente. É JSON puro, com autenticação Bearer e documentação completa.

Server-side

@veroao/node

Para Node.js, Bun e Deno. API resource-based completa com retry, idempotência e erros tipados.

Terminal
npm install @veroao/node
  • TypeScript nativo
  • Retry automático
  • fetch nativo (Node 18+)
  • Zero dependências externas
Ver documentação
Frontend

@veroao/react

Hooks e Provider para React. Usa chaves públicas (pk_...), nunca expõe a chave secreta.

Terminal
npm install @veroao/react
  • useVero(), useInvoice()
  • Chave pública segura
  • React 18+
  • SSR compatible
Ver documentação
Zero-code

@veroao/widget

Web Component drop-in. Cola uma linha de HTML e os teus utilizadores emitem facturas sem sair do teu site.

HTML
<script src="https://cdn.vero.ao/widget.js"></script>
  • Zero dependências
  • Todos os browsers
  • Tema configurável
  • Eventos customizados
Ver documentação

A implementar com Claude Code ou outro agente de IA?

Dá ao teu assistente de IA o essencial da API da Vero de uma vez só (autenticação, endpoints, formatos e erros comuns), sem teres de explicar tudo à mão. Instala as skills do Vero (API e templates) com npx skills add Eterim/veroao.

Ver vero-skill.md
Webhooks

Eventos em tempo real.

Reage a qualquer evento de facturação sem polling. Regista um endpoint e recebe notificações com assinatura HMAC para verificar autenticidade.

Integração completa
// 1. Registar endpoint
await vero.webhooks.register(ORG_ID, {
  url: 'https://teusite.ao/webhooks/vero',
  events: ['invoice.issued', 'invoice.cancelled'],
})

// 2. Receber eventos no teu servidor
app.post('/webhooks/vero', (req, res) => {
  const { event, data } = req.body

  switch (event) {
    case 'invoice.issued':
      // Factura certificada - notificar cliente, actualizar BD...
      await sendConfirmationEmail(data.pdfUrl)
      break

    case 'invoice.cancelled':
      // Factura anulada - reverter saldo, etc.
      break
  }

  res.sendStatus(200)
})

Eventos disponíveis

invoice.issuedFactura emitida e certificada pela AGT
invoice.cancelledFactura anulada
proforma.convertedPró-forma convertida em factura
proforma.cancelledPró-forma anulada

Cada entrega inclui assinatura HMAC-SHA256 no header X-Vero-Signature para verificares autenticidade antes de processar.

Vero Template

O aspecto das facturas, em React e Tailwind.

Desenha o template com @veroao/invoice, vê-o ao vivo e importa-o no Vero. As regras da AGT vêm incluídas: o template muda o aspecto, os dados fiscais vêm sempre do documento. Open source.

templates/invoice.tsx
import { Document, Row, Logo, DocumentTitle, DocumentNumber,
  DocumentDate, Customer, Issuer, Items, Totals, LegalNotes } from "@veroao/invoice"

export default function MyInvoice() {
  return (
    <Document className="bg-white px-12 pt-10 text-[11px]">
      <Row className="items-start justify-between">
        <Logo className="h-12" />
        <DocumentTitle className="text-3xl font-bold uppercase text-teal-900" />
      </Row>
      <Row className="mt-8 gap-6">
        <Customer className="flex-1 border border-zinc-200 p-3" />
        <Issuer className="flex-1" />
      </Row>
      <Row className="mt-6 justify-between">
        <DocumentNumber className="font-bold" />
        <DocumentDate />
      </Row>
      <Items className="mt-3" rowClassName="border-b border-zinc-200 even:bg-zinc-50" />
      <Totals className="ml-auto mt-4 w-1/2" />
      <LegalNotes className="mt-6 text-[9px] text-zinc-500" />
    </Document>
  )
}
Terminal
npx @veroao/invoice init minhas-facturas
npx @veroao/invoice dev     # pré-visualização ao vivo
npx @veroao/invoice check   # as verificações do Vero
  • Galeria de templates prontos, com Abrir no Vero.
  • Importação no dashboard (plano Pro), com pré-visualização e os dados da empresa.
  • Cada documento fica preso à versão do template com que foi emitido.
  • Também gera o PDF no teu próprio sistema, sem o Vero.
template.vero.ao Guia na documentação
Use cases

Qualquer modelo de negócio.

A API é suficientemente flexível para cobrir desde lojas simples até marketplaces multi-vendor com centenas de organizações.

E-commerce

Emite factura automaticamente ao fim de cada compra. O cliente recebe o PDF por email sem sair da tua loja.

  1. 1Checkout completo → webhook payment.confirmed
  2. 2customers.ensure() com dados do comprador
  3. 3invoices.create() com produtos do carrinho
  4. 4invoice.send() → PDF no email do cliente
Ver exemplo completo

SaaS / Subscrições

Gera facturas mensais automaticamente no ciclo de renovação. Liga ao teu sistema de pagamentos com idempotência.

  1. 1Renovação mensal disparada pelo billing
  2. 2customers.ensure() pelo ID do utilizador
  3. 3products.create() com plano do utilizador
  4. 4invoices.create() com idempotencyKey do ciclo
Ver exemplo completo

Marketplace

Cada vendor emite as suas próprias facturas. Gere múltiplas organizações com a mesma integração.

  1. 1Vendor regista empresa → organisations.create()
  2. 2Cliente faz compra → customers.ensure(orgId, ...)
  3. 3Produto do vendor → products.create(orgId, ...)
  4. 4Factura no nome do vendor → invoices.create(orgId, ...)
Ver Organisations API

Começa a emitir facturas hoje.

Cria uma conta gratuita, obtém a tua chave de teste e emite a primeira factura em menos de 10 minutos.

Criar conta grátisExplorar documentação

Dúvidas? suporte@vero.ao