# Equipe e permissões

> Pessoas, convites, equipes e atribuição de conversas.

São três permissões separadas: `equipe:ler` (pessoas, presença, convites abertos e equipes), `equipe:escrever` (equipes e atribuição de conversas) e `equipe:permissoes` (convidar, mudar permissões e remover). A última é sensível: o botão "Tudo" da tela de chaves não a marca, você marca de propósito.

- A chave nunca tem mais poder que um gestor e só mexe em **atendentes**. Dono e gestor aparecem nas listas, mas mudar, remover ou convidar alguém como dono ou gestor dá `403 sem_permissao`, mesmo que a chave tenha sido criada por um dono.
- O papel (atendente, gestor, dono) nunca muda pela API. Dá para mudar o papel de acesso, os WhatsApps visíveis, os módulos e a agenda de um atendente.
- Convite: a resposta traz o `link` uma única vez e o e-mail sai como na tela (mande `enviar_email: false` para só pegar o link). Vale 7 dias e conta no limite de acessos do plano. Até 20 convites por dia por organização e 3 por dia para o mesmo e-mail. Reenviar troca o link: o antigo para de valer.
- Não existe desativar: remover tira o acesso na hora e as conversas da pessoa ficam sem responsável. Para voltar, convide de novo.
- Atribuir conversa tem o mesmo efeito da tela: fica no histórico da conversa com o nome da chave, a pessoa recebe o aviso, o agente de IA pausa naquela conversa e sai o webhook `conversa.atribuida`.
- Eventos de webhook: `membro.convidado`, `membro.entrou`, `membro.alterado` (traz também `anterior`) e `membro.removido`.
- Toda mudança fica na auditoria da organização com o nome da chave. Ids de outra organização dão `404`.
- Fora da API de propósito: mudar papel, qualquer coisa com dono ou gestor, transferir a organização, plano e cobrança, horário e presença de cada pessoa (só leitura) e papéis de acesso (só pelo app).

