## 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

- [API REST, tokens e webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br)
- [Referencia de API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)
- [Visao geral de API & Desenvolvedores](/hc/ajuda/articles/api-developers-overview-pt-br)