> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hustapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral

> Estrutura do CRM, status, prioridades, permissões e erros

O CRM organiza leads e tarefas em funis no formato Kanban.

```text theme={null}
Pipeline (funil)
 └── Etapa (coluna do Kanban)
      └── Card (lead ou tarefa)
           ├── Itens de checklist
           ├── Comentários
           ├── Atendimentos vinculados
           └── Propostas vinculadas
```

* Pipelines do tipo `lead` geram cards do tipo `lead` (funil de vendas). Os demais tipos geram cards do tipo `task`.
* Cada etapa tem um **status**. Quando um card entra na etapa, assume o status dela.
* Uma pipeline pode ser restrita a um departamento: só usuários desse departamento a enxergam.

## URL base e autenticação

```text theme={null}
https://api.hustapp.com
```

O CRM usa o mesmo token das demais APIs, no cabeçalho `Authorization: Bearer SEU_TOKEN`. Veja [Autenticação](/autenticacao.md).

Os dados são sempre isolados pela empresa do usuário dono do token.

## Permissões

| Perfil | Pode |
| - | - |
| Gestor | Editar qualquer card, remover responsável, editar etapas e excluir qualquer comentário. |
| Usuário comum | Editar cards sem responsável ou dos quais é responsável, e excluir só os próprios comentários. |

## Status

| Valor | Significado |
| - | - |
| `pending` | Pendente |
| `progress` | Em andamento |
| `blocked` | Aguardando |
| `finished` | Finalizada |
| `finished_win` | Venda realizada |
| `finished_lost` | Fechamento negativo |

## Prioridade

Em leads, a prioridade representa a temperatura.

| Valor | Tarefa | Lead |
| - | - | - |
| `urgent` | Urgente | Muito quente |
| `high` | Alta | Quente |
| `medium` | Média (padrão) | Morno |
| `low` | Baixa | Frio |

## Convenções

* Corpo e resposta em JSON.
* Datas em ISO 8601: `2026-10-22T13:00:00.000Z`.
* Valores monetários em número decimal: `1500.5`.
* Relacionamentos são referenciados por objeto com `id`: `{ "pipeline": { "id": 4 } }`.

## Erros

A maioria das rotas responde erros com status `500`:

```json theme={null}
{ "message": "Error: TASK_NOT_FOUND" }
```

| Código | Significado |
| - | - |
| `TASK_NOT_FOUND` | Card inexistente ou de outra empresa. |
| `PIPELINE_NOT_FOUND` | Pipeline inexistente ou de outra empresa. |
| `PIPELINEDEST_NOT_FOUND` | Pipeline de destino da transferência não encontrada. |
| `STAGEDEST_NOT_FOUND` | Pipeline de destino não tem etapas. |
| `STAGE_NOT_FOUND` | Etapa inexistente ou de outra empresa. |
| `TASK_PARENT_NOT_FOUND` | Card pai do item de checklist não encontrado. |
| `CALLED_NOT_FOUND` | Atendimento inexistente ou de outra empresa. |
| `WITHOUT_NAME` | Nome da pipeline não informado. |
| `MISSING_REQUIRED_FIELDS` | Campos obrigatórios ausentes. |
| `INVALID_STATUS` | Status inválido. |
| `INVALID_PRIORITY` | Prioridade inválida. |
| `INVALID_STAGE_ID` | ID de etapa não numérico. |
| `FILE_SIZE_EXCEEDS_LIMIT` | Anexo maior que 5 MB. |

Rotas que respondem `400`, `403` ou `404` com mensagens próprias têm isso indicado na página do endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.