--- name: vero description: Integrate with the Vero API (AGT-certified electronic invoicing for Angola) - create customers, products, invoices, credit/debit notes, receipts, pro-formas and webhooks. Use this whenever the user asks to "create an invoice", "integrate with Vero", "issue a fiscal document" (or the Portuguese "criar uma factura", "emitir documento fiscal"), or works with the @veroao/* SDKs. --- # Vero - Electronic Invoicing API (Angola) Vero is an invoicing platform certified by the AGT (Administração Geral Tributária, Angola's tax authority). This skill gives you what you need to integrate correctly without reading the whole documentation. Fiscal terms stay in Portuguese, as in the API and on the documents: *factura* (invoice), *factura-recibo* (invoice-receipt), *nota de crédito/débito*, *recibo*, *pró-forma*, *NIF* (tax ID), *IVA* (VAT), *Consumidor Final* (anonymous end customer). ## Authentication Two families of keys - never use one in place of the other: - **`sk_...` (secret key)** - **server-to-server only**. Never expose it in the browser/frontend. Sent as `Authorization: Bearer sk_...`. Gives access to the organisation's whole API. - **`pk_...` (publishable key)** - safe in the browser. Only works on `/v1/widget/*` routes. Used by `@veroao/widget`. Keys are `live` or `test` (`vero_live_sk_...` / `vero_test_sk_...`). `test` keys never touch the real AGT - use them for development. Base URL: `https://api.vero.ao` ## Key concepts before writing code - **Money is always an integer in Kwanza cents (AOA).** 1,000.00 Kz = `100000`. Never send floats. - **`taxRate` is optional and you should omit it when possible.** If sent, only `0`, `5` or `14` are accepted. If omitted, the server resolves it from the organisation's VAT regime (`ivaRegime`/`defaultTaxRate`, set in the dashboard under Definições → Perfil) - never hard-code `14`. Organisations in the `isento` or `simplificado` regime ("Exclusão" in the UI) **cannot** have lines with a rate other than `0`; the API rejects an incompatible rate with `422 tax_rate_incompatible_with_regime`. If the organisation has no regime configured, the fallback is `14%`. - **`idempotencyKey`** - always send a unique value (e.g. the order ID in your system) when creating invoices. Prevents duplicates on network retries. - **Consumidor Final**: for anonymous/counter sales, create or use a customer with `isConsumidorFinal: true` instead of inventing a NIF. The system assigns the generic NIF `999999999`. - **`reference`** (optional, max 60 chars) is the product reference, e.g. a colour or model (`HP305-AZ`). It is printed on the PDF under the item name. If omitted on a line with `productId`, Vero uses the product's reference when the merchant set one (auto-generated product codes are never printed). - **`taxExemptionCode`** is required when `taxRate` ends up `0` (sent or resolved from the regime), except for Consumidor Final - the API rejects with `422 tax_exemption_code_required` if missing. Common codes: `M04` exclusion, `M22` health, `M21` education, `M13` books, `M30` exports. - **Sandbox**: sandbox organisations (or `test` keys) never submit to the real AGT - `hash`, `atcud` and `agtStatus` come back `null` and the number has the `TESTE` prefix. Use it to test without AGT certification. - **`customers.ensure()` never persists in sandbox**: with a `test` key it returns an ephemeral customer whose `id` looks like `sandbox_cus_...` (not a UUID), rebuilt from the request and not stored. Use that `id` as `customerId` when creating the invoice - it works - but don't expect to find it later with `GET /customers`. - **Without its own AGT key configured, an organisation cannot issue any real fiscal document** (outside sandbox) - the API returns `422 agt_keys_not_configured`. This is intentional: each organisation signs its own documents, never with a shared key. - **Withholding tax** (*retenção na fonte*, Art. 67 of the Industrial Tax Code) - always available, nothing to enable; lines are unmarked by default. Mark each subject line with `items[].withholdingTax: true` (e.g. a service line; product lines usually stay unmarked) on invoices and pro-formas. The base is the sum of the marked lines (without VAT). It only applies when the base is above the configured minimum - never send the computed amount yourself, the server always resolves it. `applyWithholdingTax: true` is the old form (all lines) and is only used when no line is marked. It does not change `subtotal`/`taxAmount`/`total` (those remain the official fiscal values); it comes separately in the response's `withholdingTax` field (`{ type, rate, base, amount, description }` or `null`). On a pro-forma it carries over to the invoice automatically when you convert it. SDKs: @veroao/node ≥ 1.3.2 (published as 1.4.0), @veroao/core/react/widget ≥ 1.2.0. ## Typical flow: create an invoice ```bash # 1. Ensure the customer (creates or updates by externalId) curl -X POST https://api.vero.ao/v1/organisations/{orgId}/customers/ensure \ -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \ -d '{"externalId":"user_123","name":"Empresa ABC","taxId":"5000123456","email":"financeiro@empresaabc.ao"}' # 2. Create the invoice curl -X POST https://api.vero.ao/v1/organisations/{orgId}/invoices \ -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \ -d '{ "customerId": "customer-uuid", "documentType": "FT", "idempotencyKey": "order_789", "items": [ { "description": "Serviço X", "quantity": 1, "unitPrice": 15000000 } ] }' ``` The response includes `number` (e.g. `"FT FT6326S62896N/1"`), `pdfUrl`, `atcud`, `hash` and `agtStatus` (`pending` for a moment, then `validated` or `rejected` - submission to the AGT is asynchronous). ## Node.js SDK (recommended for backends) ```bash npm install @veroao/node ``` ```ts import { createVeroClient } from '@veroao/node' const vero = createVeroClient({ secretKey: process.env.VERO_API_KEY! }) const customer = await vero.customers.ensure(orgId, { externalId: 'user_123', name: 'Empresa ABC', taxId: '5000123456' }) const invoice = await vero.invoices.create(orgId, { customerId: customer.id, documentType: 'FT', items: [{ description: 'Serviço X', quantity: 1, unitPrice: 15000000 }], idempotencyKey: `order_${orderId}`, }) ``` ## React SDK (`@veroao/react`) and Widget (`@veroao/widget`) - `@veroao/react` - hooks for React apps that already have their own backend calling the API (the secret key never goes to the browser). - `@veroao/widget` - to embed directly in a third-party site with the **publishable** key (`pk_`). No build step: `