Negociacoes

/v1/deals · estágio, contatos, empresa, origem, responsável, qualificação e valores calculados.

As negociações dos funis de venda: estágio, contatos, empresa, origem, responsável, qualificação e valores.

Método	Rota	Operação
GET	/v1/deals, /v1/deals/{id}	read
POST	/v1/deals	insert
PUT	/v1/deals/{id}	update

Valores e status

Os valores são calculados a partir dos produtos da negociação (total da linha = (preço − desconto) × quantidade, nunca negativo):

• total_amount soma todas as linhas

• recurring_amount soma as linhas de produtos recorrentes

• one_time_amount soma as demais

O campo status é derivado do estágio: negociação no estágio de sucesso do funil vira won; no estágio de falha, lost; qualquer outro, ongoing.

Todo payload de negociação retorna o kanban_id e o kanban_status_id atuais. Um GET /v1/deals/{id} é suficiente para descobrir os ids necessários para uma movimentação. Os ids dos demais estágios do funil vêm do painel.

Filtros

Parâmetro	Comportamento
name	exato (sem diferenciar maiúsculas); name__contains para parcial
status	enum: ongoing, won, lost; lista separada por vírgula combina com OU (?status=won,lost)
kanban_id, kanban_status_id, owner_id, company_id, source_id	inteiro ou lista separada por vírgula
contact_ids	inteiro ou lista (negociações vinculadas a qualquer um dos contatos)
rating	inteiro ou lista; também rating__gte/__lte/__gt/__lt
expected_close_date__…, closed_at__…, created_at__…, updated_at__…	comparação ISO 8601 (__gte/__lte/__gt/__lt)

Ordenação: name, rating, created_at, updated_at, closed_at (padrão -created_at).

curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/deals?status=won&closed_at__gte=2026-06-01"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/deals?status=won,lost&sort=-closed_at"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/deals?company_id=87&rating__gt=3&sort=-rating"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/deals?contact_ids=4521"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/deals/310"

Payload

{
  "data": {
    "id": 310,
    "name": "Negociação - Plano Anual",
    "company_id": 87,
    "contact_ids": [4521],
    "source_id": 5,
    "owner_id": 3,
    "kanban_id": 9,
    "kanban_status_id": 42,
    "rating": 4,
    "total_amount": 1500,
    "recurring_amount": 1200,
    "one_time_amount": 300,
    "expected_close_date": "2026-07-15",
    "status": "ongoing",
    "closed_at": null,
    "created_at": "2026-06-01T11:00:00.000Z",
    "updated_at": "2026-06-20T15:20:00.000Z"
  }
}

Escrita

Campo	Tipo	Observações
kanban_id	inteiro	obrigatório no POST; imutável no PUT (422)
kanban_status_id	inteiro	obrigatório no POST (deve pertencer ao funil); no PUT, move a negociação para o estágio informado
contact_ids	inteiro[]	obrigatório no POST (mínimo 1); no PUT substitui o conjunto de contatos (o mínimo de 1 continua valendo)
name	string, anulável	por padrão, o nome do primeiro contato
owner_id, company_id, source_id	inteiro, anulável	devem existir na conta
rating	inteiro 1 a 5, anulável	qualificação (estrelas)
expected_close_date	data ISO, anulável	previsão de fechamento
status	enum	apenas no PUT: won / lost movem a negociação para o estágio de sucesso/falha do funil (422 se o funil não os tiver configurados); ongoing não é aceito. Para reabrir, envie kanban_status_id com o estágio de destino. Não pode ser combinado com kanban_status_id na mesma requisição

O campo lost_reason não é suportado.

Efeitos no CRM

Negociações criadas ou movidas pela API aparecem em tempo real no quadro do funil e têm cada alteração registrada na linha do tempo (incluindo 🎉/❌ ao entrar nos estágios terminais). closed_at é preenchido quando a negociação entra no estágio de sucesso ou falha e limpo quando ela sai. Criações e movimentações disparam as automações configuradas no funil (ex.: "negociação criada", "negociação movida").

Os fluxos de conversa associados a estágios não são disparados por movimentações via API, e as configurações de campos obrigatórios por estágio não bloqueiam escritas via API.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"kanban_id":9,"kanban_status_id":40,"contact_ids":[4521],"name":"Negociação - Plano Anual","rating":4}' \
  "https://app-api.atendeserver.com.br/v1/deals"

# mover de estágio / marcar como ganha / reabrir
curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"kanban_status_id":42}' "https://app-api.atendeserver.com.br/v1/deals/310"
curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"won"}' "https://app-api.atendeserver.com.br/v1/deals/310"   # closed_at é preenchido
curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"kanban_status_id":40}' "https://app-api.atendeserver.com.br/v1/deals/310"   # closed_at é limpo

# edições de campos + substituição de contatos
curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"rating":5,"owner_id":3,"contact_ids":[4521,4599]}' "https://app-api.atendeserver.com.br/v1/deals/310"