Vero
DevelopersDashboard
Client-side@veroao/react v2.2.0React ≥ 18TypeScript nativo

React SDK

Hooks e componentes React para gerir facturação no frontend. Usa uma chave pública - sem expor a chave secreta no browser.

Hooks

useInvoice · useCustomer · useOrg

Performance

Memoized · Zero re-renders inúteis

Tipagem

TypeScript nativo · Tipos completos

Hooks disponíveis

useInvoice()Criar e consultar facturas
useCustomer()Criar e pesquisar clientes
useOrg()Dados da organização activa

Instalação

npm
npm install @veroao/react

VeroProvider

Envolva a raiz da sua app no VeroProvider. Use a chave pública pk_... - nunca a chave secreta.

app/layout.tsx (Next.js)
import { VeroProvider } from '@veroao/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <VeroProvider
          publicKey={process.env.NEXT_PUBLIC_VERO_KEY!}
          orgId={process.env.NEXT_PUBLIC_VERO_ORG!}
        >
          {children}
        </VeroProvider>
      </body>
    </html>
  )
}

useCustomer

Garante que o cliente existe na plataforma antes de emitir a factura.

hooks/useCheckout.ts
import { useCustomer } from '@veroao/react'

export function useCheckout() {
  const { ensureCustomer, isLoading, error } = useCustomer()

  const getOrCreateCustomer = async (user: User) => {
    return ensureCustomer({
      taxId: user.nif,     // ex: '000000000BA000'
      name: user.name,
      email: user.email,
    })
  }

  return { getOrCreateCustomer, isLoading, error }
}

useInvoice

Emite facturas e acompanha o estado da emissão em tempo real.

components/CheckoutButton.tsx
import { useCustomer, useInvoice } from '@veroao/react'

export function CheckoutButton({ user, cart }) {
  const { ensureCustomer } = useCustomer()
  const { createInvoice, isLoading, error } = useInvoice()

  const handleCheckout = async () => {
    // 1. Garantir cliente
    const customer = await ensureCustomer({
      taxId: user.nif,
      name: user.name,
      email: user.email,
    })

    // 2. Emitir Factura-Recibo
    const invoice = await createInvoice({
      customerId: customer.id,
      documentType: 'FR',
      items: cart.map(item => ({
        description: item.name,
        quantity: item.qty,
        unitPrice: item.priceCents,
        taxRate: 0.14,
      })),
    })

    // 3. Abrir PDF certificado
    window.open(invoice.pdfUrl, '_blank')
  }

  return (
    <button onClick={handleCheckout} disabled={isLoading}>
      {isLoading ? 'A emitir factura...' : 'Pagar e obter factura'}
    </button>
  )
}

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.

Chave pública vs. secreta

O React SDK usa pk_... (chave pública) - segura para o browser. Nunca use vero_live_sk_... no frontend. Para operações privilegiadas, use o Node.js SDK no servidor.