--- title: "Criar ou atualizar um funil de projeto" method: POST path: "/api/management/project-funnel" tags: ["project-funnels", "Funis"] --- # Criar ou atualizar um funil de projeto `POST /api/management/project-funnel` Salva o funil inteiro de uma vez — é o payload da tela de edição. Sem `id` cria um funil novo; com `id` substitui a configuração do funil existente. **O payload é a verdade final**: etapas, checklists, restrições, etiquetas e status que não vierem na requisição são removidos do funil. Itens que estouram o limite do plano não são criados e voltam listados em `objects_above_limit`, sem derrubar o resto do salvamento. Ver [Criar e configurar um funil](https://docs.olie.ai/guides/funnels/creating-funnels), [Etapas do funil](https://docs.olie.ai/guides/funnels/steps) e [Restrições e bloqueios](https://docs.olie.ai/guides/funnels/restrictions). ## Request body - object - `id` integer, nullable — ID do funil a atualizar. Sem ele, um novo funil é criado. - `name` string, required — Nome do funil. Obrigatório e sem HTML. - `prefix` string, nullable — Prefixo do código dos projetos. Gerado a partir do nome quando não informado. - `condition` 'active' | 'inactive' — Situação do funil. Padrão `active`. - `allow_multi_step` boolean — Permite o projeto em várias etapas ao mesmo tempo. - `allow_execution` boolean — Permite cronometrar execução nos projetos do funil. - `show_cost_info` boolean — Exibe informações de custo. Padrão true. - `project_term` object, nullable — Vocabulário do funil para o termo 'projeto', no singular e no plural. - `form` object, nullable — Formulário de vínculo do funil. - `id` integer, nullable — ID do formulário. Nulo desvincula. - `steps` object[], required — Etapas do funil, na ordem desejada. Obrigatório. Etapas ausentes são removidas. - `id` integer, nullable — ID da etapa a manter. Sem ele, a etapa é criada. - `name` string, required — Nome da etapa. Obrigatório e único dentro do funil. - `help_text` string, nullable — Texto de orientação exibido na etapa. - `sensation_amount` integer — Percentual de progresso que a etapa representa, de 0 a 100. - `allow_execution` boolean — Permite cronometrar execução na etapa. - `show_customer_form` boolean — Exibe o formulário do cliente ao mover o projeto para a etapa. - `show_contact_form` boolean — Exibe o formulário do contato ao mover o projeto para a etapa. - `hide_customer_form_when_linked` boolean — Não exibe o formulário do cliente quando já houver cliente vinculado. - `hide_contact_form_when_linked` boolean — Não exibe o formulário do contato quando já houver contato vinculado. - `step_forward` object, nullable — Etapa de avanço padrão. - `name` string — Nome da etapa de avanço. - `step_backward` object, nullable — Etapa de retrocesso padrão. - `name` string — Nome da etapa de retrocesso. - `form` object, nullable — Formulário da etapa. - `id` integer, nullable — ID do formulário. Nulo desvincula. - `sort_config` object, nullable — Ordenação automática dos cartões da etapa. - `field` string — Campo de ordenação. Obrigatório quando `sort_config` é enviado. - `direction` 'asc' | 'desc' — Sentido da ordenação. Obrigatório quando `sort_config` é enviado. - `arguments` string[] — Argumentos adicionais do campo. - `checklists` object[] — Itens de checklist da etapa. Itens ausentes são removidos. - `id` integer, nullable — ID do item a manter. - `name` string, required — Texto do item. Obrigatório. - `info` string, nullable — Orientação adicional. - `required` boolean — Impede a saída da etapa enquanto não for marcado. - `order` integer — Posição do item na lista. - `restrictions` object[] — Restrições da etapa. Restrições ausentes são removidas. - `name` string, nullable — Nome da restrição. - `direction` 'incoming' | 'outgoing', required — Se vale na entrada ou na saída da etapa. Obrigatório. - `restriction_type` 'step' | 'status' | 'tag' | 'filter', required — O que a restrição avalia. Obrigatório. - `target_step_id` integer, nullable — Etapa avaliada. Obrigatório quando o tipo é `step`. - `target_tag_id` integer, nullable — Etiqueta avaliada. Obrigatório quando o tipo é `tag`. - `target_status_id` integer, nullable — Status avaliado. Obrigatório quando o tipo é `status`. - `hierarchy_scope` 'current' | 'descendants' | 'ancestors' | 'null', nullable — Sobre quem a regra é avaliada: o próprio projeto, os filhos ou os pais. - `hierarchy_depth` integer, nullable — Quantos níveis da hierarquia considerar, de 1 a 3. - `attachments` object[] — Anexos vinculados à etapa. - `id` integer — ID do anexo de etapa a vincular. - `tags` object[] — Etiquetas do funil. Nome e cor não podem se repetir no mesmo funil. - `id` integer, nullable — ID da etiqueta a manter. - `name` string — Nome da etiqueta. - `color` string, nullable — Cor em hexadecimal. - `funnel_step_blockings` object[] — Etapas bloqueadas enquanto o projeto tiver esta marcação. - `funnel_step_id` integer, required — Etapa que fica bloqueada. Obrigatório. - `automation_bypass` boolean, nullable — Quando true, automações podem mover o projeto mesmo com o bloqueio ativo. - `funnel_status` object[] — Status do funil. - `id` integer, nullable — ID do status a manter. - `name` string — Nome do status. - `color` string, nullable — Cor em hexadecimal. - `is_conclusive` boolean — Marca o status como desfecho do projeto no funil. - `funnel_step_blockings` object[] — Etapas bloqueadas enquanto o projeto tiver esta marcação. - `funnel_step_id` integer, required — Etapa que fica bloqueada. Obrigatório. - `automation_bypass` boolean, nullable — Quando true, automações podem mover o projeto mesmo com o bloqueio ativo. - `access` object[] — Acesso ao funil por usuário. - `id` string, uuid — ID (UUID) do usuário. - `index_all` boolean — Concede ver todos os projetos do funil. - `index_assigned` boolean — Concede ver os projetos em que está designado. - `index_created` boolean — Concede ver os projetos que criou. - `attachments` object[] — Anexos do funil. - `id` integer — ID do anexo a vincular ao funil. - `template_projects` object[] — Projetos-modelo oferecidos ao criar projetos neste funil. - `id` string, uuid — ID (UUID) de um projeto-modelo da conta. ## Response `200` Sucesso - object - `response` boolean, required — Sempre true quando a operação é concluída. - `project_funnel` object, required — Funil de projeto. - `id` integer — ID do funil. - `name` string — Nome do funil. - `prefix` string, nullable — Prefixo usado no código dos projetos do funil. - `order` integer — Posição do funil na ordem de exibição. - `condition` 'active' | 'inactive' — Situação do funil. - `allow_multi_step` boolean — Indica se o projeto pode ocupar várias etapas ao mesmo tempo. - `project_term` object, nullable — Vocabulário do funil para o termo 'projeto'. - `show_cost_info` boolean — Indica se as informações de custo aparecem no funil. - `allow_execution` boolean — Indica se o funil permite cronometrar execução. - `business_area_id` integer, nullable — ID da área de negócio do funil. - `form_id` integer, nullable — ID do formulário de vínculo do funil. - `funnel_config_template_id` integer, nullable — Modelo de configuração de quadro em uso. - `frame_id` string, uuid — ID (UUID) da conta dona do funil. - `created_at` string, date-time — Data de criação. - `updated_at` string, date-time — Data da última alteração. - `deleted_at` string, date-time, nullable — Data de arquivamento, quando o funil está arquivado. - `objects_above_limit` string[] — Objetos barrados pelo limite do plano. Vazio quando tudo coube. ## Other responses - `401` — Não autorizado - `422` — Etiquetas repetidas ## Changes - **2026-08-24** `3c590152d5b5` — 7 breaking, 10 warning, 23 info - added the new required request property `name` - added the new required request property `steps` - the request's body type changed from no type to `object` - the response property `project_funnel/business_area_id` became nullable for the status `200` - …36 more - **2026-08-19** `159cf36842c5` — 8 warning, 2 info - the optional response header `Access-Control-Allow-Origin` removed for the status `422` - the optional response header `Access-Control-Expose-Headers` removed for the status `422` - the optional response header `X-Frame-Options` removed for the status `422` - the optional response header `X-Ratelimit-Limit` removed for the status `422` - …6 more - **2026-08-19** `f3efb100a3fc` — 1 info - api tag `Funis` added [Change history](https://skmtc.dev/olie-ai/apis/olie-api/changes/api/management/project-funnel/post.md) --- [API](https://skmtc.dev/olie-ai/apis/olie-api.md) · [All operations](https://skmtc.dev/olie-ai/apis/olie-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/olie-ai/olie-api/revisions/8c9bac94e5ad/schema)