**Códigos de erro comuns aqui**: `sem_permissao`, `ja_e_membro`, `limite_de_acessos`, `limite_de_convites`, `membro_inexistente`, `convite_inexistente`, `equipe_inexistente`, `equipe_repetida`, `papel_inexistente`, `modulos_do_papel`, `modulo_invalido`, `conversa_inexistente` (todos em [Erros](https://docs.forsi.com.br/erros)).

## GET /equipe/membros — Listar pessoas da equipe

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/membros`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Membro` (paginada por cursor)
- Página: https://docs.forsi.com.br/api/equipe/listar-membros (Markdown: https://docs.forsi.com.br/api/equipe/listar-membros.md)

Por ordem de entrada, paginado por cursor. Filtre por papel ou pelo e-mail exato.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `papel` | "dono" \| "gestor" \| "atendente" | não |  |
| `email` | string | não | E-mail exato de alguém DESTA organização. até 254 caracteres |
| `limite` | integer | não | Itens por página (1 a 100, padrão 50). |
| `cursor` | string | não | O valor de `proximo` da página anterior. até 80 caracteres |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/membros?papel=atendente" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "0e584d55-e895-4372-8945-cb64cafc6efd",
      "nome": "Ana Lima",
      "email": "ana@exemplo.com.br",
      "avatar_url": "https://chat.forsi.com.br/avatar.png",
      "papel": "dono",
      "papel_de_acesso_id": "646adc88-610e-4604-96fe-af5175dca375",
      "permissoes": {"caixas":["7a9d53e9-9d1b-4122-923b-fac67958f445"],"modulos":["texto"],"agenda":"todas"},
      "equipes": ["55174f08-dda3-49e6-bc5d-9309becdaf6d"],
      "disponivel": true,
      "disponivel_agora": true,
      "ausente_ate": "2026-10-04T13:05:12.481Z",
      "horario": {"dias":[1,2,3,4,5],"inicio":"08:00","fim":"18:00"},
      "ultimo_acesso": "2026-10-04T13:05:12.481Z",
      "entrou_em": "2026-10-04T13:05:12.481Z"
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /equipe/membros/{id} — Ver uma pessoa

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/membros/{id}`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Membro`
- Página: https://docs.forsi.com.br/api/equipe/ver-membro (Markdown: https://docs.forsi.com.br/api/equipe/ver-membro.md)

O `id` é o id da pessoa (usuário).

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/membros/0e584d55-e895-4372-8945-cb64cafc6efd" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "id": "0e584d55-e895-4372-8945-cb64cafc6efd",
    "nome": "Ana Lima",
    "email": "ana@exemplo.com.br",
    "avatar_url": "https://chat.forsi.com.br/avatar.png",
    "papel": "dono",
    "papel_de_acesso_id": "646adc88-610e-4604-96fe-af5175dca375",
    "permissoes": {"caixas":["7a9d53e9-9d1b-4122-923b-fac67958f445"],"modulos":["texto"],"agenda":"todas"},
    "equipes": ["55174f08-dda3-49e6-bc5d-9309becdaf6d"],
    "disponivel": true,
    "disponivel_agora": true,
    "ausente_ate": "2026-10-04T13:05:12.481Z",
    "horario": {"dias":[1,2,3,4,5],"inicio":"08:00","fim":"18:00"},
    "ultimo_acesso": "2026-10-04T13:05:12.481Z",
    "entrou_em": "2026-10-04T13:05:12.481Z"
  }
}
```

**Erros**: `401`, `403`, `404`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## PATCH /equipe/membros/{id} — Mudar permissões de um atendente

- URL: `PATCH https://chat.forsi.com.br/api/v1/equipe/membros/{id}`
- Acesso: escopo `equipe:permissoes` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Membro`
- Página: https://docs.forsi.com.br/api/equipe/atualizar-membro (Markdown: https://docs.forsi.com.br/api/equipe/atualizar-membro.md)

Papel de acesso, WhatsApps visíveis, módulos e agenda. Só os campos enviados mudam. Só vale para atendentes: dono e gestor (e contas de suporte da FORSI) dão 403 `sem_permissao` e só mudam pelo app. O papel (atendente, gestor, dono) nunca muda pela API. Dispara `membro.alterado`.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `papel_de_acesso_id` | uuid ou null | não | Papel de acesso (Configurações → Equipe → Papéis). Com papel, os módulos e a agenda vêm dele. null tira o papel. |
| `caixas` | lista de uuid | não | WhatsApps que a pessoa vê. Lista vazia = todos. até 200 itens |
| `modulos` | lista de "conversas" \| "contatos" \| "automacoes" \| "agentes" \| "funil" \| "agenda" \| "followup" \| "relatorios" | não | Módulos liberados. Só sem papel de acesso. até 8 itens |
| `agenda` | "todas" \| "propria" | não | Agenda: todas ou só a própria. Só sem papel de acesso. |

**Exemplo (curl)**

```bash
curl -X PATCH "https://chat.forsi.com.br/api/v1/equipe/membros/0e584d55-e895-4372-8945-cb64cafc6efd" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"modulos":["conversas","contatos","agenda"],"agenda":"propria"}'
```

**Resposta `200`**: mesmo formato do exemplo de `Membro` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## DELETE /equipe/membros/{id} — Tirar um atendente da equipe

- URL: `DELETE https://chat.forsi.com.br/api/v1/equipe/membros/{id}`
- Acesso: escopo `equipe:permissoes` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `ApagadoEquipe`
- Página: https://docs.forsi.com.br/api/equipe/remover-membro (Markdown: https://docs.forsi.com.br/api/equipe/remover-membro.md)

A pessoa perde o acesso na hora e as conversas dela ficam sem responsável. Só vale para atendentes: dono e gestor (e contas de suporte da FORSI) dão 403 `sem_permissao` e só mudam pelo app. Para voltar, convide de novo. Dispara `membro.removido`.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl -X DELETE "https://chat.forsi.com.br/api/v1/equipe/membros/0e584d55-e895-4372-8945-cb64cafc6efd" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{"dados":{"id":"44ccbf83-e9cc-43ae-a406-c7d8c1550e81","apagado":false}}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /equipe/presenca — Quem está disponível

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/presenca`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Presenca` (paginada por cursor)
- Página: https://docs.forsi.com.br/api/equipe/listar-presenca (Markdown: https://docs.forsi.com.br/api/equipe/listar-presenca.md)

