Zero-codecdn.vero.ao/widget.js v1.3.0Web ComponentSem dependências

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.

index.html
<!-- 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.

CheckoutButton.tsx
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.

AtributoTipoObrig.Descrição
api-keystringsimChave pública pk_... da organização
org-idstringsimID da organização (org_...)
amountnumbersimValor em cêntimos (AOA). Ex: 15000 = 150,00 AOA
customer-nifstring-NIF do cliente - pré-preenche o formulário
customer-namestring-Nome do cliente - pré-preenche o formulário
descriptionstring-Descrição do produto ou serviço
document-typestring-"FT" (Factura) ou "FR" (Factura-Recibo). Default: "FR"
themestring-"light" ou "dark". Default: detecta prefers-color-scheme
localestring-"pt" ou "en". Default: "pt"

Eventos

O widget dispara CustomEvents no elemento. Ouça com addEventListener ou os atributos on-*.

EventodetailQuando
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ávelDefaultDescrição
--vero-radius0.75remBorder-radius dos botões e painéis
--vero-fontinheritFamília de tipos - herda da página por omissão
--vero-primary#18181bCor primária do botão
--vero-primary-text#ffffffCor do texto no botão primário
Exemplo de personalização
: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:

TypeScript
// 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.