Central de Ajuda Conversa Labs
pt_BR
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

API de Plataforma (provisionamento multi-conta)

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Conversa Labs

Conversa Labs

Última atualização em Jul 27, 2026

Visão geral

A API de Plataforma opera acima das contas: ela permite criar e gerenciar contas, usuarios, vinculos usuario-conta e agent bots de forma programatica. Tudo fica sob um Platform App — uma aplicacao de plataforma que o operador cria e que recebe um token proprio.

Diferenca para a API REST da conta:

  • A API REST trabalha dentro de uma unica conta (contatos, conversas, mensagens) e usa o token de um usuario/agente daquela conta.
  • A API de Plataforma trabalha entre contas (provisionamento e ciclo de vida) e usa o token do Platform App. Os endpoints ficam sob o prefixo /platform/api/v1.

Um Platform App so enxerga e altera os objetos que estao na sua lista de permissiveis (as contas, usuarios e bots que ele mesmo criou ou que foram associados a ele).

Pre-requisitos

  • Um Platform App criado pelo operador (em Super Admin -> Platform Apps).
  • O token de acesso desse Platform App (gerado junto com o app).
  • O token deve trafegar apenas no backend do operador — nunca no front-end.

Passo a passo

  1. O operador cria um Platform App em Super Admin -> Platform Apps. Ao salvar, a plataforma gera um token de acesso vinculado ao app.

  2. Autentique cada chamada incluindo o cabecalho api_access_token com o token do Platform App. Se o token nao pertencer a um Platform App, a resposta e 401 Invalid access_token.

  3. Crie uma conta:

    POST /platform/api/v1/accounts
api_access_token: <token-da-plataforma>
Content-Type: application/json

{ "name": "Cliente XPTO", "locale": "pt_BR", "support_email": "suporte@cliente.com" }

    A conta criada e adicionada automaticamente aos permissiveis do app.

  4. Crie um usuario:

    POST /platform/api/v1/users
{ "name": "Maria", "email": "maria@cliente.com", "password": "<senha-forte>" }

    O usuario tambem entra nos permissiveis do app. Se ja existir um usuario com aquele e-mail, a plataforma reaproveita o usuario existente.

  5. Vincule usuario e conta (account_user) com papel:

    POST /platform/api/v1/accounts/<account_id>/account_users
{ "user_id": <user_id>, "role": "administrator" }

    Use administrator ou agent no campo role.

  6. Provisione agent bots:

    POST /platform/api/v1/agent_bots
{ "name": "Bot de Vendas", "account_id": <account_id>, "outgoing_url": "https://meu-bot/webhook" }

Endpoints complementares: GET/PATCH/DELETE /platform/api/v1/accounts/:id, GET :id e DELETE :id de usuarios, GET .../account_users (listar), DELETE .../account_users (remover vinculo), GET :id/login (gera um link de acesso SSO para o usuario) e POST :id/token.

Configuracoes & opcoes

  • Objetos permissiveis: cada Platform App mantem uma lista de contas, usuarios e agent bots que pode gerenciar. Objetos que o app cria entram nessa lista automaticamente.
  • Escopo do token: o token do Platform App so atua sobre os permissiveis do app — ele nao alcanca contas/usuarios de outros apps nem dados internos de uma conta (para isso, use a API REST da conta).
  • Parametros de conta: name, locale, domain, support_email, status, alem de features, limits e custom_attributes.
  • Parametros de usuario: name, display_name, email, password e custom_attributes.

Casos de uso

  • Onboarding multi-tenant / revenda: criar uma conta por cliente e popular usuarios em massa.
  • Provisionamento estilo SSO: criar o usuario e gerar o link de login (GET :id/login) para levar o usuario direto ao painel sem senha manual.
  • Ciclo de vida automatizado: criar, atualizar e desativar contas e vinculos a partir do seu proprio sistema (ex.: ao concluir ou cancelar uma assinatura).

Dicas, limites e boas praticas

  • Mantenha o token do Platform App somente no backend do operador. Ele tem poder de provisionamento — nunca o exponha no front-end nem em apps cliente.
  • Trabalhe com permissoes restritas: o app so deve tocar nos objetos que ele mesmo criou.
  • A remocao de contas e usuarios e assincrona (enfileirada) — a resposta 200 indica que a exclusao foi agendada, nao concluida no mesmo instante.
  • Trate idempotencia: criar um usuario com e-mail ja existente reaproveita o registro; criar o mesmo vinculo conta-usuario nao duplica.

Solucao de problemas

  • 401 Invalid access_token: o token nao pertence a um Platform App (ou esta ausente/incorreto no cabecalho api_access_token).
  • 401 Non permissible resource: o objeto (conta/usuario/bot) nao esta na lista de permissiveis do app — voce esta tentando alterar algo que o app nao gerencia.
  • 404: o id informado nao existe.

Veja tambem