Disponível agora = marcou disponível, não está ausente e está dentro do horário de trabalho (no fuso da organização).

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `equipe_id` | uuid | não | Só quem está nesta equipe. |
| `limite` | integer | não | Itens por página (1 a 100, padrão 50). |
| `cursor` | string | não | O valor de `proximo` da página anterior. até 80 caracteres |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/presenca?equipe_id=55174f08-dda3-49e6-bc5d-9309becdaf6d" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "9d77cca2-2aa9-45d6-aef4-707f6b6ee109",
      "nome": "Ana Lima",
      "papel": "dono",
      "disponivel": true,
      "disponivel_agora": true,
      "ausente_ate": "2026-10-04T13:05:12.481Z",
      "horario": {"dias":[1,2,3,4,5],"inicio":"08:00","fim":"18:00"},
      "ultimo_acesso": "2026-10-04T13:05:12.481Z"
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /equipe/convites — Listar convites abertos

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/convites`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Convite` (paginada por cursor)
- Página: https://docs.forsi.com.br/api/equipe/listar-convites (Markdown: https://docs.forsi.com.br/api/equipe/listar-convites.md)

Só os que ainda não foram aceitos nem venceram, do mais novo para o mais antigo. O link do convite nunca aparece aqui.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `limite` | integer | não | Itens por página (1 a 100, padrão 50). |
| `cursor` | string | não | O valor de `proximo` da página anterior. até 80 caracteres |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/convites" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "fac480ff-6cc4-47be-9a87-6270d519a659",
      "email": "nova.atendente@exemplo.com.br",
      "papel": "dono",
      "papel_de_acesso_id": "646adc88-610e-4604-96fe-af5175dca375",
      "convidado_por": "Ana Lima",
      "expira_em": "2026-10-04T13:05:12.481Z",
      "criado_em": "2026-10-04T13:05:12.481Z"
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /equipe/convites — Convidar atendente

- URL: `POST https://chat.forsi.com.br/api/v1/equipe/convites`
- Acesso: escopo `equipe:permissoes` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `201`, `{"dados": ...}` com `ConviteComLink`
- Página: https://docs.forsi.com.br/api/equipe/criar-convite (Markdown: https://docs.forsi.com.br/api/equipe/criar-convite.md)

Manda o e-mail de convite (como a tela) e responde com o `link` UMA vez. Vale 7 dias. Só atendente. Conta no limite de acessos do plano. Até 20 convites por dia por organização e 3 por e-mail (429 `limite_de_convites`). Repetir com a mesma `Idempotency-Key` devolve o convite sem `link` e sem mandar outro e-mail. Dispara `membro.convidado`.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `email` | string | sim | até 254 caracteres |
| `papel` | "atendente" | não | Sempre `atendente` pela API. |
| `papel_de_acesso_id` | uuid | não | Papel de acesso aplicado quando a pessoa aceitar. |
| `enviar_email` | boolean | não | false = não manda o e-mail; use o `link` da resposta. Padrão: manda. |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/equipe/convites" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{"email":"nova.atendente@exemplo.com.br","enviar_email":true}'
```

**Resposta `201` (exemplo)**

```json
{
  "dados": {
    "id": "fac480ff-6cc4-47be-9a87-6270d519a659",
    "email": "nova.atendente@exemplo.com.br",
    "papel": "dono",
    "papel_de_acesso_id": "646adc88-610e-4604-96fe-af5175dca375",
    "convidado_por": "Ana Lima",
    "expira_em": "2026-10-04T13:05:12.481Z",
    "criado_em": "2026-10-04T13:05:12.481Z",
    "link": "https://chat.forsi.com.br/convite/EXEMPLO"
  }
}
```

**Erros**: `401`, `403`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## DELETE /equipe/convites/{id} — Cancelar convite

- URL: `DELETE https://chat.forsi.com.br/api/v1/equipe/convites/{id}`
- Acesso: escopo `equipe:permissoes` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `ApagadoEquipe`
- Página: https://docs.forsi.com.br/api/equipe/cancelar-convite (Markdown: https://docs.forsi.com.br/api/equipe/cancelar-convite.md)

O link deixa de valer na hora.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl -X DELETE "https://chat.forsi.com.br/api/v1/equipe/convites/fac480ff-6cc4-47be-9a87-6270d519a659" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200`**: mesmo formato do exemplo de `ApagadoEquipe` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /equipe/convites/{id}/reenviar — Reenviar convite

- URL: `POST https://chat.forsi.com.br/api/v1/equipe/convites/{id}/reenviar`
- Acesso: escopo `equipe:permissoes` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `200`, `{"dados": ...}` com `ConviteComLink`
- Página: https://docs.forsi.com.br/api/equipe/reenviar-convite (Markdown: https://docs.forsi.com.br/api/equipe/reenviar-convite.md)

