# Configurar funis e campos pela API

## Criar e identificar o funil

Use `GET /api/v1/pipelines` para consultar funis e `POST /api/v1/pipelines` para criar. As operações individuais usam a sequência em `/api/v1/pipelines/{seq}`.

```json
{
	"name": "Novas vendas",
	"description": "Qualificar e fechar novas oportunidades",
	"stages": [
		{ "name": "Qualificação", "color": "#2563eb" },
		{ "name": "Proposta", "color": "#7c3aed" }
	]
}
```

Etapas ativas são criadas na ordem enviada. Se a lista vier vazia ou omitida, o servidor cria o funil padrão. Ganho e perda são acrescentados pelo sistema.

## Alterar etapas e acesso

| Ação                           | Operação                                                     |
| ------------------------------ | ------------------------------------------------------------ |
| Editar funil                   | `PATCH /api/v1/pipelines/{seq}`                              |
| Criar etapa                    | `POST /api/v1/pipelines/{seq}/stages`                        |
| Editar ou remover etapa        | `PATCH` ou `DELETE /api/v1/pipelines/{seq}/stages/{stageId}` |
| Reordenar etapas               | `PATCH /api/v1/pipelines/{seq}/stages/reorder`               |
| Consultar ou substituir acesso | `GET` ou `PUT /api/v1/pipelines/{seq}/access`                |
| Consultar arquivados           | `GET /api/v1/pipelines/archived`                             |
| Desarquivar                    | `POST /api/v1/pipelines/{seq}/unarchive`                     |

Revise os conflitos informados pelo servidor antes de remover uma etapa ou um funil. O catálogo de motivos de perda é atualizado por `PUT /api/v1/pipelines/loss-reasons` e pertence ao workspace.

## Comportamentos

Configure `behaviors` com `recurring_clients`, `multi_channel_pipeline` e `attendance_queue` quando o workspace tiver o recurso disponível. O PATCH substitui o conjunto: envie todos os comportamentos que devem permanecer ligados.

A fila de atendimento exige `attendanceQueueStageId`, uma etapa ativa desse funil. Configure depois da criação, quando você já tiver o ID da etapa. Para desligar a fila, remova `attendance_queue` de `behaviors`; enviar apenas `attendanceQueueStageId: null` não a desliga.

`pipelineType` é uma entrada legada ignorada. Use `behaviors`. Leia [Comportamentos do funil](/configuracoes/comportamentos-do-funil/) para entender os efeitos sobre criação, retorno e acesso.

## Campos do funil e das etapas

Use `GET /api/v1/pipelines/{seq}/fields` para consultar a configuração. Para um campo, use `GET` ou `PATCH /api/v1/pipelines/{seq}/fields/{field}`. `field` aceita o identificador do campo personalizado ou a chave do campo padrão.

O contrato diferencia a configuração base do funil das alterações por etapa. Consulte as propriedades do corpo na [referência da API](/api/) e as [regras de visibilidade, sugestão e obrigatoriedade](/configuracoes/regras-de-campos/). Alterar uma definição global não equivale a alterar sua regra em um funil.