Vero
DevelopersDashboard

Organisations API

Gere as empresas associadas à tua conta. Cada empresa tem o seu próprio NIF, chaves AGT, séries fiscais e clientes.

Criar Empresa

POST/v1/organisations

Requer o token de sessão (login), não uma API key - normalmente feito uma vez, no dashboard, ao criar a conta.

JSON
{
  "name": "Empresa Exemplo, Lda",
  "taxId": "5000123456",
  "email": "geral@exemplo.ao",
  "legalName": "Empresa Exemplo Comércio e Serviços, Lda",
  "phone": "923456789",
  "website": "https://exemplo.ao",
  "ivaRegime": "geral",
  "address": { "line1": "Rua da Missão, 123", "city": "Luanda", "province": "Luanda", "country": "AO" },
  "bankAccounts": [
    { "bankName": "BAI", "bankIban": "AO06...", "bankAccount": "123456789" }
  ]
}

Ver Detalhes da Empresa

GET/v1/organisations/:id

Resposta

JSON
{
  "id": "779b90ce-...",
  "userId": "a1b2c3d4-...",
  "name": "Empresa Exemplo, Lda",
  "legalName": "Empresa Exemplo Comércio e Serviços, Lda",
  "taxId": "5000123456",
  "email": "geral@exemplo.ao",
  "phone": "923456789",
  "website": "https://exemplo.ao",
  "addressLine1": "Rua da Missão, 123",
  "city": "Luanda",
  "province": "Luanda",
  "country": "AO",
  "bankAccounts": [{ "bankName": "BAI", "bankIban": "AO06...", "bankAccount": "123456789" }],
  "logoUrl": null,
  "ivaRegime": "geral",
  "defaultTaxRate": 14,
  "invoiceFormat": "a4",
  "withholdingTaxEnabled": true,
  "partialPaymentsEnabled": true,
  "withholdingTaxType": "II",
  "withholdingTaxRate": 650,
  "withholdingTaxThreshold": 2000000,
  "status": "active",
  "agtKeysConfigured": true,
  "createdAt": "2026-05-12T10:00:00.000Z",
  "updatedAt": "2026-05-12T10:00:00.000Z"
}

Nota: agtKeysConfigured é um booleano - as chaves AGT em si nunca são devolvidas por este endpoint, por segurança.

Os campos withholdingTax* controlam a retenção na fonte (Art. 67º do Código do Imposto Industrial). A retenção e os pagamentos parciais estão sempre ligados:withholdingTaxEnabled e partialPaymentsEnabled vêm sempre true e, se enviados no PATCH, são ignorados.withholdingTaxType é 'II' (Imposto Industrial) ou 'IRT' (pessoa singular/ENI); withholdingTaxRate é a percentagem × 100 (650 = 6,50%); withholdingTaxThreshold é o valor mínimo em kwanzas × 100 abaixo do qual a retenção não se aplica. Actualizável via PATCH (também disponível no dashboard, em Definições → Perfil). Ver applyWithholdingTax na Invoices API.

Contas de tesouraria (bancos, caixa, TPA)

Onde a empresa recebe o dinheiro. O id de uma conta vai em receivedIn ao emitir uma factura-recibo, converter uma proforma em FR ou emitir um recibo. Registar contas não tem limite; as marcadas com showOnDocuments (máx. 3, só bancos) são as impressas nas facturas e aparecem em bankAccounts. Todas as empresas têm uma Caixa. O campo bankAccounts no criar/editar empresa continua a funcionar: a lista enviada passa a ser a das contas mostradas nos documentos.

GET/v1/organisations/:orgId/treasury-accountsLista as contas (type: bank | cash | tpa, shortLabel, isDefault, showOnDocuments)
POST/v1/organisations/:orgId/treasury-accountsCria uma conta: type, bankName, iban, holder, accountNumber, swift, label, showOnDocuments, isDefault, settlesToAccountId (TPA)
PATCH/v1/organisations/:orgId/treasury-accounts/:idEdita, torna por omissão (isDefault) ou arquiva (archived)
DELETE/v1/organisations/:orgId/treasury-accounts/:idRemove; se já foi usada em documentos ou extratos, arquiva
GET/v1/organisations/:orgId/treasury/overview?year&monthSaldo de cada conta no mês: saldo no início, entradas, saídas, saldo final e comparação com o último extrato
GET/v1/organisations/:orgId/treasury/accounts/:id/ledger?year&monthMovimentos de uma conta no mês com saldo corrido
PUT/v1/organisations/:orgId/treasury/accounts/:id/openingSaldo inicial: openingBalance (cêntimos) no fim do dia openingDate
POST/v1/organisations/:orgId/treasury/movementsRegista saída (out), entrada sem documento (in) ou transferência (transfer, com fee e linkedDocs para depósitos de caixa)
DELETE/v1/organisations/:orgId/treasury/movements/:idApaga um movimento registado à mão

Outros endpoints

GET/v1/organisationsLista as empresas a que tens acesso
PATCH/v1/organisations/:idActualiza campos (mesma forma do corpo de criação)
POST/v1/organisations/:id/logoUpload do logótipo (multipart/form-data)
PUT/v1/organisations/:id/agt-keysRegista/actualiza as chaves AGT - ver Primeiros Passos
GET/v1/organisations/:id/agt-keys/statusVerifica se as chaves estão configuradas, sem as devolver
DELETE/v1/organisations/:id/agt-keysRemove as chaves AGT
DELETE/v1/organisations/:idRemove a empresa

Para o processo completo de configuração (chaves AGT, dados bancários, API keys), ver Primeiros Passos.