> For the complete documentation index, see [llms.txt](https://ajuda.livechat360.com.br/crm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.livechat360.com.br/crm/api-docs/negociacoes.md). # Negociacoes 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](broken://pages/ce52ec6009f8895759728a7831007561f04f026c) (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`. {% hint style="info" %} 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. {% endhint %} ## 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`). ```bash 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 ```json { "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"). {% hint style="warning" %} 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. {% endhint %} ```bash 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" ```