Empresas

A tua conta pode gerir várias empresas. Cada empresa tem o seu próprio NIF, chave RSA e chaves de API — mas o plano de facturação é partilhado por todas as empresas da conta.

Esta página assume que já tens uma conta e um token de acesso (access_token) — obtidos ao criar conta/entrar na aplicação. O que fica aqui é como adicionar e gerir empresas a partir daí.

Listar as tuas empresas

GET /v1/companies

curl https://<host>/v1/companies \
  -H "Authorization: Bearer <access_token>"

const res = await fetch('https://<host>/v1/companies', {
  headers: { 'Authorization': `Bearer ${accessToken}` },
})
const companies = await res.json()

response = requests.get(
    "https://<host>/v1/companies",
    headers={"Authorization": f"Bearer {access_token}"},
)
companies = response.json()

$ch = curl_init("https://<host>/v1/companies");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $accessToken]);
$companies = json_decode(curl_exec($ch), true);

[
  {
    "tenant_id": "b3f1c2a4-1234-4a5b-9c6d-7e8f9a0b1c2d",
    "name": "Empresa A Lda",
    "nif": "5001234567",
    "establishment_number": "SEDE",
    "role": "tenant_owner",
    "status": "active",
    "created_at": "2026-06-01T10:00:00Z"
  }
]

Adicionar uma nova empresa

POST /v1/companies

curl -X POST https://<host>/v1/companies \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa B Lda",
    "nif": "5001234568",
    "establishment_number": "SEDE"
  }'

const res = await fetch('https://<host>/v1/companies', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Empresa B Lda',
    nif: '5001234568',
    establishment_number: 'SEDE',
  }),
})
const company = await res.json()

response = requests.post(
    "https://<host>/v1/companies",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Empresa B Lda",
        "nif": "5001234568",
        "establishment_number": "SEDE",
    },
)
company = response.json()

$ch = curl_init("https://<host>/v1/companies");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Empresa B Lda',
    'nif' => '5001234568',
    'establishment_number' => 'SEDE',
]));
$company = json_decode(curl_exec($ch), true);

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome da empresa.
`nif`	string	sim	NIF — tem de ser único no sistema.
`establishment_number`	string	não	Por omissão `"0"`.
`private_key_pem`	string	não	Chave privada RSA (PEM, mín. 2048 bits) do contribuinte. Se enviada, é validada e guardada já nesta chamada — poupa um passo depois em `/v1/client/chaves/upload`.

{
  "tenant_id": "0679d0f4-862e-4b6a-913f-c6fb0fbf78c4",
  "name": "Empresa B Lda",
  "nif": "5001234568",
  "establishment_number": "SEDE",
  "role": "tenant_owner",
  "status": "active",
  "created_at": "2026-08-10T10:54:28.813675Z",
  "api_key": "agt_live_XXXXXXXX.xxxxxxxxxxxxxxxxxxxxxx"
}

A empresa nova entra logo a partilhar o mesmo plano de facturação da conta — não é criado um novo. Já vem com uma chave de API própria — cada empresa tem a sua, mesmo partilhando conta e facturação (ver Autenticação).

⚠️

api_key só aparece nesta resposta, no momento da criação — guarda-a já, não é mostrada novamente. GET /v1/companies (listagem) nunca a devolve.

⚠️

Uma private_key_pem inválida (formato errado, não-RSA, ou menos de 2048 bits) devolve 400 e nada é criado — nem a empresa. Corrige a chave e repete o pedido.

409 se já existir uma empresa com este NIF.

Activar a empresa nova no teu token

O token que já tinhas continua apontado para a empresa (ou estado) anterior. Para passares a usar a empresa que acabaste de criar nas rotas /v1/client/*, troca a empresa activa:

POST /v1/select-tenant

curl -X POST https://<host>/v1/select-tenant \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "0679d0f4-862e-4b6a-913f-c6fb0fbf78c4"}'

const res = await fetch('https://<host>/v1/select-tenant', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ tenant_id: company.tenant_id }),
})
const token = await res.json()

response = requests.post(
    "https://<host>/v1/select-tenant",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tenant_id": company["tenant_id"]},
)
token = response.json()

$ch = curl_init("https://<host>/v1/select-tenant");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['tenant_id' => $company['tenant_id']]));
$token = json_decode(curl_exec($ch), true);

Devolve um novo access_token, agora com tenant_id a apontar para essa empresa. 403 se a conta não estiver vinculada a esse tenant_id.

Editar empresa, activar/desactivar

PATCH /v1/companies/{tenant_id}

Só quem tem role: tenant_owner nesta empresa pode chamar este endpoint.

curl -X PATCH https://<host>/v1/companies/<tenant_id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'

const res = await fetch(`https://<host>/v1/companies/${tenantId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'suspended' }),
})

response = requests.patch(
    f"https://<host>/v1/companies/{tenant_id}",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"status": "suspended"},
)

$ch = curl_init("https://<host>/v1/companies/{$tenantId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['status' => 'suspended']));
curl_exec($ch);

Campo	Tipo	Obrigatório	Descrição
`name`	string	não	Novo nome.
`establishment_number`	string	não	Novo número de estabelecimento.
`status`	`"active"` \| `"suspended"`	não	Activar ou desactivar a empresa.

⚠️

Desactivar (status: "suspended") bloqueia de imediato o acesso a essa empresa — via JWT (/v1/client/tenant/*) e via chave de API (X-API-Key) — com 403. Billing e as outras empresas da conta não são afectados. Reactiva com o mesmo endpoint (status: "active") a qualquer momento; a gestão em si nunca fica bloqueada, mesmo com a empresa desactivada.

404 se a empresa não existir ou não estiver vinculada à tua conta. 403 se não fores tenant_owner desta empresa.

Autenticação Erros