Gera um link novo (o antigo para de valer), renova o prazo de 7 dias e manda o e-mail de novo. Conta na mesma cota diária da criação.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON, opcional)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `enviar_email` | boolean | não | false = só gera o link novo. Padrão: manda o e-mail. |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/equipe/convites/fac480ff-6cc4-47be-9a87-6270d519a659/reenviar" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{"enviar_email":false}'
```

**Resposta `200`**: mesmo formato do exemplo de `ConviteComLink` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /equipe/equipes — Listar equipes (setores)

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/equipes`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Equipe` (paginada por cursor)
- Página: https://docs.forsi.com.br/api/equipe/listar-equipes (Markdown: https://docs.forsi.com.br/api/equipe/listar-equipes.md)

Cada equipe vem com os ids das pessoas dela.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `limite` | integer | não | Itens por página (1 a 100, padrão 50). |
| `cursor` | string | não | O valor de `proximo` da página anterior. até 80 caracteres |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/equipes" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "55174f08-dda3-49e6-bc5d-9309becdaf6d",
      "nome": "Recepção",
      "cor": "blue",
      "distribuicao": "manual",
      "ordem": 12,
      "membros": ["0e584d55-e895-4372-8945-cb64cafc6efd"],
      "criado_em": "2026-10-04T13:05:12.481Z"
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /equipe/equipes — Criar equipe

- URL: `POST https://chat.forsi.com.br/api/v1/equipe/equipes`
- Acesso: escopo `equipe:escrever` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `201`, `{"dados": ...}` com `Equipe`
- Página: https://docs.forsi.com.br/api/equipe/criar-equipe (Markdown: https://docs.forsi.com.br/api/equipe/criar-equipe.md)

Nome único na organização (409 `equipe_repetida`). Mande `Idempotency-Key` para poder repetir com segurança.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string | sim | até 40 caracteres |
| `cor` | "slate" \| "blue" \| "violet" \| "amber" \| "emerald" \| "green" \| "rose" \| "cyan" \| "orange" | não |  |
| `distribuicao` | "manual" \| "rodizio" \| "menos_ocupado" | não | Como as conversas novas da equipe são distribuídas: manual, rodízio ou para quem tem menos conversas abertas. |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/equipe/equipes" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{"nome":"Recepção","cor":"emerald","distribuicao":"rodizio"}'
```

**Resposta `201` (exemplo)**

```json
{
  "dados": {
    "id": "55174f08-dda3-49e6-bc5d-9309becdaf6d",
    "nome": "Recepção",
    "cor": "blue",
    "distribuicao": "manual",
    "ordem": 12,
    "membros": ["0e584d55-e895-4372-8945-cb64cafc6efd"],
    "criado_em": "2026-10-04T13:05:12.481Z"
  }
}
```

**Erros**: `401`, `403`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /equipe/equipes/{id} — Ver uma equipe

- URL: `GET https://chat.forsi.com.br/api/v1/equipe/equipes/{id}`
- Acesso: escopo `equipe:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Equipe`
- Página: https://docs.forsi.com.br/api/equipe/ver-equipe (Markdown: https://docs.forsi.com.br/api/equipe/ver-equipe.md)

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/equipe/equipes/55174f08-dda3-49e6-bc5d-9309becdaf6d" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200`**: mesmo formato do exemplo de `Equipe` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## PATCH /equipe/equipes/{id} — Atualizar equipe

- URL: `PATCH https://chat.forsi.com.br/api/v1/equipe/equipes/{id}`
- Acesso: escopo `equipe:escrever` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Equipe`
- Página: https://docs.forsi.com.br/api/equipe/atualizar-equipe (Markdown: https://docs.forsi.com.br/api/equipe/atualizar-equipe.md)

Nome, cor e distribuição. Só os campos enviados mudam.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string | não | até 40 caracteres |
| `cor` | "slate" \| "blue" \| "violet" \| "amber" \| "emerald" \| "green" \| "rose" \| "cyan" \| "orange" | não |  |
| `distribuicao` | "manual" \| "rodizio" \| "menos_ocupado" | não | Como as conversas novas da equipe são distribuídas: manual, rodízio ou para quem tem menos conversas abertas. |

**Exemplo (curl)**

```bash
curl -X PATCH "https://chat.forsi.com.br/api/v1/equipe/equipes/55174f08-dda3-49e6-bc5d-9309becdaf6d" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"distribuicao":"menos_ocupado"}'
```

**Resposta `200`**: mesmo formato do exemplo de `Equipe` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## DELETE /equipe/equipes/{id} — Apagar equipe

- URL: `DELETE https://chat.forsi.com.br/api/v1/equipe/equipes/{id}`
- Acesso: escopo `equipe:escrever` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `ApagadoEquipe`
- Página: https://docs.forsi.com.br/api/equipe/apagar-equipe (Markdown: https://docs.forsi.com.br/api/equipe/apagar-equipe.md)

