# Departamentos (/docs/crm/departamentos)





Um **departamento** agrupa atendentes por área (Suporte, Financeiro, Comercial…). Cada atendente fica vinculado a um departamento; cada conversa "está" em um departamento e pode ser **transferida** entre eles. O caso típico: o contato cai no Suporte, o atendente percebe que é uma questão financeira e **transfere a conversa para o Financeiro** — ela sai da visão do Suporte e entra na fila do Financeiro.

<Callout type="info">
  Departamentos são **escopados ao Projeto** da sua API key e seguem a mesma autenticação por
  `Authorization: Bearer` do resto da API. O CRUD e a transferência também estão disponíveis para
  integradores via API key.
</Callout>

## O modelo [#o-modelo]

* **Atendente → 1 departamento.** Cada membro da equipe pode estar vinculado a um departamento (ou a nenhum). Definido na página **Equipe** do painel (ou via API do painel).
* **Conversa → 1 departamento (ou nenhum).** Uma conversa "está" em um departamento por vez. **Sem departamento = fila geral**, visível a todos os atendentes.
* **Como a conversa cai num departamento:** (1) pelo **número** — cada instância pode ter um departamento padrão (no cadastro da instância) que o ticket novo herda; (2) pelo **chatbot** — o nó "Transferir" do [construtor de fluxo](/docs/crm/fluxos) pode mandar pra um departamento; (3) por **transferência manual** (botão no topo do chat) ou pela API. Sem nenhum desses, a conversa fica na **fila geral** (sem departamento, visível a todos).
* **Roteamento automático respeita o departamento:** quando a [Equipe](/docs/crm/equipe) usa atribuição automática (menos ocupado / rodízio), o atendente escolhido sai **do departamento da conversa**; na fila geral, de qualquer atendente online.

### Visibilidade por departamento [#visibilidade-por-departamento]

A regra de quem enxerga o quê depende da permissão `ver_todas_conversas`:

| Quem                                               | Enxerga                                                                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Dono/Admin, ou atendente com `ver_todas_conversas` | **Todas** as conversas do Projeto.                                                                                              |
| Atendente **sem** `ver_todas_conversas`            | As conversas **atribuídas a ele** + as **sem dono** do **seu departamento** + as **sem dono da fila geral** (sem departamento). |

Ou seja: ao transferir uma conversa do Suporte para o Financeiro, ela **deixa de aparecer** para os atendentes do Suporte (que não têm "ver todas") e passa a aparecer para os do Financeiro. Conversas **sem departamento** ficam visíveis para todos — é a fila de triagem.

## Transferir uma conversa [#transferir-uma-conversa]

Transferir é o caminho principal e foi feito para ser rápido:

* **No painel:*&#x2A; no topo do chat, ao lado das etiquetas, há um botão com o departamento atual. Clique e escolha o destino (ou &#x2A;*"Fila geral"** para tirar o departamento).
* **Na API:** `POST /v1/inbox/conversations/{id}/department` com `{ "departmentId": "..." }`.

<Callout type="warn">
  A transferência **solta o atendente atual**: a conversa volta para a **fila do departamento de
  destino** (sem dono), para que alguém daquele departamento assuma. Envie `departmentId: null` para
  mandar para a fila geral.
</Callout>

## No painel [#no-painel]

| Ação                                  | Onde                                                                    |
| ------------------------------------- | ----------------------------------------------------------------------- |
| Criar/excluir departamento            | Inbox → engrenagem **Configurar atendimento** → aba **Deptos**          |
| Vincular atendente a um departamento  | **Equipe** → seletor de departamento no atendente                       |
| Departamento padrão do número         | **Instâncias** → seletor "Departamento padrão" na instância             |
| Transferir a conversa                 | **Inbox** → botão de departamento no topo do chat                       |
| Filtrar o inbox por departamento      | **Inbox** → chips de departamento acima da lista                        |
| Chatbot transfere pra um departamento | **Fluxos** → nó **Transferir** → campo "Transferir para o departamento" |

Gerenciar o catálogo de departamentos e vincular atendentes exige um usuário **dono ou administrador**. **Transferir** uma conversa é liberado a qualquer atendente com acesso à conversa.

## Na API [#na-api]

| Operação               | Método e rota                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| Listar departamentos   | [`GET /v1/inbox/departments`](/docs/api/departamentos/listDepartments)                                   |
| Criar departamento     | [`POST /v1/inbox/departments`](/docs/api/departamentos/createDepartment)                                 |
| Atualizar departamento | [`PATCH /v1/inbox/departments/{id}`](/docs/api/departamentos/updateDepartment)                           |
| Remover departamento   | [`DELETE /v1/inbox/departments/{id}`](/docs/api/departamentos/deleteDepartment)                          |
| Transferir a conversa  | [`POST /v1/inbox/conversations/{id}/department`](/docs/api/departamentos/transferConversationDepartment) |

A conversa no [Inbox](/docs/api/inbox/listInboxConversations) traz `departmentId` e `departmentName`; a listagem aceita o filtro `?departmentId=` para ver só um departamento. O **vínculo do atendente** a um departamento é feito pelo painel (não exposto na API de integração).

### Exemplos [#exemplos]

Criar um departamento:

```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/departments \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Financeiro", "description": "Cobrança, boletos e notas fiscais" }'
```

Transferir uma conversa para esse departamento:

```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "departmentId": "dep_financeiro" }'
```

Devolver a conversa para a fila geral (sem departamento):

```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
  -H "Authorization: Bearer pzk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "departmentId": null }'
```

## Pontos importantes [#pontos-importantes]

* **Soft-delete:** remover um departamento o desativa. As conversas que estavam nele **voltam para a fila geral** e os atendentes vinculados perdem o vínculo — nada de histórico quebra.
* **Nome único** por Projeto (case-insensitive); nome repetido retorna `409`.
* **Departamentos e [etiquetas](/docs/crm/etiquetas-encerramento) são ortogonais:** o departamento diz *qual fila* atende a conversa; a etiqueta é uma *marcação* livre. Uma conversa pode ter os dois.

Veja também &#x2A;*[Equipe e permissões](/docs/crm/equipe)** (atendentes, presença e a permissão `ver_todas_conversas` que rege a visibilidade acima).