@veroao/core

Cliente partilhado, mínimo, para os endpoints de widget do Vero - a base usada internamente pelos pacotes @veroao/react e @veroao/widget.

A maioria dos integradores não precisa deste pacote directamente. Se estás a construir no browser (checkout, formulário de factura embutido), usa @veroao/react ou @veroao/widget. Se estás no servidor com acesso à API completa, usa @veroao/node.

Porque é que isto existe

Os endpoints /v1/widget/... são uma superfície deliberadamente pequena e segura para expor no browser: só pesquisa de clientes e criação de factura, pensados para serem usados com uma chave publicável (vero_live_pk_...), que o servidor recusa em qualquer outra rota. Este pacote só fala com essas duas rotas.

Instalação

npm install @veroao/core

Uso

import { VeroAOClient } from '@veroao/core'

const client = new VeroAOClient({
  apiKey: 'vero_live_pk_...', // chave publicável - segura para o browser
})

const { data: customers } = await client.listCustomers(orgId, { search: 'Maria', limit: 8 })

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

console.log(invoice.pdfUrl) // link público de download, sem autenticação

Tratamento de erros

Um pedido falhado lança o corpo de erro da API directamente:

try {
  await client.createInvoice(orgId, input)
} catch (err) {
  const apiErr = err as { error: string; message?: string }
  if (apiErr.error === 'customer_not_found') {
    // ...
  }
}

Referência

new VeroAOClient(config)

| Campo | Obrigatório | Descrição | |---------------|:-----------:|----------------------------------------------| | apiKey | sim | Chave publicável (vero_live_pk_... / vero_test_pk_...) | | baseUrl | não | Default https://api.vero.ao/v1 |

client.listCustomers(orgId, params?)

params: { search?: string; limit?: number } - devolve { data: Customer[] }.

client.createInvoice(orgId, input)

input: { customerId, items, documentType?, notes?, idempotencyKey? } - devolve a factura criada.

Preciso de mais do que isto

Não é possível com uma chave publicável - o servidor só a aceita nestas duas rotas. Para gerir produtos, listar facturas existentes, emitir notas de crédito/débito, etc., usa um backend teu com @veroao/node e a chave secreta; este pacote (e o browser em geral) fala com esse backend, nunca directamente com o Vero para essas operações.

Esse backend não precisa de ser Node - é só a opção mais directa. Qualquer linguagem (PHP, Python, Ruby, etc.) consegue chamar a API REST directamente com o seu próprio cliente HTTP, com as mesmas operações disponíveis. Exemplos em cURL, Python e PHP em vero.ao/docs.