Vero
DevelopersDashboard
Software houses

Box: facturar em nome dos teus clientes

Tens um software (ERP, POS, gestão) e queres que os teus clientes emitam facturas certificadas pela AGT a partir dele? Com o Box, juntas as empresas dos teus clientes ao Vero e emites pela API em nome de cada uma. As facturas saem sempre em nome da empresa cliente e são comunicadas à AGT.

Como funciona

  1. Cria o teu Box no dashboard, em Box (menu lateral).
  2. Junta a empresa do cliente com o NIF e o email dela. O Vero vai buscar o nome à AGT. Se a empresa ainda não usa o Vero, criamos a conta dela - a empresa é sempre a dona da sua conta.
  3. A empresa autoriza pelo link que recebe no email (ou dentro do Vero, em Definições). Até lá já podes configurá-la, mas nenhum documento é emitido em nome dela.
  4. Configura a empresa: abre-a a partir do Box e regista a chave privada AGT dela em Definições › Segurança.
  5. Cria a chave de API da empresa em Chaves de API, com a empresa aberta. Cada empresa tem a sua chave e o seu orgId.
  6. Emite pela API com a chave dessa empresa - exactamente como na API de Facturas.

No teu software: uma chave por cliente

Guarda, para cada cliente teu, o orgId e a chave de API da empresa dele - sempre no servidor, nunca no browser nem na app. Cada pedido usa a chave do cliente para quem estás a emitir.

Terminal
curl -X POST https://api.vero.ao/v1/organisations/ORG_ID_DO_CLIENTE/invoices \
  -H "Authorization: Bearer vero_live_sk_CHAVE_DO_CLIENTE" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "...",
    "documentType": "FR",
    "items": [{ "description": "Consultoria", "quantity": 1, "unitPrice": 2500000, "taxRate": 14 }],
    "idempotencyKey": "venda-8841"
  }'
TypeScript
// Node 18+ - no teu backend
async function emitirParaCliente(cliente, venda) {
  const res = await fetch(`https://api.vero.ao/v1/organisations/${cliente.veroOrgId}/invoices`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${cliente.veroApiKey}`, // chave DESTA empresa
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ customerId: venda.customerId, documentType: 'FR', items: venda.items, idempotencyKey: venda.id }),
  })
  const body = await res.json()
  if (res.status === 403 && body.error === 'box_consent_pending') {
    throw new Error('A empresa ainda não autorizou o teu Box - reenvia o pedido no painel do Box.')
  }
  if (res.status === 402) throw new Error('Emissão suspensa: renova o Box em Box › Pagamentos.')
  if (res.status === 401) throw new Error('Chave revogada - a empresa pode ter saído do Box.')
  if (!res.ok) throw new Error(body.error)
  return body
}

Respostas específicas do Box

EstadoErroO que significa
403box_consent_pendingA empresa ainda não autorizou o Box. Reenvia o pedido no painel.
402plan_expiredO período pago do Box acabou (ou o Box foi suspenso). Renova em Box › Pagamentos.
401—Chave revogada. Acontece quando a empresa retira o acesso ao Box ou a removes.

Pagamento

  • Pagas o preço normal do Vero por cada empresa activa (autorizada), por mês ou por ano. As empresas não pagam nem recebem avisos de cobrança.
  • Todas as empresas do Box ficam pagas até à mesma data. Uma empresa que entra a meio fica incluída até lá e conta a partir da renovação seguinte.
  • Avisamos-te por email 7 dias antes do fim do período. Sem pagamento, as empresas deixam de emitir documentos novos; os já emitidos continuam válidos.
  • Recebes uma factura-recibo do Vero por cada pagamento.

A empresa continua a mandar

  • A empresa pode entrar no Vero com o email dela e ver todas as facturas.
  • Pode retirar o acesso ao Box quando quiser. Nesse momento perdes o acesso e as chaves que criaste para ela são revogadas.
  • O Box nunca pode apagar a empresa, dar acesso a contabilistas nem mudar o plano dela.

Webhooks

Os webhooks são por empresa: com a empresa aberta a partir do Box, configura-os em Webhooks. Ver Segurança de Webhooks.