Criar oportunidade no pipeline certo

Pro e FullAtualizado em 13/10/2026

Oportunidade é o cartão no kanban. Pra criar uma pela API você precisa do id do contato, do pipeline e da fase. Os dois últimos são descobertos uma vez e guardados.

1. Descobrir pipeline e fase

curl "https://services.leadconnectorhq.com/opportunities/pipelines?locationId=ID_DA_CONTA" \
  -H "Authorization: Bearer SEU_TOKEN" -H "Version: 2021-07-28"

Escopo opportunities.readonly. Resposta:

{
  "pipelines": [
    {
      "id": "pipe_8f2c...",
      "name": "Vendas",
      "stages": [
        { "id": "st_01...", "name": "Novo", "position": 0 },
        { "id": "st_02...", "name": "Em contato", "position": 1 }
      ]
    }
  ]
}

Guarde pipelines[].id e stages[].id. Eles não mudam quando alguém renomeia a fase; mudam só se a fase for apagada e recriada.

2. Criar

curl -X POST "https://services.leadconnectorhq.com/opportunities/" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ID_DA_CONTA",
    "pipelineId": "pipe_8f2c...",
    "pipelineStageId": "st_01...",
    "contactId": "ocQHyuzHvysMo5N5VsXc",
    "name": "Maria Souza · Apartamento 2 quartos",
    "status": "open",
    "monetaryValue": 350000,
    "assignedTo": "ID_DO_USUARIO",
    "source": "Site institucional"
  }'

Escopo opportunities.write.

Campo	Obrigatório	Observação
`locationId`, `pipelineId`, `pipelineStageId`, `contactId`, `name`	Sim	`name` é o título do cartão
`status`	Sim	`open`, `won`, `lost` ou `abandoned`
`monetaryValue`	Não, mas preencha	Número, sem formatação. É o que o painel soma
`assignedTo`	Não	Id do usuário dono. Lista em `GET /users/?locationId=` com escopo `users.readonly`
`customFields`	Não	Mesmo formato do contato: `[{ "id": "...", "field_value": "..." }]`

Evitar oportunidade duplicada

Antes de criar, procure se o contato já tem oportunidade aberta no pipeline:

curl "https://services.leadconnectorhq.com/opportunities/search?location_id=ID_DA_CONTA&contact_id=ocQHyuzHvysMo5N5VsXc&status=open" \
  -H "Authorization: Bearer SEU_TOKEN" -H "Version: 2021-07-28"

Achou? Atualize em vez de criar. Existe também um endpoint de upsert de oportunidade (POST /opportunities/upsert) que faz essa checagem por contato e pipeline.

Atualizar

Mudar valor, nome, fase ou dono: PUT /opportunities/{id} com só os campos que mudam.
Marcar ganho ou perdido: PUT /opportunities/{id}/status com { "status": "won" } ou "lost".

Mudança de fase feita pela API dispara automação de "fase mudou" igual à feita na tela.

O que a tela faz e a API não

Motivo da perda com lista fixa e as cores das fases são coisas da tela. Pela API, lost sem motivo. Se o motivo importa pro seu relatório, grave num campo personalizado da oportunidade.