@veroao/react

SDK React para o Vero - integra pesquisa de clientes e emissão de factura directamente no teu checkout, usando uma chave segura para o browser.

Instalação

npm install @veroao/react

react e react-dom (>=18) são peer dependencies - usa as que já tens no projecto.

Chave publicável - segura para o browser

Este SDK foi desenhado para correr no cliente (browser), por isso usa uma chave publicável (vero_live_pk_... / vero_test_pk_...), diferente da chave secreta usada no @veroao/node. Cria-a no dashboard, em Chaves de API, escolhendo o tipo "Publicável".

Mesmo que alguém veja esta chave no código-fonte da página, o servidor só a aceita nos endpoints de widget (pesquisar clientes, emitir factura) - nunca dá acesso à tua conta completa.

Quick start

import { VeroAOProvider, useVeroAO } from '@veroao/react'

function App() {
  return (
    <VeroAOProvider config={{ apiKey: 'vero_live_pk_...' }}>
      <CheckoutButton />
    </VeroAOProvider>
  )
}

function CheckoutButton() {
  const { client } = useVeroAO()

  const handleCreateInvoice = async () => {
    const { data: customers } = await client.listCustomers(orgId, { search: 'Maria' })

    const invoice = await client.createInvoice(orgId, {
      customerId: customers[0].id,
      documentType: 'FR',
      items: [{ description: 'Plano Pro', quantity: 1, unitPrice: 500000, taxRate: 14 }],
    })

    window.open(invoice.pdfUrl!, '_blank') // link público, sem autenticação
  }

  return <button onClick={handleCreateInvoice}>Emitir factura</button>
}

Configuração do Provider

<VeroAOProvider config={{
  apiKey: 'vero_live_pk_...',
  baseUrl: 'https://api.custom.ao/v1', // opcional - útil para testes locais
  environment: 'live',                  // opcional, default 'test'
}}>
  {children}
</VeroAOProvider>

useVeroAO()

Devolve { client, isLoading, error }. client expõe:

• client.listCustomers(orgId, { search?, limit? }) → { data: Customer[] }
• client.createInvoice(orgId, { customerId, items, documentType?, notes?, idempotencyKey? }) → Invoice

Tratamento de erros

try {
  await client.createInvoice(orgId, input)
} catch (err) {
  const apiErr = err as { error: string; message?: string }
  if (apiErr.error === 'customer_not_found') {
    // cliente não encontrado nesta organização
  }
}

Preços em kwanzas

Os valores monetários usam kwanzas × 100: unitPrice: 500000 equivale a 5 000,00 AOA.

Preciso de mais do que isto - criar produtos, listar facturas, notas de crédito...

Este SDK só sabe fazer as duas coisas acima, de propósito: a chave publicável que usa é restrita pelo servidor a essas rotas, para ser segura no browser. Não existe forma de "desbloquear" mais operações com uma chave publicável - nem gerir produtos, nem listar facturas existentes, nem emitir notas de crédito/débito, nem apagar clientes.

Se precisas de qualquer uma dessas operações a partir de uma aplicação React, o padrão correcto é:

React (browser)  →  o TEU backend  →  Vero (com @veroao/node + chave secreta)

Ou seja, cria uma rota de API tua (Next.js API route, Express, etc.) que use @veroao/node com a chave secreta, e chama essa rota a partir do React - nunca a API do Vero directamente para essas operações.

// app/api/products/route.ts (exemplo Next.js)
import { createVeroClient } from '@veroao/node'

const vero = createVeroClient() // VERO_API_KEY - chave secreta, só no servidor

export async function POST(req: Request) {
  const body = await req.json()
  const product = await vero.products.create(ORG_ID, body)
  return Response.json(product)
}

O backend não precisa de ser Node - é só o exemplo mais directo. Se for PHP, Python, Ruby, etc., chama a API REST directamente com o cliente HTTP dessa linguagem; tens as mesmas operações disponíveis. Exemplos em cURL, Python e PHP em vero.ao/docs.