Autenticação
A API do Vero utiliza Chaves de API para autenticar pedidos. Cada pedido deve incluir a sua chave no cabeçalho de autorização.
Ambiente de teste
vero_test_sk_...Documentos gerados localmente (número, PDF) - nunca chegam à AGT, não têm ATCUD real nem qualquer valor fiscal. Use para desenvolvimento e integração.
Ambiente de produção
vero_live_sk_...Documentos certificados pela AGT em produção - valor fiscal real. Nunca exponha no frontend.
Chave Secreta vs. Publicável
Além do ambiente (teste/produção), cada chave tem um tipo, escolhido na criação em Chaves de API:
Secreta
vero_live_sk_...Acesso total à API - criar/editar/apagar clientes, produtos, facturas, notas, tudo. Usa apenas no teu servidor (Node.js SDK). Nunca a exponhas no browser - qualquer pessoa que a veja no código-fonte da página pode usá-la para aceder à tua organização.
Publicável
vero_live_pk_...Restrita, no servidor, a pesquisar clientes e emitir facturas através do widget de checkout - nada mais. Segura para colocar no browser (SDK React, widget HTML). Mesmo que alguém a copie da página, só consegue usá-la para essas duas acções.
Cabeçalho de Autorização
Inclua a sua chave de API usando o esquema Bearer no cabeçalho HTTP:
curl https://api.vero.ao/v1/organisations \
-H "Authorization: Bearer vero_test_sk_sua_chave_aqui"Sandbox
Com uma chave vero_test_sk_..., facturas, notas de crédito e notas de débito são geradas inteiramente em local - número marcado como TESTE, sem ATCUD real, sem assinatura e sem qualquer contacto com a AGT, mesmo que a organização já tenha chaves de produção configuradas.
| Comportamento | Teste (sandbox) | Produção |
|---|---|---|
| Número do documento | Ex: FT TESTE/A3B2C1 | Ex: FT FT6326S62896N/1 |
| Pedido enviado à AGT | Nunca | Sim |
| ATCUD / assinatura JWS | Não gerados | Sim, reais |
| PDF emitido | Sim (marca de água de teste) | Sim |
| Valor fiscal | Nenhum | Sim |
| Exige chaves AGT configuradas | Não | Sim |
| Cliente criado via customers.ensure() | Efémero, id sandbox_cus_..., não persiste | Gravado na base de dados, id UUID |
O ambiente é detectado automaticamente pela chave usada - não precisas de configurar nada extra. Para trocar para produção, substitui a chave vero_test_sk_ por vero_live_sk_. Também existe uma chave de sandbox pública e partilhada (sem necessidade de conta) em GET /v1/sandbox, usada pelo botão "experimentar agora" em /developers.
Chave Pública
Para integrações no frontend (React SDK, Widget), use a chave pública pk_.... Ela tem permissões limitadas e é segura para ser exposta no browser.
import { VeroProvider } from '@veroao/react'
export default function RootLayout({ children }) {
return (
<VeroProvider
publicKey={process.env.NEXT_PUBLIC_VERO_KEY!} // pk_...
orgId={process.env.NEXT_PUBLIC_VERO_ORG!}
>
{children}
</VeroProvider>
)
}Revogar Chaves
Gerencie as suas chaves de API em Dashboard → Chaves de API. Pode criar múltiplas chaves (ex: uma por serviço) e revogar individualmente sem afectar as outras.
Aviso de Segurança
Se suspeitar que a sua chave foi comprometida, revogue-a imediatamente no painel e gere uma nova. As chaves secretas têm acesso total à sua conta.