Vero
DevelopersDashboard
Blueprint

E-commerce (Checkout)

Emite uma Factura-Recibo (FR) automaticamente após cada compra confirmada. O cliente recebe o PDF certificado por email sem sair da tua loja.

01 · Garantir cliente

customers.ensure() cria ou actualiza pelo externalId - nunca duplica.

02 · Registar produto

products.create() regista o item no catálogo e devolve o ID para referenciar na factura.

03 · Emitir FR

invoices.create() com documentType FR - Factura-Recibo para pagamentos à vista.

Sandbox · Usa a chave vero_test_sk_... durante o desenvolvimento - as facturas são geradas mas não chegam à AGT. Troca para vero_live_sk_... quando fores para produção.
TypeScript
import { createVeroClient } from '@veroao/node'

const vero = createVeroClient() // lê VERO_API_KEY do ambiente
const ORG_ID = process.env.VERO_ORG_ID!

// Express handler - chamado após pagamento confirmado
app.post('/checkout/complete', async (req, res) => {
  const { user, cart } = req.body

  // 1. Garantir cliente (cria ou actualiza pelo externalId)
  const customer = await vero.customers.ensure(ORG_ID, {
    externalId: user.id,
    name: user.name,
    taxId: user.nif,
    phone: user.phone,
    email: user.email,
    addressLine1: user.address,
    city: user.city,
  })

  // 2. Garantir produto no catálogo (ou reutilizar o ID se já existe)
  const product = await vero.products.create(ORG_ID, {
    code: cart.productCode,
    name: cart.productName,
    description: cart.productDescription,
    unitPrice: cart.unitPrice, // kwanzas × 100 - ex: 5000000 = 50 000,00 AOA
    taxRate: 14,
    unitOfMeasure: 'UN',
  })

  // 3. Emitir Factura/Recibo (FR = pagamento à vista)
  const invoice = await vero.invoices.create(ORG_ID, {
    customerId: customer.id,
    documentType: 'FR',
    items: [{
      description: product.name,
      quantity: cart.quantity,
      unitPrice: product.unitPrice,
      taxRate: product.taxRate,
      productId: product.id,
    }],
    idempotencyKey: `checkout_${req.body.orderId}`,
  })

  res.json({ pdfUrl: invoice.pdfUrl, number: invoice.number })
})

Resposta (201 Created)

JSON
{
  "id": "a1b2c3d4-...",
  "number": "FR FR6326S47071N/1",
  "documentType": "FR",
  "status": "paid",
  "subtotal": 4385965,
  "taxAmount": 614035,
  "total": 5000000,
  "currency": "AOA",
  "atcud": "ABCD1234-1",
  "pdfUrl": "https://storage.vero.ao/invoices/a1b2c3d4.pdf",
  "issuedAt": "2026-05-19T10:30:00.000Z"
}
Valores monetários · Todos os preços em kwanzas × 100 (inteiros, sem vírgula flutuante). 50 000,00 AOA → unitPrice: 5000000.