Criar e consultar negócios pela API

Use GET /api/v1/deals. Sem status, a consulta inclui open, won e lost. Para consultar apenas abertos, envie status=open; para vários estados, repita o parâmetro ou separe por vírgula.

curl --get 'https://pipefacil-server.matchsales.com.br/api/v1/deals' \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --data-urlencode 'status=open' \
  --data-urlencode 'pipeline=1' \
  --data-urlencode 'limit=50'

pipeline recebe a sequência do funil. stageId, tagIds e responsibleUserIds recebem IDs técnicos. Os negócios vêm pela criação mais recente. Os filtros do aplicativo não são todos parâmetros dessa rota: consulte a referência.

Para valores exatos, use customFields[slug]. O valor __empty__ seleciona campos não preenchidos. Para intervalos, use customFieldRanges[slug][from] e [to]. Os slugs nativos incluem value, close_probability, expected_close_at, stage_changed_at, updated_at, lost_reason e lost_from_stage; os dois últimos usam valores exatos.

POST /api/v1/deals aceita telefone opcional. Sem telefone ou dados de contato, o negócio pode ficar sem contato. Com nome ou e-mail, pode ser criado um contato sem telefone.

{
	"name": "Proposta de consultoria",
	"contactFirstName": "Ana",
	"contactLastName": "Silva",
	"email": "ana@example.com",
	"value": 1500,
	"currency": "BRL"
}

Envie primeiro nome e sobrenome separados. Quando usados, eles têm preferência sobre contactName. stageId escolhe a etapa inicial; quando omitido, o servidor usa a primeira etapa do funil escolhido pelas regras de criação.

O corpo também aceita campos personalizados, empresa, dados de rastreio e metadados. Use tracking.ctwaClid para o identificador de clique Click to WhatsApp quando ele estiver disponível na origem.

Use GET /api/v1/deals/{seq} e PATCH /api/v1/deals/{seq}. O PATCH aceita alterações parciais; revise as regras de movimento, campos obrigatórios e motivo da perda antes de mudar a etapa.

properties contém valores resolvidos dos campos personalizados. Resumo de tarefas e última atividade podem ser nulos quando não estiverem habilitados na configuração do card. lostFromStage informa a etapa anterior à perda.

Para extrair valores de campos em vários negócios, use GET /api/v1/deals/custom-field-values com os filtros da referência.

Confira o retorno de cada escrita. As tarefas têm corpo próprio, com prazo e responsável; os tipos aceitos estão na referência. Não use os exemplos de uma nota como corpo de uma tarefa.

A interface chama o negócio de lead; a API usa deal. Para integrar um formulário externo, comece pela autenticação e siga esta sequência:

Criar o registro e enviar uma mensagem são operações distintas. Uma automação ativa com gatilho Lead criado pode executar ações após o cadastro. Revise o fluxo de primeiro atendimento e as regras do canal antes de integrar a origem. O contrato completo do corpo está em Criar negócio.