As pessoas continuam na organização; as conversas da equipe ficam sem equipe.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl -X DELETE "https://chat.forsi.com.br/api/v1/equipe/equipes/55174f08-dda3-49e6-bc5d-9309becdaf6d" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200`**: mesmo formato do exemplo de `ApagadoEquipe` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## PATCH /equipe/equipes/{id}/membros — Pôr e tirar pessoas da equipe

- URL: `PATCH https://chat.forsi.com.br/api/v1/equipe/equipes/{id}/membros`
- Acesso: escopo `equipe:escrever` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Equipe`
- Página: https://docs.forsi.com.br/api/equipe/atualizar-membros-equipe (Markdown: https://docs.forsi.com.br/api/equipe/atualizar-membros-equipe.md)

Até 50 em cada lista. Qualquer pessoa da organização pode estar numa equipe: isso não muda o que ela pode ver.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `adicionar` | lista de uuid | não | Ids de pessoas (GET /equipe/membros) para pôr na equipe. até 50 itens |
| `remover` | lista de uuid | não | Ids de pessoas para tirar da equipe. até 50 itens |

**Exemplo (curl)**

```bash
curl -X PATCH "https://chat.forsi.com.br/api/v1/equipe/equipes/55174f08-dda3-49e6-bc5d-9309becdaf6d/membros" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "adicionar": ["0e584d55-e895-4372-8945-cb64cafc6efd"],
    "remover": ["8e5f909e-42a4-455e-801f-328bf2e7acf1"]
  }'
```

**Resposta `200`**: mesmo formato do exemplo de `Equipe` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /conversas/{id}/atribuir — Atribuir ou transferir conversa

- URL: `POST https://chat.forsi.com.br/api/v1/conversas/{id}/atribuir`
- Acesso: escopo `equipe:escrever` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `200`, `{"dados": ...}` com `Conversa`
- Página: https://docs.forsi.com.br/api/equipe/atribuir-conversa (Markdown: https://docs.forsi.com.br/api/equipe/atribuir-conversa.md)

Muda o responsável e/ou a equipe; null tira. Mesmo efeito da tela: registra no histórico da conversa ("Integração “nome da chave” passou para..."), avisa a pessoa, pausa o agente de IA da conversa e dispara `conversa.atribuida`.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `responsavel_id` | uuid ou null | não | Pessoa responsável (GET /equipe/membros). null tira o responsável. |
| `equipe_id` | uuid ou null | não | Equipe da conversa (GET /equipe/equipes). null tira a equipe. |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/conversas/495a7cae-128c-4b66-adbc-807b3959c129/atribuir" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{"responsavel_id":"0e584d55-e895-4372-8945-cb64cafc6efd"}'
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "id": "495a7cae-128c-4b66-adbc-807b3959c129",
    "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445",
    "grupo": false,
    "titulo": "Consulta de retorno",
    "estado": "aberta",
    "responsavel_id": "42b8028f-d7ce-4706-9567-44ac3bff4219",
    "equipe_id": "55174f08-dda3-49e6-bc5d-9309becdaf6d",
    "agente_id": "d1ab0f6b-41bf-4522-baaa-c3e281a79935",
    "etiquetas": ["ea287b0d-9968-4022-b9c7-b6dc239e6101"],
    "nao_lidas": 2,
    "janela_ate": "2026-10-04T13:05:12.481Z",
    "ultima_mensagem_em": "2026-10-04T13:05:12.481Z",
    "ultima_previa": "Oi, queria remarcar minha consulta",
    "ultima_direcao": "texto",
    "criado_em": "2026-10-04T13:05:12.481Z",
    "atualizado_em": "2026-10-04T13:05:12.481Z",
    "resolvida_em": "2026-10-04T13:05:12.481Z",
    "contato": {
      "id": "08054a7f-a752-481e-9915-cf4cf944df39",
      "nome": "Maria Souza",
      "telefone": "+5531988887777"
    },
    "origem_anuncio": {
      "anuncio_id": "texto",
      "titulo": "Consulta de retorno",
      "canal": "whatsapp",
      "clicado_em": "2026-10-04T13:05:12.481Z"
    }
  }
}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## Objetos das respostas

