# API pública do PipeFácil

API REST do PipeFácil, autenticada por **chave de API** (`Authorization: Bearer pf_live_…`). A chave representa o membro que a criou: suas permissões, papel e visibilidade de registros se aplicam às requisições. O `workspaceId` vem sempre da chave, nunca da requisição. O limite é de 600 requisições por minuto, por workspace e por IP. Ao excedê-lo, a API responde `429`, com o cabeçalho `X-Rate-Limit-Retry-After-Seconds`.
Crie e gerencie as chaves no aplicativo. Esta referência documenta as rotas sob `/api/v1` autenticadas por chave; a gestão de chaves, protegida por JWT, fica fora deste contrato.

## Autenticação

Use `Authorization: Bearer pf_live_…` em todas as requisições.

## Recursos

### Negócios

Crie, consulte e atualize negócios, etiquetas, notas, tarefas e atividades.

- [Listar negócios](/api/resources/deals/methods/list-deals/): `GET /api/v1/deals`
- [Criar negócio](/api/resources/deals/methods/create-deal/): `POST /api/v1/deals`
- [Listar valores de campos personalizados dos negócios](/api/resources/deals/methods/list-deal-custom-field-values/): `GET /api/v1/deals/custom-field-values`
- [Consultar negócio](/api/resources/deals/methods/get-deal/): `GET /api/v1/deals/{seq}`
- [Atualizar negócio](/api/resources/deals/methods/update-deal/): `PATCH /api/v1/deals/{seq}`
- [Adicionar etiqueta ao negócio](/api/resources/deals/methods/add-deal-tag/): `POST /api/v1/deals/{seq}/tags`
- [Remover etiqueta do negócio](/api/resources/deals/methods/remove-deal-tag/): `DELETE /api/v1/deals/{seq}/tags/{tagId}`
- [Criar nota do negócio](/api/resources/deals/methods/create-deal-note/): `POST /api/v1/deals/{seq}/notes`
- [Enviar anexo de nota do negócio](/api/resources/deals/methods/upload-deal-note-attachment/): `POST /api/v1/deals/{seq}/notes/attachments`
- [Criar tarefa do negócio](/api/resources/deals/methods/create-deal-task/): `POST /api/v1/deals/{seq}/tasks`
- [Listar atividades do negócio](/api/resources/deals/methods/list-deal-activities/): `GET /api/v1/deals/{seq}/activities`
- [Listar atividades do workspace](/api/resources/deals/methods/list-workspace-activities/): `GET /api/v1/deals/activities`
- [Listar mensagens do negócio](/api/resources/deals/methods/list-deal-messages/): `GET /api/v1/deals/{seq}/messages`
- [Obter arquivo de um campo do negócio](/api/resources/deals/methods/get-deal-property-file/): `GET /api/v1/deals/{seq}/properties/{slug}/file`
- [Enviar e vincular arquivo ao negócio](/api/resources/deals/methods/upload-deal-property-file/): `POST /api/v1/deals/{seq}/properties/{slug}/file`

### Contatos

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar contatos](/api/resources/reference/methods/list-contacts/): `GET /api/v1/contacts`
- [Criar contato](/api/resources/reference/methods/create-contact/): `POST /api/v1/contacts`
- [Consultar contato](/api/resources/reference/methods/get-contact/): `GET /api/v1/contacts/{id}`
- [Atualizar contato](/api/resources/reference/methods/update-contact/): `PATCH /api/v1/contacts/{id}`
- [Excluir contato](/api/resources/reference/methods/delete-contact/): `DELETE /api/v1/contacts/{id}`
- [Enviar foto do contato](/api/resources/reference/methods/upload-contact-avatar/): `POST /api/v1/contacts/{id}/avatar`
- [Remover foto do contato](/api/resources/reference/methods/remove-contact-avatar/): `DELETE /api/v1/contacts/{id}/avatar`

