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.


POST/external/v1/accounts

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
}
  • apiKey aparece apenas nesta resposta: guarde-a nessa altura ou crie novamente a subconta para obter outra. É uma chave User com os âmbitos predefinidos anteriores, que excluem events: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 externalId devolve essa subconta, reativada se estava desativada, sem alterar o nome. Cada chamada emite outra chave, salvo se issueKey for false. 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.

GET/external/v1/accounts

Listar subcontas

Todas as subcontas, incluindo as desativadas com active a false, pela ordem de criação. A lista nunca inclui chaves.


DELETE/external/v1/accounts/{accountId}

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-Key sã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 externalId sem subconta ativa devolve 404 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 externalId no account de cada evento. Consulte Webhooks.
  • Os modelos SMS enviados por uma subconta são os que partilha com ela. Consulte Modelos.
Esta página foi útil?