@veroao/widget

Botão de checkout embutível para o Vero - um <script> e um elemento HTML, sem dependências, sem necessidade de framework. Abre um modal para pesquisar/seleccionar cliente e emite a factura.

Instalação

Via <script> (qualquer site)

<script src="https://unpkg.com/@veroao/widget"></script>

<vero-button
  api-key="vero_live_pk_..."
  org-id="TEU_ORG_ID"
  amount="500000"
  description="Plano Pro - Mensal"
  document-type="FR"
>
  Pagar agora
</vero-button>

Via npm (Vite, Webpack, etc.)

npm install @veroao/widget

import '@veroao/widget' // regista o custom element <vero-button>

Chave publicável - segura para o browser

Usa sempre uma chave publicável (vero_live_pk_... / vero_test_pk_...), nunca a chave secreta do @veroao/node. Cria-a no dashboard, em Chaves de API, escolhendo o tipo "Publicável" - o servidor recusa-a em qualquer rota que não seja a de pesquisa de clientes / emissão de factura, mesmo que alguém a copie do código-fonte da página.

Atributos

| Atributo | Obrigatório | Descrição | |------------------|:-----------:|---------------------------------------------------------------------| | api-key | sim | Chave publicável | | org-id | sim | UUID da tua organização no Vero | | amount | sim | Valor em kwanzas × 100 (ex: 500000 = 5 000,00 AOA) | | description | não | Pré-preenche a descrição do item | | customer-nif | não | Pré-preenche a pesquisa de cliente pelo NIF | | customer-name | não | Pré-preenche a pesquisa de cliente pelo nome | | document-type | não | FT ou FR (default FR - pagamento imediato) | | theme | não | light (default) ou dark | | locale | não | pt (default) ou en | | base-url | não | Override da API base - útil para testes locais |

Eventos

O elemento emite CustomEvents normais do DOM:

<vero-button
  id="btn"
  api-key="vero_live_pk_..."
  org-id="..."
  amount="500000"
></vero-button>

<script>
  const btn = document.getElementById('btn')

  btn.addEventListener('on-success', (e) => {
    console.log(e.detail.invoiceId, e.detail.pdfUrl, e.detail.atcud)
  })

  btn.addEventListener('on-error', (e) => {
    console.error(e.detail.code, e.detail.message)
  })

  btn.addEventListener('on-open', () => console.log('modal aberto'))
  btn.addEventListener('on-close', () => console.log('modal fechado'))
</script>

Alternativa: define o nome de uma função global no próprio atributo (on-success="minhaFuncao").

Personalização visual

Variáveis CSS aplicadas via style ou uma folha de estilos global:

vero-button {
  --vero-primary: #0070f3;
  --vero-primary-text: #ffffff;
  --vero-radius: 8px;
  --vero-font: 'Inter', sans-serif;
}

Em React / Vue / outros frameworks

O widget é um Web Component nativo - funciona em qualquer framework sem wrapper especial:

import '@veroao/widget'

function Checkout() {
  return (
    <vero-button api-key="vero_live_pk_..." org-id={orgId} amount="500000">
      Pagar agora
    </vero-button>
  )
}

Este pacote ainda não publica declarações TypeScript para o elemento <vero-button> - em projectos TS, declara-o tu mesmo (declare global { namespace JSX { interface IntrinsicElements { 'vero-button': React.DetailedHTMLProps<...> } } }) ou usa ref + addEventListener como no exemplo de eventos acima.

Se precisares de um hook React em vez de um elemento HTML, considera @veroao/react.

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

Este widget só sabe fazer duas coisas, de propósito: pesquisar cliente e emitir factura. A chave publicável que usa é restrita pelo servidor a essas rotas - não há forma de gerir produtos, listar facturas existentes, emitir notas de crédito/débito ou apagar clientes com ela.

Para isso, precisas de um backend teu que use @veroao/node com a chave secreta:

Página com <vero-button>  →  o TEU backend  →  Vero (com @veroao/node + chave secreta)

O widget nunca deve ser o único ponto de contacto com o Vero se precisares de mais do que emitir facturas simples a partir do browser.

Esse backend não precisa de ser Node - @veroao/node é só a opção mais directa. 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.