### Empresas

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar empresas](/api/resources/reference/methods/list-companies/): `GET /api/v1/companies`
- [Criar empresa](/api/resources/reference/methods/create-company/): `POST /api/v1/companies`
- [Consultar empresa](/api/resources/reference/methods/get-company/): `GET /api/v1/companies/{seq}`
- [Atualizar empresa](/api/resources/reference/methods/update-company/): `PATCH /api/v1/companies/{seq}`
- [Excluir empresa](/api/resources/reference/methods/delete-company/): `DELETE /api/v1/companies/{seq}`

### Funis

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar funis](/api/resources/reference/methods/list-pipelines/): `GET /api/v1/pipelines`
- [Criar funil](/api/resources/reference/methods/create-pipeline/): `POST /api/v1/pipelines`
- [Listar funis arquivados](/api/resources/reference/methods/list-archived-pipelines/): `GET /api/v1/pipelines/archived`
- [Substituir motivos de perda](/api/resources/reference/methods/replace-loss-reasons/): `PUT /api/v1/pipelines/loss-reasons`
- [Consultar funil](/api/resources/reference/methods/get-pipeline/): `GET /api/v1/pipelines/{seq}`
- [Atualizar funil](/api/resources/reference/methods/update-pipeline/): `PATCH /api/v1/pipelines/{seq}`
- [Arquivar funil](/api/resources/reference/methods/archive-pipeline/): `DELETE /api/v1/pipelines/{seq}`
- [Restaurar funil](/api/resources/reference/methods/unarchive-pipeline/): `POST /api/v1/pipelines/{seq}/unarchive`
- [Listar regras de acesso ao funil](/api/resources/reference/methods/list-pipeline-access/): `GET /api/v1/pipelines/{seq}/access`
- [Substituir regras de acesso ao funil](/api/resources/reference/methods/replace-pipeline-access/): `PUT /api/v1/pipelines/{seq}/access`
- [Criar etapa do funil](/api/resources/reference/methods/create-pipeline-stage/): `POST /api/v1/pipelines/{seq}/stages`
- [Reordenar etapas do funil](/api/resources/reference/methods/reorder-pipeline-stages/): `PATCH /api/v1/pipelines/{seq}/stages/reorder`
- [Atualizar etapa do funil](/api/resources/reference/methods/update-pipeline-stage/): `PATCH /api/v1/pipelines/{seq}/stages/{stageId}`
- [Excluir etapa do funil](/api/resources/reference/methods/delete-pipeline-stage/): `DELETE /api/v1/pipelines/{seq}/stages/{stageId}`
- [Listar configuração de campos do funil](/api/resources/reference/methods/list-pipeline-fields/): `GET /api/v1/pipelines/{seq}/fields`
- [Consultar configuração de campo do funil](/api/resources/reference/methods/get-pipeline-field/): `GET /api/v1/pipelines/{seq}/fields/{field}`
- [Atualizar configuração de campo do funil](/api/resources/reference/methods/update-pipeline-field/): `PATCH /api/v1/pipelines/{seq}/fields/{field}`

### Etiquetas

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar etiquetas](/api/resources/reference/methods/list-tags/): `GET /api/v1/tags`
- [Criar etiqueta](/api/resources/reference/methods/create-tag/): `POST /api/v1/tags`
- [Consultar etiqueta](/api/resources/reference/methods/get-tag/): `GET /api/v1/tags/{id}`
- [Atualizar etiqueta](/api/resources/reference/methods/update-tag/): `PATCH /api/v1/tags/{id}`
- [Excluir etiqueta](/api/resources/reference/methods/delete-tag/): `DELETE /api/v1/tags/{id}`

### Campos personalizados

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar campos personalizados](/api/resources/reference/methods/list-custom-fields/): `GET /api/v1/custom-fields`
- [Criar campo personalizado](/api/resources/reference/methods/create-custom-field/): `POST /api/v1/custom-fields`
- [Enviar arquivo de campo personalizado](/api/resources/reference/methods/upload-custom-field-file/): `POST /api/v1/custom-fields/upload`
- [Obter URL de arquivo de campo personalizado](/api/resources/reference/methods/resolve-custom-field-file-url/): `GET /api/v1/custom-fields/file`
- [Consultar campo personalizado](/api/resources/reference/methods/get-custom-field/): `GET /api/v1/custom-fields/{id}`
- [Atualizar campo personalizado](/api/resources/reference/methods/update-custom-field/): `PATCH /api/v1/custom-fields/{id}`
- [Excluir campo personalizado](/api/resources/reference/methods/delete-custom-field/): `DELETE /api/v1/custom-fields/{id}`

