Ir para o conteúdo
Pipefácil

Criar funil

Ver como MarkdownConfigurar agente
POST/api/v1/pipelines

Cria um funil no workspace da chave e retorna suas etapas. Exige settings.pipelines. stages define as etapas ativas, em ordem. Quando omitido ou vazio, cria Leads, Qualificação, Proposta, Negociação e Fechamento. O sistema acrescenta as etapas finais Ganho e Perda. Não envie etapas finais nem isWon/isLost: a API responde 400. O primeiro funil ativo torna-se o padrão do workspace. O limite de funis do plano se aplica; quando atingido, a API responde 409 QUOTA_EXCEEDED. Qualquer behaviors exige PIPELINE_BEHAVIORS, ou a resposta será 400. Para usar attendance_queue, crie o funil primeiro. Depois configure behaviors e attendanceQueueStageId em PATCH /api/v1/pipelines/{seq}, usando uma etapa do próprio funil.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request POST \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/pipelines" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Pós-venda",
  "description": "Clientes que já compraram",
  "stages": [
    {
      "name": "Onboarding",
      "color": "#3b82f6"
    },
    {
      "name": "Acompanhamento"
    }
  ]
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/pipelines`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Pós-venda",
  "description": "Clientes que já compraram",
  "stages": [
    {
      "name": "Onboarding",
      "color": "#3b82f6"
    },
    {
      "name": "Acompanhamento"
    }
  ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;
Python
import os
import json
import requests

response = requests.request(
    "POST",
    f"https://pipefacil-server.matchsales.com.br/api/v1/pipelines",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"name\": \"Pós-venda\",\n  \"description\": \"Clientes que já compraram\",\n  \"stages\": [\n    {\n      \"name\": \"Onboarding\",\n      \"color\": \"#3b82f6\"\n    },\n    {\n      \"name\": \"Acompanhamento\"\n    }\n  ]\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "name": "Pós-venda",
  "description": "Clientes que já compraram",
  "stages": [
    {
      "name": "Onboarding",
      "color": "#3b82f6"
    },
    {
      "name": "Acompanhamento"
    }
  ]
}
CampoTipoObrigatório no objetoDescrição
namestringSimAté 255 caracteres.
descriptionstringNãoOpcional. Objetivo do funil; usado como contexto pela CIA. Aceita null. Até 2000 caracteres.
stagesarrayNãoEtapas ativas em ordem. Omitir ou enviar lista vazia cria as etapas padrão. O sistema acrescenta as etapas de ganho e perda. Aceita null.
stages[].namestringSimAté 255 caracteres.
stages[].colorstringNãoCor hexadecimal. Padrão: #6366f1.
stages[].descriptionstringNãoOpcional. Condição esperada para o negócio estar nesta etapa; usada como contexto pela CIA. Aceita null. Até 2000 caracteres.
behaviorsarrayNãoNão configure attendance_queue na criação: exige uma etapa do próprio funil. Configure por PATCH depois de criar. Aceita null.
pipelineTypestringNãoEntrada legada, ignorada. Configure behaviors para definir o comportamento do funil. Valores: standard, recurring_clients. Aceita null.
attendanceQueueStageIdstringNãoA fila exige uma etapa já existente neste funil. Configure após a criação, com PATCH e behaviors. Aceita null.
Esquema OpenAPI
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 2000,
      "description": "Opcional. Objetivo do funil; usado como contexto pela CIA."
    },
    "stages": {
      "type": "array",
      "nullable": true,
      "description": "Etapas ativas em ordem. Omitir ou enviar lista vazia cria as etapas padrão. O sistema acrescenta as etapas de ganho e perda.",
      "items": {
        "$ref": "#/components/schemas/PipelineStageRequest"
      }
    },
    "behaviors": {
      "type": "array",
      "nullable": true,
      "items": {
        "$ref": "#/components/schemas/PipelineBehavior"
      },
      "description": "Não configure `attendance_queue` na criação: exige uma etapa do próprio funil. Configure por `PATCH` depois de criar."
    },
    "pipelineType": {
      "type": "string",
      "nullable": true,
      "deprecated": true,
      "enum": [
        "standard",
        "recurring_clients"
      ],
      "description": "Entrada legada, ignorada. Configure behaviors para definir o comportamento do funil."
    },
    "attendanceQueueStageId": {
      "type": "string",
      "description": "A fila exige uma etapa já existente neste funil. Configure após a criação, com PATCH e behaviors.",
      "nullable": true
    }
  },
  "example": {
    "name": "Vendas",
    "description": "Qualificação e fechamento de novas oportunidades."
  }
}

Respostas

201Criado: funil com todas as etapas.
CampoTipoDescrição
dataPipeline—
data.idstring—
data.seqintegerNúmero sequencial no workspace usado em /api/v1/pipelines/{seq}.
data.positionintegerOrdem de exibição entre os funis ativos.
data.namestring—
data.descriptionstringAceita null.
data.isDefaultboolean—
data.isArchivedboolean—
data.exitStageIdstringAceita null.
data.pipelineTypestringDerivado de behaviors; mantido por compatibilidade. Valores: standard, recurring_clients.
data.behaviorsarray—
data.attendanceQueueStageIdstringAceita null.
data.stagesarrayEtapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda.
data.stages[].idstringIdentificador da etapa usado em stageId na API, por exemplo, em POST /api/v1/deals.
data.stages[].seqinteger—
data.stages[].orderinteger—
data.stages[].namestring—
data.stages[].colorstring—
data.stages[].descriptionstringCondição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null.
data.stages[].isWonboolean—
data.stages[].isLostboolean—
data.stages[].isRequiredboolean—
data.stages[].requiredMilestoneFieldIdstringAceita null.
data.stages[].dealCountintegerFormato: int64.
data.createdAtstringFormato: date-time.
data.updatedAtstringFormato: date-time.
messagestringAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Pipeline"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
400Falha de validação dos campos; `fieldErrors` contém os erros.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
403Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
409Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
429Limite de requisições excedido por workspace ou IP.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
OpenAPI JSONMarkdown desta operação

Precisa de ajuda?

Encontrou um problema ou ficou com uma dúvida? Fale com a equipe pelo WhatsApp.

Chamar no WhatsApp
Pipefácil