Ir para o conteúdo
Pipefácil

Criar negócio

Ver como MarkdownConfigurar agente
POST/api/v1/deals

Cria um negócio no workspace da chave e retorna o registro criado.

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/deals" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Proposta de consultoria",
  "contactFirstName": "Ana",
  "contactLastName": "Silva",
  "email": "ana@example.com",
  "value": 1500,
  "currency": "BRL"
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/deals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Proposta de consultoria",
  "contactFirstName": "Ana",
  "contactLastName": "Silva",
  "email": "ana@example.com",
  "value": 1500,
  "currency": "BRL"
}),
});

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/deals",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"name\": \"Proposta de consultoria\",\n  \"contactFirstName\": \"Ana\",\n  \"contactLastName\": \"Silva\",\n  \"email\": \"ana@example.com\",\n  \"value\": 1500,\n  \"currency\": \"BRL\"\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "name": "Proposta de consultoria",
  "contactFirstName": "Ana",
  "contactLastName": "Silva",
  "email": "ana@example.com",
  "value": 1500,
  "currency": "BRL"
}
CampoTipoObrigatório no objetoDescrição
namestringNãoAceita null. Até 255 caracteres.
phonestringNãoTelefone do contato, opcional. Sem telefone, o negócio pode não ter contato; um nome ou e-mail permite criar um contato sem telefone. Aceita null.
contactNamestringNãoNome completo do contato, dividido no primeiro espaço em firstName/lastName. Ignorado quando contactFirstName ou contactLastName é enviado. Aceita null. Até 255 caracteres.
contactFirstNamestringNãoAceita null. Até 255 caracteres.
contactLastNamestringNãoAceita null. Até 255 caracteres.
emailstringNãoFormato: email. Aceita null. Até 255 caracteres.
notesstringNãoAceita null. Até 2000 caracteres.
valuenumberNãoAceita null. Mínimo: 0.
closeProbabilityintegerNãoAceita null. Mínimo: 0. Máximo: 100.
expectedCloseAtstringNãoFormato: date-time. Aceita null.
currencystringNãoPadrão: BRL. Aceita null. Até 3 caracteres.
stageIdstringNãoPadrão: primeira etapa do funil. Aceita null.
companyIdstringNãoAceita null.
channelIdstringNãoAceita null.
responsibleUserIdstringNãoAceita null.
useAssignmentStrategybooleanNãoAceita null.
customFieldsobjectNãoAceita null.
companyobjectNãoAceita null.
company.namestringSimAté 255 caracteres.
company.domainstringNãoAceita null. Até 255 caracteres.
company.cnpjstringNãoAceita null. Até 30 caracteres.
company.industrystringNãoAceita null. Até 255 caracteres.
company.websitestringNãoAceita null. Até 500 caracteres.
company.logoUrlstringNãoAceita null. Até 500 caracteres.
company.notesstringNãoAceita null. Até 2000 caracteres.
trackingobjectNãoAceita null.
tracking.utmContentstringNãoAceita null.
tracking.utmMediumstringNãoAceita null.
tracking.utmCampaignstringNãoAceita null.
tracking.utmSourcestringNãoAceita null.
tracking.utmTermstringNãoAceita null.
tracking.utmReferrerstringNãoAceita null.
tracking.referrerstringNãoAceita null.
tracking.gclientidstringNãoAceita null.
tracking.gclidstringNãoAceita null.
tracking.fbclidstringNãoAceita null.
tracking.metaLeadIdstringNãoAceita null.
tracking.fbpstringNãoAceita null.
tracking.fbcstringNãoAceita null.
tracking.clientIpAddressstringNãoAceita null.
tracking.clientUserAgentstringNãoAceita null.
tracking.ctwaClidstringNãoAceita null.
metadataobjectNãoMetadados adicionais do negócio. Aceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "nullable": true
    },
    "phone": {
      "type": "string",
      "description": "Telefone do contato, opcional. Sem telefone, o negócio pode não ter contato; um nome ou e-mail permite criar um contato sem telefone.",
      "nullable": true
    },
    "contactName": {
      "type": "string",
      "maxLength": 255,
      "nullable": true,
      "description": "Nome completo do contato, dividido no primeiro espaço em firstName/lastName. Ignorado quando contactFirstName ou contactLastName é enviado."
    },
    "contactFirstName": {
      "type": "string",
      "maxLength": 255,
      "nullable": true
    },
    "contactLastName": {
      "type": "string",
      "maxLength": 255,
      "nullable": true
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 255,
      "nullable": true
    },
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "nullable": true
    },
    "value": {
      "type": "number",
      "minimum": 0,
      "nullable": true
    },
    "closeProbability": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "nullable": true
    },
    "expectedCloseAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "currency": {
      "type": "string",
      "maxLength": 3,
      "nullable": true,
      "description": "Padrão: BRL."
    },
    "stageId": {
      "type": "string",
      "nullable": true,
      "description": "Padrão: primeira etapa do funil."
    },
    "companyId": {
      "type": "string",
      "nullable": true
    },
    "channelId": {
      "type": "string",
      "nullable": true
    },
    "responsibleUserId": {
      "type": "string",
      "nullable": true
    },
    "useAssignmentStrategy": {
      "type": "boolean",
      "nullable": true
    },
    "customFields": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "company": {
      "allOf": [
        {
          "$ref": "#/components/schemas/CreateCompanyRequest"
        }
      ],
      "nullable": true
    },
    "tracking": {
      "allOf": [
        {
          "$ref": "#/components/schemas/DealTracking"
        }
      ],
      "nullable": true
    },
    "metadata": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Metadados adicionais do negócio."
    }
  },
  "example": {
    "name": "Proposta de consultoria",
    "contactFirstName": "Ana",
    "contactLastName": "Silva",
    "email": "ana@example.com",
    "value": 1500,
    "currency": "BRL"
  }
}

Respostas

201Criado
CampoTipoDescrição
dataDealResponseNegócio resumido retornado na criação ou atualização.
data.idstring—
data.seqinteger—
data.namestring—
data.contactIdstringAceita null.
data.responsibleUserIdstring—
data.companyIdstringAceita null.
data.pipelineIdstring—
data.stageIdstring—
data.valuenumber—
data.currencystring—
data.closeProbabilityinteger—
data.sourcestring—
data.statusstringopen | won | lost
data.coOwnerUserIdstringAceita null.
data.expectedCloseAtstringFormato: date-time. Aceita null.
data.stageChangedAtstringFormato: date-time.
data.closedAtstringFormato: date-time. Aceita null.
data.lostReasonstringAceita null.
data.customFieldsobject—
data.createdAtstringFormato: date-time.
data.trackingobjectAceita null.
data.tracking.utmContentstringAceita null.
data.tracking.utmMediumstringAceita null.
data.tracking.utmCampaignstringAceita null.
data.tracking.utmSourcestringAceita null.
data.tracking.utmTermstringAceita null.
data.tracking.utmReferrerstringAceita null.
data.tracking.referrerstringAceita null.
data.tracking.gclientidstringAceita null.
data.tracking.gclidstringAceita null.
data.tracking.fbclidstringAceita null.
data.tracking.metaLeadIdstringAceita null.
data.tracking.fbpstringAceita null.
data.tracking.fbcstringAceita null.
data.tracking.clientIpAddressstringAceita null.
data.tracking.clientUserAgentstringAceita null.
data.tracking.ctwaClidstringAceita null.
messagestringAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/DealResponse"
    },
    "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"
  ]
}
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