API de Negócios

Um negócio é uma oportunidade de venda no seu quadro de Pipeline de Vendas — 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)
Erros e paginação — veja Erros e Paginação

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

{
  "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 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

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

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

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)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Obter um negócio

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Resposta (200)

{ "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.

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)

{ "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.

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.

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.

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.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Resposta (200):

{
  "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").

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 — como funcionam os estágios, tags de estágio, vários pipelines e o quadro.
API de Tarefas — as tarefas podem ser vinculadas a um negócio com deal_id.
Automações — as etapas Encontrar negócios e Encontrar negócio leem os mesmos dados dentro de um fluxo de trabalho.

API de Negócios #

O objeto de negócio #

Listar negócios #

Obter um negócio #

Criar um negócio #

Atualizar um negócio #

Mover um negócio para outra etapa #

Excluir um negócio #

Pipelines #

Listar pipelines #

Criar um pipeline #

Atualizar um pipeline #

Excluir um pipeline #

Próximos passos #