# API de Negócios Um negócio é uma oportunidade de venda no seu quadro de [Pipeline de Vendas](../deals/sales-pipeline.md) — um título, um valor, a etapa em que se encontra e, opcionalmente, o contato ao qual pertence e o membro da equipe a quem está atribuído. Este guia aborda a leitura e o gerenciamento de negócios por meio da API. - **URL Base** — `https://api.youraiconnector.com/v1` - **Autenticação** — sua chave de API (veja [Autenticação](authentication.md)) - **Erros e paginação** — veja [Erros e Paginação](errors-and-pagination.md) Todos os exemplos abaixo mostram a forma de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — ambos funcionam em todos os endpoints. --- ## O objeto de negócio ```json { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "description": "Asked for pricing on the annual plan.", "company": "Jane's Clinic", "notes": "Prefers a call after 5pm.", "stage": "stage-2", "pipeline_id": "default", "value": 4800, "probability": 60, "priority": "high", "status": "open", "source": "whatsapp", "position": 0, "contact_id": "ctc_9f8e7d", "assigned_to": "usr_4a2b", "tags": ["clinic"], "close_date": "2026-10-01T00:00:00.000Z", "created_at": "2026-09-05T09:12:00.000Z", "updated_at": "2026-09-05T09:40:00.000Z", "stage_entered_at": "2026-09-05T09:40:00.000Z" } ``` `stage` é o id de um dos estágios do seu pipeline — leia-os com `GET /pipelines` (veja [Pipelines](#pipelines) abaixo). Os ids de estágio são únicos em todos os seus pipelines, portanto `pipeline_id` é derivado do estágio e é somente leitura: `default` é o seu pipeline principal, e ele é `null` quando o estágio não existe mais. Os carimbos de data/hora estão no formato ISO 8601. Um negócio armazena apenas os campos mostrados acima. Quando você cria ou atualiza um, qualquer outro campo é recusado com um `400` que o nomeia, portanto, nada do que você envia é perdido silenciosamente. Mantenha dados extras nos campos personalizados do contato vinculado. --- ## Listar negócios `GET /deals` — retorna os negócios em sua conta, do mais recente para o mais antigo. **Parâmetros de consulta** (todos opcionais): `stage` (um id de estágio), `pipeline_id` (apenas os negócios naquele pipeline), `contact_id`, `limit` (padrão 50, máx 200), `cursor` (da `next_cursor` da página anterior). **cURL** ```bash curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const { deals, next_cursor } = await res.json(); ``` **Python** ```python res = requests.get( "https://api.youraiconnector.com/v1/deals", headers={"X-API-Key": "YOUR_API_KEY"}, params={"stage": "stage-2", "limit": 50}, ) deals = res.json()["deals"] ``` **Resposta** (`200`) ```json { "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null } ``` --- ## Obter um negócio `GET /deals/{dealId}` ```bash curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Resposta** (`200`) ```json { "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } } ``` Um negócio que não existe, ou que pertence a outra conta, retorna `404`. --- ## Criar um negócio `POST /deals` — `title` e `stage` são obrigatórios; `stage` deve ser um dos ids de etapa do seu pipeline. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }' ``` **Resposta** (`201`) ```json { "success": true, "deal_id": "deal_abc123" } ``` --- ## Atualizar um negócio `PUT /deals/{dealId}` — envie apenas os campos que deseja alterar (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` deve ser um número. ```bash curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": 5200, "priority": "high" }' ``` **Resposta** (`200`): `{ "success": true, "deal_id": "deal_abc123" }` --- ## Mover um negócio para outra etapa `POST /deals/{dealId}/move` — corpo `{ "new_stage_id": "stage-3", "new_position": 0 }`. A posição `0` coloca o cartão no topo da coluna. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "new_stage_id": "stage-3", "new_position": 0 }' ``` **Resposta** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }` --- ## Excluir um negócio `DELETE /deals/{dealId}` — remove o negócio. **Isso não pode ser desfeito.** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Resposta** (`200`): `{ "success": true }` --- ## Pipelines Cada conta possui um pipeline principal (`id: "default"`); você pode adicionar até nove adicionais, cada um com seus próprios estágios. Os ids de estágio e as tags de gatilho devem ser únicos em todos os pipelines da conta, e cada pipeline pode marcar um estágio como seu `won` e um como seu resultado `lost`. ### Listar pipelines `GET /pipelines` — todos os pipelines, com o principal primeiro, cada um com seus estágios ordenados por posição. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Resposta** (`200`): ```json { "success": true, "data": { "pipelines": [ { "id": "default", "name": "Sales", "position": 0, "is_default": true, "settings": { "sync_stage_tags": false }, "stages": [ { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null }, { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" } ] } ] } } ``` ### Criar um pipeline `POST /pipelines` — corpo `{ "id"?, "name", "stages"?, "settings"? }`. Deixe `id` vazio para que um seja gerado. Cada estágio utiliza os mesmos campos da caixa de diálogo Estágios: `id`, `name`, `color`, `position`, `trigger_tag` opcional (um caminho de tag, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (um estágio do mesmo pipeline) e `outcome` (`"won"` ou `"lost"`). ```bash curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "reviews", "name": "Review requests", "stages": [ { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 }, { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" } ] }' ``` **Resposta** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Um id de estágio ou tag de gatilho já utilizado por outro pipeline é um `400` nomeando esse pipeline; um id que já existe é um `409`. ### Atualizar um pipeline `PUT /pipelines/{pipelineId}` — corpo `{ "name"?, "stages"?, "settings"? }`. `stages` substitui toda a lista, como na caixa de diálogo Estágios. Use `default` para o pipeline principal. O id do pipeline em si não pode ser alterado. ### Excluir um pipeline `DELETE /pipelines/{pipelineId}` — remove um pipeline adicional (o principal não pode ser excluído). Se ainda houver negócios em seus estágios, a chamada responde `409` com `deal_count`; adicione `?delete_deals=true` para excluir esses negócios junto com o pipeline. **Isso não pode ser desfeito.** **Resposta** (`204`). --- ## Próximos passos - [Pipeline de Vendas](../deals/sales-pipeline.md) — como funcionam os estágios, tags de estágio, vários pipelines e o quadro. - [API de Tarefas](tasks.md) — as tarefas podem ser vinculadas a um negócio com `deal_id`. - [Automações](../automations/automations.md) — as etapas **Encontrar negócios** e **Encontrar negócio** leem os mesmos dados dentro de um fluxo de trabalho.