Criar negócio

Endpoint

POST /v1/deals

Escopo necessário: write:deals

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título do negócio
`pipeline_id`	string	Sim	ID do pipeline
`stage_id`	string	Não	ID da etapa. Se omitido, usa a primeira etapa do funil de venda
`value`	number	Não	Valor em reais. Padrão: `0`
`contact_ids`	string[]	Não	IDs dos contatos vinculados, todos da sua organização
`company_id`	string	Não	ID da empresa
`assigned_to`	string	Não	ID do membro responsável
`expected_close_date`	string	Não	Data prevista de fechamento (ISO 8601)
`tags`	string[]	Não	Tags
`custom_fields`	object	Não	Campos personalizados

Obtendo o pipeline_id

Use GET /v1/pipelines para listar os pipelines disponíveis e seus IDs de etapas.

Exemplo de requisição

curl -X POST https://api.socialsell.ai/v1/deals \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato Anual - TechCorp",
    "pipeline_id": "664a1b2c3d4e5f6789012345",
    "value": 36000,
    "contact_ids": ["664f1a2b3c4d5e6f78901234"],
    "company_id": "664b1c2d3e4f5a6789012346",
    "expected_close_date": "2026-08-31T00:00:00.000Z",
    "tags": ["contrato-anual"]
  }'

Resposta

Retorna HTTP 201 com o objeto negócio criado. A resposta inclui stage.id (ID da etapa) e stage.name (nome legível). Use contact_ids como lista. Campos desconhecidos, como contact_id, retornam 422 com código UNKNOWN_FIELDS e o nome do campo em error.details. A criação dispara o evento deal.created em webhooks configurados.

Erros

Código	Status	Descrição
`MISSING_REQUIRED_FIELD`	`400`	`title` ou `pipeline_id` ausente
`PIPELINE_NOT_FOUND`	`404`	Funil de venda não encontrado
`STAGE_NOT_FOUND`	`404`	Etapa não encontrada no funil de venda
`NO_STAGES`	`422`	Funil de venda não tem etapas
`PIPELINE_INACTIVE`	`422`	Funil desativado não aceita negócios novos
`UNKNOWN_FIELDS`	`422`	Campo não aceito neste endpoint; consulte `error.details`
`INVALID_REFERENCE`	`422`	Vínculo inválido, inexistente ou de outra organização

Contatos

Empresas

Negócios

Funis de venda

Conversas

Mensagens

Tarefas

Campos personalizados

Agentes de IA

Disparos

Créditos de mensagem

Lookup

Endpoint

Corpo da requisição

Obtendo o pipeline_id

Exemplo de requisição

Resposta

Erros

​Endpoint

​Corpo da requisição

​Obtendo o pipeline_id

​Exemplo de requisição

​Resposta

​Erros

Endpoint

Corpo da requisição

Obtendo o pipeline_id

Exemplo de requisição

Resposta

Erros