### Membros

Contatos, empresas, funis, etapas, acesso, configuração de campos, motivos de perda, etiquetas e campos personalizados podem ser gerenciados pela API. Usuários são somente leitura; gerencie membros pelo aplicativo.
Qualquer chave válida pode ler funis. Alterações de funis exigem `settings.pipelines`. A leitura de contatos exige `contacts.view`; a de empresas, `companies.view`. Etiquetas e campos personalizados continuam disponíveis para leitura com qualquer chave válida.
As permissões pertencem ao membro que criou a chave. Os papéis privilegiados possuem todas elas; os demais membros seguem as permissões do papel e suas exceções individuais. Empresas usam `companies.view`, `companies.edit` e `companies.delete`, independentemente das permissões de negócios.

- [Listar usuários](/api/resources/reference/methods/list-users/): `GET /api/v1/users`
- [Consultar membro](/api/resources/reference/methods/get-user/): `GET /api/v1/users/{id}`

### Calendário

Calendário unificado do workspace: reuniões, tarefas, etapas de cadência e eventos do Google Calendar do membro. Exige o recurso `CALENDAR` no workspace.

- [Listar intervalo do calendário](/api/resources/calendar/methods/list-calendar-window/): `GET /api/v1/calendar/events`
- [Criar reunião](/api/resources/calendar/methods/create-calendar-event/): `POST /api/v1/calendar/events`
- [Consultar reunião](/api/resources/calendar/methods/get-calendar-event/): `GET /api/v1/calendar/events/{id}`
- [Atualizar reunião](/api/resources/calendar/methods/update-calendar-event/): `PATCH /api/v1/calendar/events/{id}`
- [Excluir reunião](/api/resources/calendar/methods/delete-calendar-event/): `DELETE /api/v1/calendar/events/{id}`

### Conversas

Envie mensagens e consulte conversas e seus históricos. Exige `ADVANCED_API`, além de `API_ACCESS`, necessário para qualquer chave. Sem o recurso, as rotas deste grupo respondem `403 FEATURE_DISABLED`.

- [Enviar mensagem](/api/resources/conversations/methods/send-message/): `POST /api/v1/conversations/messages`
- [Listar conversas](/api/resources/conversations/methods/list-conversations/): `GET /api/v1/conversations`
- [Listar mensagens da conversa](/api/resources/conversations/methods/list-conversation-messages/): `GET /api/v1/conversations/{conversationKey}/messages`

### Cadências

Consulte cadências, seus negócios matriculados e o ciclo de matrícula de cada negócio. Exige **`CADENCE` e `ADVANCED_API`** no workspace. O acesso externo é contratado separadamente e vem desligado por padrão. A ausência de qualquer recurso resulta em `403 FEATURE_DISABLED`.
A rota `tasks/{taskId}/execute` envia de fato uma mensagem por WhatsApp, um e-mail ou uma chamada externa e pode gerar cobrança no workspace. Envie a `idempotencyKey` obrigatória: repetir a mesma chave retorna `duplicated: true`, sem novo envio. As outras rotas alteram somente o estado da cadência.