Campos de cada objeto devolvido em `dados`. Campos novos podem aparecer: ignore os que não conhecer.

### Membro

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string | não |  |
| `email` | string | não |  |
| `avatar_url` | string | não |  |
| `papel` | "dono" \| "gestor" \| "atendente" | não |  |
| `papel_de_acesso_id` | uuid | não |  |
| `permissoes` | object | não |  |
| `permissoes.caixas` | lista de uuid | não | WhatsApps visíveis. Vazio = todos. |
| `permissoes.modulos` | lista de string | não | Módulos liberados. Vazio = todos. |
| `permissoes.agenda` | "todas" \| "propria" | não |  |
| `equipes` | lista de uuid | não |  |
| `disponivel` | boolean | não |  |
| `disponivel_agora` | boolean | não |  |
| `ausente_ate` | data e hora ISO 8601 | não |  |
| `horario` | objeto livre | não | {"dias": [1,2,3,4,5], "inicio": "08:00", "fim": "18:00"} (0 = domingo). |
| `ultimo_acesso` | data e hora ISO 8601 | não |  |
| `entrou_em` | data e hora ISO 8601 | não |  |

### ApagadoEquipe

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `apagado` | boolean | não |  |

### Presenca

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string | não |  |
| `papel` | "dono" \| "gestor" \| "atendente" | não |  |
| `disponivel` | boolean | não |  |
| `disponivel_agora` | boolean | não |  |
| `ausente_ate` | data e hora ISO 8601 | não |  |
| `horario` | objeto livre | não |  |
| `ultimo_acesso` | data e hora ISO 8601 | não |  |

### Convite

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `email` | string | não |  |
| `papel` | "dono" \| "gestor" \| "atendente" | não |  |
| `papel_de_acesso_id` | uuid | não |  |
| `convidado_por` | string | não | Nome de quem convidou pela tela. Convites da API não têm. |
| `expira_em` | data e hora ISO 8601 | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |

### Equipe

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string | não |  |
| `cor` | string | não |  |
| `distribuicao` | "manual" \| "rodizio" \| "menos_ocupado" | não |  |
| `ordem` | integer | não |  |
| `membros` | lista de uuid | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |

### Conversa

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `caixa_id` | uuid | não |  |
| `grupo` | boolean | não |  |
| `titulo` | string ou null | não |  |
| `estado` | "aberta" \| "pendente" \| "adiada" \| "resolvida" | não |  |
| `responsavel_id` | uuid ou null | não |  |
| `equipe_id` | uuid ou null | não |  |
| `agente_id` | uuid ou null | não |  |
| `etiquetas` | lista de uuid | não |  |
| `nao_lidas` | integer | não |  |
| `janela_ate` | data e hora ISO 8601 ou null | não | Até quando a janela de 24 h da API oficial está aberta. |
| `ultima_mensagem_em` | data e hora ISO 8601 ou null | não |  |
| `ultima_previa` | string ou null | não |  |
| `ultima_direcao` | string ou null | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |
| `atualizado_em` | data e hora ISO 8601 | não |  |
| `resolvida_em` | data e hora ISO 8601 ou null | não |  |
| `contato` | object ou null | não |  |
| `contato.id` | uuid | não |  |
| `contato.nome` | string ou null | não |  |
| `contato.telefone` | string ou null | não |  |
| `origem_anuncio` | object ou null | não | Primeiro anúncio que levou a pessoa ao WhatsApp, Instagram ou Messenger. |
| `origem_anuncio.anuncio_id` | string ou null | não |  |
| `origem_anuncio.titulo` | string ou null | não |  |
| `origem_anuncio.canal` | string | não |  |
| `origem_anuncio.clicado_em` | data e hora ISO 8601 | não |  |

---

Página: https://docs.forsi.com.br/api/equipe · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt