Negócios

GET    {BASE_URL}/api-v1-deals                 # lista
GET    {BASE_URL}/api-v1-deals/:id             # detalhe
POST   {BASE_URL}/api-v1-deals                 # cria
PATCH  {BASE_URL}/api-v1-deals/:id             # atualiza
POST   {BASE_URL}/api-v1-deals/:id/move-stage  # mover de etapa
POST   {BASE_URL}/api-v1-deals/:id/win         # marcar como ganho
POST   {BASE_URL}/api-v1-deals/:id/lose        # marcar como perdido

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/deals), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopos: deals:read para os GET; deals:write para a escrita.

PATCH não aceita status, stage_id, pipeline_id, won_at nem lost_at — mudança de etapa e fecho passam pelas ações.

Campos

Campo	Tipo	Escrita	Notas
`id`	uuid	somente leitura
`workspace_id`	uuid	somente leitura	Sempre o workspace da chave de API usada na chamada.
`name`	string	criar: obrigatório, editar: sim	De 1 a 255 caracteres.
`status`	string	somente leitura	aberto \| em_andamento \| ganho \| perdido. Só muda por /win, /lose e /move-stage.
`value`	number	criar: opcional, editar: sim	Mínimo 0.
`recurring_value`	number	criar: opcional, editar: sim	Mínimo 0.
`pipeline_id`	uuid	criar: opcional, editar: não	Omitido na criação, usa o funil padrão do cliente. formato uuid; deve existir na ficha `pipelines`.
`stage_id`	uuid	criar: opcional, editar: não	Trocar de etapa depois de criado é POST /deals/:id/move-stage. formato uuid.
`owner_id`	uuid	criar: opcional, editar: sim	Traduzível pela ficha `owners`. formato uuid; deve existir na ficha `owners`.
`contact_id`	uuid	criar: opcional, editar: sim	Formato uuid; deve existir na ficha `contacts`.
`company_id`	uuid	criar: opcional, editar: sim	Formato uuid; deve existir na ficha `companies`.
`expected_close_date`	date	criar: opcional, editar: sim	Data de calendário YYYY-MM-DD — nunca convertida para datetime. formato date.
`lead_source_id`	uuid	criar: opcional, editar: sim	Traduzível pela ficha `lead-sources`. formato uuid; deve existir na ficha `lead-sources`.
`loss_reason_id`	uuid	somente leitura	Primeiro motivo da lista. Traduzível pela ficha `loss-reasons`. Gravado por /lose.
`loss_reason_ids`	lista de textos	somente leitura	Todos os motivos de perda do negócio, na ordem registrada. Gravado por /lose. Campo montado pela API (não é coluna direta).
`won_at`	datetime	somente leitura
`lost_at`	datetime	somente leitura
`stage_entered_at`	datetime	somente leitura
`external_id`	string	somente leitura	Gravado só pela entrada de lead (`leads`), não por POST /deals.
`source`	string	somente leitura	Gravado só pela entrada de lead (`leads`), não por POST /deals.
`notes`	string	criar: opcional, editar: sim	Máximo 10000 caracteres.
`custom_fields`	objeto	criar: opcional, editar: sim	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.
`created_at`	datetime	somente leitura
`updated_at`	datetime	somente leitura

Listar negócios

GET {BASE_URL}/api-v1-deals

Parâmetro (query)	Tipo	Notas
`status`	string	aberto/em_andamento devolvem os dois estados ativos. Valores: `aberto`, `em_andamento`, `ganho`, `perdido`. Compara: um dos valores.
`pipeline_id`	uuid
`stage_id`	uuid
`owner_id`	uuid
`since`	datetime	Só registros criados a partir desta data (ISO 8601). Compara: maior ou igual a.
`limit`	number	Tamanho da página. Padrão 50, máximo 200.
`cursor`	uuid	Próxima página — use o `meta.next_cursor` da resposta anterior.

Ordenação: id crescente. Paginação por cursor.

curl "{BASE_URL}/api-v1-deals?status=aberto" \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um registro

GET {BASE_URL}/api-v1-deals/:id → o recurso completo, ou 404 not_found.

O detalhe traz blocos embutidos (cada um é um objeto ou null):

Bloco	Ficha	Notas
`contact`	`contacts`	Apontado por `contact_id`.
`company`	`companies`	Apontado por `company_id`.
`last_activity`	`activities`	Atividade mais recente do negócio (completed_at, scheduled_at, created_at desc).

curl "{BASE_URL}/api-v1-deals/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

Criar

POST {BASE_URL}/api-v1-deals — escopo deals:write.

Campo	Tipo	Obrigatório	Notas
`name`	string	Sim	De 1 a 255 caracteres.
`value`	number	Não	Mínimo 0.
`recurring_value`	number	Não	Mínimo 0.
`pipeline_id`	uuid	Não	Omitido na criação, usa o funil padrão do cliente. formato uuid; deve existir na ficha `pipelines`.
`stage_id`	uuid	Não	Trocar de etapa depois de criado é POST /deals/:id/move-stage. formato uuid.
`owner_id`	uuid	Não	Traduzível pela ficha `owners`. formato uuid; deve existir na ficha `owners`.
`contact_id`	uuid	Não	Formato uuid; deve existir na ficha `contacts`.
`company_id`	uuid	Não	Formato uuid; deve existir na ficha `companies`.
`expected_close_date`	date	Não	Data de calendário YYYY-MM-DD — nunca convertida para datetime. formato date.
`lead_source_id`	uuid	Não	Traduzível pela ficha `lead-sources`. formato uuid; deve existir na ficha `lead-sources`.
`notes`	string	Não	Máximo 10000 caracteres.
`custom_fields`	objeto	Não	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

curl -X POST "{BASE_URL}/api-v1-deals" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "..." }'

Atualizar

PATCH {BASE_URL}/api-v1-deals/:id — escopo deals:write. Todos os campos são opcionais; só o que vier no corpo muda.

Campo	Tipo	Obrigatório	Notas
`name`	string	Não	De 1 a 255 caracteres.
`value`	number	Não	Mínimo 0.
`recurring_value`	number	Não	Mínimo 0.
`owner_id`	uuid	Não	Traduzível pela ficha `owners`. formato uuid; deve existir na ficha `owners`.
`contact_id`	uuid	Não	Formato uuid; deve existir na ficha `contacts`.
`company_id`	uuid	Não	Formato uuid; deve existir na ficha `companies`.
`expected_close_date`	date	Não	Data de calendário YYYY-MM-DD — nunca convertida para datetime. formato date.
`lead_source_id`	uuid	Não	Traduzível pela ficha `lead-sources`. formato uuid; deve existir na ficha `lead-sources`.
`notes`	string	Não	Máximo 10000 caracteres.
`custom_fields`	objeto	Não	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

curl -X PATCH "{BASE_URL}/api-v1-deals/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "value": 0, "recurring_value": 0 }'

Ações

Mover de etapa

POST {BASE_URL}/api-v1-deals/:id/move-stage — escopo deals:write.

Campo	Tipo	Obrigatório	Notas
`stage_id`	uuid	Sim	Formato uuid.

Publica o webhook deal.stage_changed.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../move-stage" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "8f3c..." }'

Marcar como ganho

POST {BASE_URL}/api-v1-deals/:id/win — escopo deals:write.

Idempotente: repetir não muda nada nem republica o evento.

Campo	Tipo	Obrigatório	Notas
`won_at`	datetime	Não	Formato datetime.

Publica o webhook deal.won.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../win" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "won_at": "2026-08-01T14:00:00Z" }'

Marcar como perdido

POST {BASE_URL}/api-v1-deals/:id/lose — escopo deals:write.

Idempotente. loss_reason_ids manda sobre loss_reason_id quando os dois vêm.

Campo	Tipo	Obrigatório	Notas
`loss_reason_id`	uuid	Não	Formato uuid; deve existir na ficha `loss-reasons`.
`loss_reason_ids`	lista de textos	Não	De 1 a 20 itens; deve existir na ficha `loss-reasons`.
`notes`	string	Não	Máximo 10000 caracteres.

Publica o webhook deal.lost.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../lose" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "loss_reason_id": "8f3c..." }'

Webhooks desta ficha

deal.created
deal.stage_changed
deal.won
deal.lost
deal.stale

Formato do envio, cabeçalhos e verificação da assinatura em Webhooks.

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `deals:read` / `deals:write`.
`404`	`not_found`	O registro não existe neste cliente.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`422`	`invalid_reference`	`pipeline_id`, `owner_id`, `contact_id`, `company_id`, `lead_source_id` aponta para fora deste cliente.
`422`	`invalid_cursor`	O `cursor` enviado não é válido.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.

Idempotência

Envie um header Idempotency-Key (1–255 caracteres, qualquer string única sua) para tornar o POST acima seguro de reenviar em caso de timeout de rede ou retry automático:

curl -X POST "{BASE_URL}/api-v1-deals" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-9f21" \
  -d '{ "name": "Projeto Q3 - Empresa Exemplo", "value": 24000 }'

Mesma chave, mesmo corpo: a segunda chamada não cria outro negócio — responde 200 OK com o corpo da resposta original (não 201), e o webhook deal.created não é reemitido.
Mesma chave, corpo diferente (ou reusada em outro recurso): 422 idempotency_conflict — a chave é sua, reusá-la para outra coisa é erro do cliente.
Mesma chave, requisição original ainda processando: 409 idempotency_in_progress — duas chamadas concorrentes com a mesma chave; espere e tente de novo.
Janela: a chave fica registrada por 24 horas; depois disso pode ser reusada como se fosse nova.
Sem o header: comportamento idêntico ao de hoje — cada POST cria um negócio novo.

Erros específicos desta ficha

HTTP	`code`	Quando
`400`	`bad_request`	Corpo ausente/JSON inválido (escrita).
`422`	`no_default_pipeline` / `pipeline_has_no_stage` / `no_owner_available`	Falha ao resolver pipeline/etapa/responsável na criação.
`400`	`invalid_idempotency_key`	`Idempotency-Key` fora de 1–255 caracteres.
`422`	`idempotency_conflict`	Mesma `Idempotency-Key` com corpo ou recurso diferente.
`409`	`idempotency_in_progress`	Mesma `Idempotency-Key` já em processamento (corrida).

Negócios

Nesta página