Drop-in Widget
Um Web Component pronto a usar. Incorpore com uma linha de HTML - sem instalar pacotes, sem escrever JavaScript.
Instalação
Uma linha de <script>
Compatibilidade
Todos os browsers modernos
Personalização
CSS variables · Temas light/dark
Quick Start
Carregue o script e adicione o elemento vero-button onde quiser o botão.
<!-- 1. Carregar o widget -->
<script src="https://cdn.vero.ao/widget.js"></script>
<!-- 2. Adicionar o botão -->
<vero-button
api-key="pk_live_..."
org-id="org_123"
amount="150000"
description="Plano Pro - Jan 2025"
document-type="FR"
>
Pagar e obter factura
</vero-button>Usar em React
Web Components funcionam em React mas os eventos customizados precisam de um ref.
import { useEffect, useRef } from 'react'
export function CheckoutButton({ amount }: { amount: number }) {
const ref = useRef<HTMLElement>(null)
useEffect(() => {
const el = ref.current
if (!el) return
const onSuccess = (e: Event) => {
const { invoiceId, pdfUrl } = (e as CustomEvent).detail
window.open(pdfUrl, '_blank')
}
el.addEventListener('on-success', onSuccess)
return () => el.removeEventListener('on-success', onSuccess)
}, [])
return (
<vero-button
ref={ref}
api-key={import.meta.env.VITE_VERO_PUBLIC_KEY}
org-id={import.meta.env.VITE_VERO_ORG_ID}
amount={amount}
>
Pagar e obter factura
</vero-button>
)
}Atributos
Todos os atributos são strings no HTML - os tipos indicados referem-se ao valor semântico.
| Atributo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| api-key | string | sim | Chave pública pk_... da organização |
| org-id | string | sim | ID da organização (org_...) |
| amount | number | sim | Valor em cêntimos (AOA). Ex: 15000 = 150,00 AOA |
| customer-nif | string | - | NIF do cliente - pré-preenche o formulário |
| customer-name | string | - | Nome do cliente - pré-preenche o formulário |
| description | string | - | Descrição do produto ou serviço |
| document-type | string | - | "FT" (Factura) ou "FR" (Factura-Recibo). Default: "FR" |
| theme | string | - | "light" ou "dark". Default: detecta prefers-color-scheme |
| locale | string | - | "pt" ou "en". Default: "pt" |
Eventos
O widget dispara CustomEvents no elemento. Ouça com addEventListener ou os atributos on-*.
| Evento | detail | Quando |
|---|---|---|
| on-success | { invoiceId, pdfUrl, atcud } | Factura emitida com sucesso |
| on-error | { code, message } | Erro na emissão - code é o código da API |
| on-open | - | Modal aberto pelo utilizador |
| on-close | - | Modal fechado (com ou sem sucesso) |
Variáveis CSS
Defina estas variáveis no elemento pai (ou :root) para personalizar a aparência.
| Variável | Default | Descrição |
|---|---|---|
| --vero-radius | 0.75rem | Border-radius dos botões e painéis |
| --vero-font | inherit | Família de tipos - herda da página por omissão |
| --vero-primary | #18181b | Cor primária do botão |
| --vero-primary-text | #ffffff | Cor do texto no botão primário |
:root {
--vero-radius: 0.25rem; /* botões quadrados */
--vero-primary: #1d4ed8; /* azul da sua marca */
--vero-primary-text: #ffffff;
--vero-font: 'Inter', sans-serif;
}Anular uma factura ou um recibo
Este SDK corre no browser com a chave pública (pk_...), que o servidor só deixa pesquisar clientes e emitir facturas. De propósito: se alguém copiar a chave do código da página, não consegue anular documentos. Para anular, use o seu servidor com a chave secreta, pelo @veroao/node ou pela API REST:
// No SEU servidor (chave secreta vero_..._sk_), nunca no browser
import { createVeroClient } from '@veroao/node'
const vero = createVeroClient()
// Factura: anula-se com uma Nota de Crédito (NC), que a AGT valida
await vero.creditNotes.create(orgId, invoiceId, 'Devolução do artigo')
// Recibo emitido por engano (@veroao/node 1.2+). A AGT só aceita:
// 'N' - não foi enviado ao cliente · 'I' - cliente identificado incorrectamente
await vero.receipts.cancel(orgId, receiptId, { reason: 'N' })Na página do seu site, chame um endpoint seu (ex.: POST /anular) que faz isto no servidor. Detalhes em Notas de Crédito e em Recibos, na referência da API.
Segurança
O widget usa pk_... (chave pública) - segura para ser exposta no HTML. Nunca use vero_live_sk_... no frontend. O montante é validado no servidor antes da emissão.