API Docs

Endpoints REST para integrar com a plataforma. Autenticação via Authorization: Bearer <api_token>.

Seu API Token

pessoal / não compartilhe
carregando…

Auth

GET/api/v1/me

Usuário atual

Retorna os dados do usuário dono do token.

Response 2xx

{
  "user": {
    "id": "uuid",
    "name": "João",
    "email": "joao@acme.com",
    "role": "admin",
    "can_manage_numbers": true,
    "active": true
  }
}

cURL

curl -X GET "https://your-domain.com/api/v1/me" \
  -H "Authorization: Bearer SEU_TOKEN"
POST/api/v1/me/token

Rotacionar token

Gera um novo api_token para o usuário atual. O token antigo para de funcionar imediatamente.

Response 2xx

{
  "api_token": "env_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

cURL

curl -X POST "https://your-domain.com/api/v1/me/token" \
  -H "Authorization: Bearer SEU_TOKEN"

Celulares

GET/api/v1/accounts

Listar celulares / números WABA

Admin: retorna todos os números da plataforma. Usuário: apenas os números atribuídos a ele.

Response 2xx

{
  "accounts": [
    {
      "id": "uuid",
      "name": "Número Principal",
      "phone": "5511999999999",
      "phone_id": "meta_phone_id",
      "chatwoot_active": true,
      "chatwoot_url": "https://chat.acme.com",
      "chatwoot_inbox_id": "42",
      "chatwoot_account_id": "1",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

cURL

curl -X GET "https://your-domain.com/api/v1/accounts" \
  -H "Authorization: Bearer SEU_TOKEN"

Usuários

GET/api/v1/usersadmin only

Listar / buscar usuários

Admin only. Filtros opcionais via query string: ?email=foo@bar.com (match exato), ?q=maria (busca parcial por email ou nome, case-insensitive), ?role=admin|user, ?active=true|false. Sem filtros retorna todos.

Response 2xx

{
  "users": [
    {
      "id": "uuid",
      "name": "Maria",
      "email": "maria@acme.com",
      "role": "user",
      "can_manage_numbers": false,
      "active": true,
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-02T10:00:00Z"
    }
  ],
  "count": 1
}

cURL

curl -X GET "https://your-domain.com/api/v1/users" \
  -H "Authorization: Bearer SEU_TOKEN"
POST/api/v1/usersadmin only

Criar usuário

Admin only. Cria o usuário e opcionalmente já atribui celulares.

Request Body

{
  "name": "Maria Silva",
  "email": "maria@acme.com",
  "password": "senha-forte-aqui",
  "role": "user",
  "can_manage_numbers": false,
  "account_ids": [
    "account-uuid-1",
    "account-uuid-2"
  ]
}

Response 2xx

{
  "user": {
    "id": "new-uuid",
    "name": "Maria Silva",
    "email": "maria@acme.com",
    "role": "user",
    "can_manage_numbers": false,
    "active": true,
    "api_token": "env_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2026-04-21T00:00:00Z"
  }
}

cURL

curl -X POST "https://your-domain.com/api/v1/users" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Silva",
  "email": "maria@acme.com",
  "password": "senha-forte-aqui",
  "role": "user",
  "can_manage_numbers": false,
  "account_ids": [
    "account-uuid-1",
    "account-uuid-2"
  ]
}'
GET/api/v1/users/{id}

Buscar usuário

Retorna um usuário específico. Admin pode buscar qualquer um; usuários comuns só a si mesmos.

Response 2xx

{
  "user": {
    "id": "uuid",
    "name": "Maria",
    "email": "maria@acme.com",
    "role": "user",
    "can_manage_numbers": false,
    "active": true
  }
}

cURL

curl -X GET "https://your-domain.com/api/v1/users/{id}" \
  -H "Authorization: Bearer SEU_TOKEN"
PATCH/api/v1/users/{id}admin only

Editar usuário

Admin only. Todos os campos são opcionais. Informe password para redefinir a senha.

Request Body

{
  "name": "Maria S.",
  "email": "maria.nova@acme.com",
  "role": "admin",
  "can_manage_numbers": true,
  "active": true,
  "password": "nova-senha-opcional"
}

Response 2xx

{
  "user": {
    "id": "uuid",
    "name": "Maria S.",
    "email": "maria.nova@acme.com",
    "role": "admin",
    "can_manage_numbers": true,
    "active": true
  }
}

cURL

curl -X PATCH "https://your-domain.com/api/v1/users/{id}" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria S.",
  "email": "maria.nova@acme.com",
  "role": "admin",
  "can_manage_numbers": true,
  "active": true,
  "password": "nova-senha-opcional"
}'

Permissões

GET/api/v1/users/{id}/accounts

Ver permissões (celulares) do usuário

Retorna os celulares que o usuário pode acessar. Admin pode consultar qualquer usuário; usuário comum só ele mesmo.

Response 2xx

{
  "account_ids": [
    "account-uuid-1",
    "account-uuid-2"
  ],
  "accounts": [
    {
      "id": "account-uuid-1",
      "name": "Número 1",
      "phone": "5511999999999"
    }
  ]
}

cURL

curl -X GET "https://your-domain.com/api/v1/users/{id}/accounts" \
  -H "Authorization: Bearer SEU_TOKEN"
PUT/api/v1/users/{id}/accountsadmin only

Definir permissões do usuário

Admin only. Substitui a lista completa de celulares atribuídos ao usuário.

Request Body

{
  "account_ids": [
    "account-uuid-1",
    "account-uuid-3"
  ]
}

Response 2xx

{
  "ok": true,
  "account_ids": [
    "account-uuid-1",
    "account-uuid-3"
  ]
}

cURL

curl -X PUT "https://your-domain.com/api/v1/users/{id}/accounts" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "account_ids": [
    "account-uuid-1",
    "account-uuid-3"
  ]
}'

SSO

POST/api/v1/sso

Gerar link de login automático (SSO)

Gera uma URL temporária de uso único. Ao abrir no navegador, o usuário é logado automaticamente e redirecionado para /dashboard. TTL padrão 120s (min 30s, max 600s). Admins podem gerar para outro usuário informando user_id; usuários comuns só para si.

Request Body

{
  "user_id": "uuid (apenas admin; omita para gerar para si mesmo)",
  "ttl_seconds": 120
}

Response 2xx

{
  "url": "https://app.acme.com/api/sso/consume?t=sso_xxxxxxxx",
  "token": "sso_xxxxxxxx",
  "expires_at": "2026-04-21T00:02:00Z",
  "ttl_seconds": 120
}

cURL

curl -X POST "https://your-domain.com/api/v1/sso" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "uuid (apenas admin; omita para gerar para si mesmo)",
  "ttl_seconds": 120
}'