Subcontas
Uma plataforma que envia pelos seus clientes atribui uma subconta a cada um: uma organização Oblic própria, com remetentes, modelos, mensagens e relatórios próprios. A sua chave atua em nome dela ao identificá-la. Gerir subcontas exige uma chave Owner ou Admin com accounts:manage.
Criar uma subconta
- Nome
name- Tipo
- string
- Descrição
Obrigatório: o nome do cliente, até 511 caracteres.
- Nome
externalId- Tipo
- string
- Descrição
Obrigatório: o seu identificador do cliente, até 100 letras ASCII, algarismos e os caracteres
_,.,:e-. É usado para identificar a subconta posteriormente.
- Nome
issueKey- Tipo
- boolean
- Descrição
Indica se deve ser emitida uma chave API própria para a subconta; o valor predefinido é
true.
Criar uma subconta
curl -X POST https://api.oblic.app/external/v1/accounts \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "name": "Asha Textiles", "externalId": "tenant-4821" }'
Resposta
{
"status": "success",
"data": {
"id": "ORG000R7ZM4Q2VXH00",
"name": "Asha Textiles",
"externalId": "tenant-4821",
"active": true,
"createdAt": "2026-10-24T09:30:00Z",
"apiKey": "obl_live_…"
},
"errors": null
}
apiKeyaparece apenas nesta resposta: guarde-a nessa altura ou crie novamente a subconta para obter outra. É uma chave User com os âmbitos predefinidos anteriores, que excluemevents:write: permite enviar, ler e gerir identidades e listas de contactos, mas não aceder às rotas que exigem uma chave Owner ou Admin.- Repetir o mesmo
externalIddevolve essa subconta, reativada se estava desativada, sem alterar o nome. Cada chamada emite outra chave, salvo seissueKeyforfalse. As chaves anteriores continuam válidas, exceto as revogadas durante a desativação. - Uma subconta não tem subcontas: tentar criar uma ao atuar em nome de uma subconta devolve
403 SUB_ACCOUNT_NOT_ALLOWED.
Listar subcontas
Todas as subcontas, incluindo as desativadas com active a false, pela ordem de criação. A lista nunca inclui chaves.
Desativar uma subconta
Desativa a subconta pelo seu id Oblic, não pelo seu externalId, e revoga imediatamente todas as suas chaves. Criá-la novamente com o seu externalId volta a ativá-la. Uma subconta que não pertence à organização devolve 404 ACCOUNT_NOT_FOUND.
Atuar em nome de uma subconta
Envie X-Oblic-On-Behalf-Of com o externalId da subconta: o pedido é executado em nome dela como se usasse a sua própria chave. Uma única chave serve todos os clientes, sem guardar uma por cliente.
Enviar a partir da conta de um cliente
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'X-Oblic-On-Behalf-Of: tenant-4821' \
-H 'Content-Type: application/json' \
-d '{ "from": "hello@ashatextiles.example", "to": ["asha@example.org"], "subject": "Welcome", "html": "<p>Welcome!</p>" }'
- Da subconta: o email parte apenas das suas identidades; mensagens, relatórios, modelos, webhooks e valores
Idempotency-Keysão próprios da subconta. - Da sua organização: a sua carteira paga as mensagens e a sua lista de IP permitidos aplica-se aos pedidos feitos em nome da subconta.
- O papel da sua chave continua a aplicar-se: gira modelos, webhooks ou o número WhatsApp do cliente com a sua própria chave Owner ou Admin e o cabeçalho.
- Um
externalIdsem subconta ativa devolve404 ACCOUNT_NOT_FOUND. - Os eventos webhook da subconta vão para os endpoints da própria subconta, se existirem; caso contrário, para os da sua organização principal, com o
externalIdnoaccountde cada evento. Consulte Webhooks. - Os modelos SMS enviados por uma subconta são os que partilha com ela. Consulte Modelos.