- [Listar cadências](/api/resources/cadences/methods/list-cadences/): `GET /api/v1/cadences`
- [Listar matrículas da cadência](/api/resources/cadences/methods/list-cadence-enrollments/): `GET /api/v1/cadences/{cadenceId}/enrollments`
- [Consultar cadência do negócio](/api/resources/cadences/methods/get-deal-cadence/): `GET /api/v1/deals/{seq}/cadence`
- [Matricular negócio em cadência](/api/resources/cadences/methods/enroll-deal-cadence/): `POST /api/v1/deals/{seq}/cadence/enroll`
- [Remover negócio da cadência](/api/resources/cadences/methods/unenroll-deal-cadence/): `POST /api/v1/deals/{seq}/cadence/unenroll`
- [Pausar cadência do negócio](/api/resources/cadences/methods/pause-deal-cadence/): `POST /api/v1/deals/{seq}/cadence/pause`
- [Retomar cadência do negócio](/api/resources/cadences/methods/resume-deal-cadence/): `POST /api/v1/deals/{seq}/cadence/resume`
- [Iniciar cadência do negócio](/api/resources/cadences/methods/start-deal-cadence/): `POST /api/v1/deals/{seq}/cadence/start`
- [Executar tarefa de cadência](/api/resources/cadences/methods/execute-cadence-task/): `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/execute`
- [Pular tarefa de cadência](/api/resources/cadences/methods/skip-cadence-task/): `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/skip`
- [Concluir tarefa de cadência manualmente](/api/resources/cadences/methods/complete-cadence-task-manually/): `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/complete-manual`

### Automações

Gerencie fluxos de automação e consulte o histórico de execução. Exige `ADVANCED_API` e `API_ACCESS`; sem o recurso, as rotas respondem `403 FEATURE_DISABLED`. O acesso por API é a operação externa das automações disponíveis no aplicativo.
A leitura exige `automations.view`; alterações exigem `automations.edit`. Esta última permissão não pertence ao conjunto padrão de nenhum papel comum: conceda uma exceção explícita ao membro que precisa editar fluxos. Um fluxo ativo pode enviar mensagens aos clientes automaticamente.
Os papéis privilegiados `owner`, `admin`, `partner` e `support` possuem todas as permissões na API. Assim, `partner` e `support` podem alterar automações por esta API, embora as rotas de escrita do aplicativo sejam restritas a `owner` e `admin`.
Nenhuma rota deste grupo inicia a execução de uma automação. `POST /{id}/test` não envia mensagens nem entrega o webhook: retorna o corpo assinado que a primeira ação de webhook enviaria. Exige `automations.edit`, pois usa o segredo real para calcular a assinatura.
As respostas de leitura removem segredos de webhook, inclusive nos logs e nas cópias da definição de uma execução. Quando uma criação ou atualização gera um segredo, a resposta o mostra uma única vez.
Limitação: não há rota pública para listar `outboundChannelId` nem os identificadores `channelId`, `mediaAssetId` e `scriptId` das ações `send_whatsapp`. Obtenha esses identificadores fora desta referência. Funis, etapas, etiquetas, campos e usuários podem ser consultados em `/api/v1/pipelines`, `/tags`, `/custom-fields` e `/users`.

- [Listar automações](/api/resources/automations/methods/list-automations/): `GET /api/v1/automations`
- [Criar automação](/api/resources/automations/methods/create-automation/): `POST /api/v1/automations`
- [Listar catálogo de gatilhos](/api/resources/automations/methods/list-automation-triggers/): `GET /api/v1/automations/triggers`
- [Consultar automação](/api/resources/automations/methods/get-automation/): `GET /api/v1/automations/{id}`
- [Substituir automação](/api/resources/automations/methods/replace-automation/): `PUT /api/v1/automations/{id}`
- [Excluir automação](/api/resources/automations/methods/delete-automation/): `DELETE /api/v1/automations/{id}`
- [Ativar ou desativar automação](/api/resources/automations/methods/set-automation-enabled/): `PATCH /api/v1/automations/{id}/enabled`
- [Pré-visualizar entrega de webhook](/api/resources/automations/methods/test-automation/): `POST /api/v1/automations/{id}/test`
- [Listar logs da automação](/api/resources/automations/methods/list-automation-logs/): `GET /api/v1/automations/{id}/logs`
- [Listar entregas de webhook](/api/resources/automations/methods/list-automation-deliveries/): `GET /api/v1/automations/{id}/deliveries`
- [Listar execuções da automação](/api/resources/automations/methods/list-automation-runs/): `GET /api/v1/automations/{id}/runs`
- [Consultar execução da automação](/api/resources/automations/methods/get-automation-run/): `GET /api/v1/automations/{id}/runs/{runId}`