Pipeline (CRM)

Gerencie pipelines de vendas completos com estagios customizaveis, cards (deals), automacoes de workflow e lead scoring integrado.

Base URL

Todos os endpoints usam o prefixo /api/v1/accounts/{account_id}

Pipelines

GET/api/v1/accounts/{account_id}/pipelines

Lista todos os pipelines da conta.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipelines" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de pipelines

json

{
  "data": [
    {
      "id": 1,
      "name": "Vendas B2B",
      "description": "Pipeline principal de vendas",
      "stages": [
        { "id": 1, "name": "Prospeccao", "position": 0 },
        { "id": 2, "name": "Qualificacao", "position": 1 },
        { "id": 3, "name": "Proposta", "position": 2 },
        { "id": 4, "name": "Negociacao", "position": 3 },
        { "id": 5, "name": "Fechamento", "position": 4 }
      ],
      "cards_count": 42,
      "created_at": "2025-06-01T00:00:00Z"
    }
  ]
}

POST/api/v1/accounts/{account_id}/pipelines

Cria um novo pipeline com estagios.

stages e obrigatorio

O campo stages e obrigatorio e deve ser um objeto (hash), nao um array. Envie pelo menos um estagio ou a API retorna 422. Use sempre Content-Type: application/json.

Body

Nome	Tipo	Obrigatorio	Descricao
`pipeline.name`	`string`	Sim	Nome do pipeline
`pipeline.description`	`string`	Nao	Descricao
`pipeline.stages`	`object`	Sim	Objeto com estagios. Chaves sao IDs temporarios (string). Apos criacao os IDs sao normalizados para {pipeline_id}_{slug}
`pipeline.stages.{key}.name`	`string`	Sim	Nome do estagio
`pipeline.stages.{key}.color`	`string`	Nao	Cor em hex (ex: "#3B82F6")
`pipeline.stages.{key}.position`	`integer`	Nao	Ordem de exibicao (1 = primeiro)

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipelines" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "name": "Vendas B2B",
      "stages": {
        "stage_1": { "name": "Prospeccao", "color": "#6366f1", "position": 1 },
        "stage_2": { "name": "Qualificacao", "color": "#3B82F6", "position": 2 },
        "stage_3": { "name": "Proposta", "color": "#f59e0b", "position": 3 },
        "stage_4": { "name": "Fechamento", "color": "#10b981", "position": 4 }
      }
    }
  }'

IDs dos estagios apos criacao

Apos criar o pipeline, os IDs dos estagios sao normalizados pelo servidor para o formato {pipeline_id}_{slug_do_nome} (ex: 1_prospeccao). Use GET /pipelines/{id}/stages para obter os IDs reais antes de criar cards.

PATCH/api/v1/accounts/{account_id}/pipelines/{id}

Atualiza nome, descricao, estagios ou settings de um pipeline.

ATENCAO: formato do campo stages

Sempre envie stages como objeto (hash) com IDs reais como chaves, nao como array. Array com cada item contendo id tambem e aceito (desde v4.13.0.34), mas array sem id em cada item e rejeitado com 422 e os cards nao sao alterados (defesa contra payloads mal-formatados que poderiam mover todos os cards para a primeira stage nao-terminal).

A rota PATCH /pipelines/{id}/stages/{stage_id} nao existe e retorna 404. Para editar uma stage individual (descricao, cor, nome, posicao), envie PATCH /pipelines/{id} com o hashstagescompleto — o backend faz diff inteligente.

Body

Nome	Tipo	Obrigatorio	Descricao
`pipeline.name`	`string`	Nao	Nome do pipeline
`pipeline.description`	`string`	Nao	Descricao
`pipeline.active`	`boolean`	Nao	Status de ativacao
`pipeline.stages`	`object`	Nao	Hash com stages keyed por ID real (ex: "1_qualificado"). Array tambem aceito desde que cada item tenha campo id.
`pipeline.settings`	`object`	Nao	Configuracoes do pipeline (JSONB). Chaves desconhecidas sao descartadas.

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/pipelines/36" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "stages": {
        "36_qualificado": {
          "name": "Qualificado",
          "position": 1,
          "description": "Lead qualificado para proxima etapa",
          "color": "#10b981"
        },
        "36_entrada_de_lead": { "name": "Entrada de Lead", "position": 0 }
      }
    }
  }'

Comportamento ao remover stages

Quando uma stage existente e omitida do payload, ela e considerada removida e os cards que estavam nela sao automaticamente movidos para a primeira stage nao-terminal por ordem de position. Cada movimento e registrado em pipeline_stage_histories.

Limites: maximo de 50 stages por pipeline; settings JSON ate 64 KB.

DELETE/api/v1/accounts/{account_id}/pipelines/{id}

Remove um pipeline e todos os cards associados.

Acao Irreversivel

Remove permanentemente o pipeline, estagios e todos os cards associados.

Estagios do Pipeline

GET/api/v1/accounts/{account_id}/pipelines/{pipeline_id}/stages

Lista todos os estagios de um pipeline com contagem de cards.

200Lista de estagios

json

{
  "data": [
    {
      "id": 1,
      "name": "Prospeccao",
      "position": 0,
      "cards_count": 15,
      "total_value": 45000.00
    },
    {
      "id": 2,
      "name": "Qualificacao",
      "position": 1,
      "cards_count": 8,
      "total_value": 120000.00
    }
  ]
}

Cards (Deals)

Cards representam oportunidades de venda (deals) dentro de um pipeline. Cada card possui valor, contato associado, estagio atual e lead score.

GET/api/v1/accounts/{account_id}/pipeline_cards

Lista cards do kanban com filtros. Existem duas rotas equivalentes: /pipeline_cards (legacy) e /pipeline/cards (canonico). A canonica aceita mais filtros.

Duas rotas, filtros distintos (v4.12.3.0+)

/api/v1/accounts/{id}/pipeline_cards (legacy, paginacao por limit/offset): aceita pipeline_id, conversation_display_id, contact_id, limit, offset. Usado pelo kanban frontend.

/api/v1/accounts/{id}/pipeline/cards (canonica, paginacao por page/per_page): aceita pipeline_id, pipeline_stage (string), owner_id, contact_id, status (open/won/lost), lead_score_category (hot/warm/cold).

Importante: o filtro contact_id foi implementado na v4.12.3.0. Antes dessa versao, ele era silenciosamente ignorado e retornava todos os cards da conta. Se voce tem automacoes que dependem desse filtro, confirme que esta rodando v4.12.3.0 ou superior.

Parametros (rota legacy /pipeline_cards)

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Nao	Filtrar por pipeline (todos os cards desse funnel)
`conversation_display_id`(query)	`integer`	Nao	Filtrar por conversa associada (display_id, nao ID global)
`contact_id`(query)	`integer`	Nao	Filtrar por contato (v4.12.3.0+)
`limit`(query)	`integer`	Nao	Itens por pagina (default 50, max 2000)
`offset`(query)	`integer`	Nao	Offset para paginacao(default: `0`)

Parametros (rota canonica /pipeline/cards)

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Nao	Filtrar por pipeline
`pipeline_stage`(query)	`string`	Nao	Filtrar por estagio (ex: "69_lead")
`owner_id`(query)	`integer`	Nao	Filtrar por responsavel
`contact_id`(query)	`integer`	Nao	Filtrar por contato (v4.12.3.0+)
`status`(query)	`string`	Nao	open, won, lost
`lead_score_category`(query)	`string`	Nao	hot, warm, cold
`page`(query)	`integer`	Nao	Pagina atual(default: `1`)
`per_page`(query)	`integer`	Nao	Itens por pagina(default: `25`)

bash

# Filtrar por contato (v4.12.3.0+) — ambas rotas funcionam
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards?contact_id=42&pipeline_id=1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

# Canonica com status
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards?status=open&pipeline_id=1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de cards (legacy /pipeline_cards)

json

{
  "data": [
    {
      "id": 1,
      "title": "Contrato Empresa XYZ",
      "pipeline_id": 1,
      "pipeline_stage": "1_qualificacao",
      "position": 1,
      "status": "open",
      "contact_id": 10,
      "owner_id": 5,
      "lead_score": 78,
      "conversation_display_id": 42,
      "item_details": { "value": 15000.00 },
      "created_at": "2026-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "has_more": false,
    "stage_counts": { "1_lead": 12, "1_qualificacao": 18, "1_ganho": 12 }
  }
}

POST/api/v1/accounts/{account_id}/pipeline_cards

Cria um novo card (deal) no pipeline.

Como obter o pipeline_stage

O campo pipeline_stage e uma string no formato {pipeline_id}_{slug} (ex: "1_prospeccao"). Use GET /pipelines/{id}/stages para listar os IDs reais dos estagios do seu pipeline antes de criar cards.

Body

Nome	Tipo	Obrigatorio	Descricao
`title`	`string`	Sim	Titulo do deal
`pipeline_id`	`integer`	Sim	ID do pipeline
`pipeline_stage`	`string`	Sim	ID do estagio no formato "{pipeline_id}_{slug}" (ex: "1_prospeccao"). Obtenha via GET /pipelines/{id}/stages
`contact_id`	`integer`	Nao	ID do contato associado
`conversation_display_id`	`integer`	Nao	Display ID da conversa associada
`owner_id`	`integer`	Nao	ID do responsavel
`item_details.title`	`string`	Nao	Titulo customizado do card
`item_details.value`	`number`	Nao	Valor do deal
`item_details.currency`	`string`	Nao	Moeda (ex: "BRL")
`deadline`	`string`	Nao	Data prevista de fechamento (ISO 8601)
`custom_attributes`	`object`	Nao	Atributos personalizados

# Primeiro obtenha os IDs dos estagios:
# curl -s ".../api/v1/accounts/1/pipelines/1/stages" -H "api_access_token: TOKEN"

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": 1,
    "pipeline_stage": "1_prospeccao",
    "contact_id": 10,
    "owner_id": 5,
    "item_details": {
      "title": "Contrato Empresa XYZ",
      "value": 15000.00,
      "currency": "BRL"
    },
    "deadline": "2026-03-15T00:00:00Z"
  }'

GET/api/v1/accounts/{account_id}/pipeline_cards/{id}

Retorna detalhes completos de um card incluindo timeline e score.

PATCH/api/v1/accounts/{account_id}/pipeline_cards/{id}

Atualiza dados de um card.

Body

Nome	Tipo	Obrigatorio	Descricao
`title`	`string`	Nao	Titulo
`value`	`number`	Nao	Valor
`owner_id`	`integer`	Nao	Responsavel
`expected_close_date`	`string`	Nao	Data prevista
`custom_attributes`	`object`	Nao	Atributos

DELETE/api/v1/accounts/{account_id}/pipeline_cards/{id}

Remove um card (soft delete). Pode ser restaurado via GDPR endpoints.

Mover Card entre Estagios

POST/api/v1/accounts/{account_id}/pipeline_cards/{id}/move_to_stage

Move um card para outro estagio do pipeline.

Body

Nome	Tipo	Obrigatorio	Descricao
`pipeline_stage`	`string`	Sim	Identificador do estagio destino no formato "{pipeline_id}_{stage_slug}" (ex: "2_qualificao"). Use GET /pipelines/{id}/stages para obter os identificadores disponiveis.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/5/move_to_stage" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_stage": "1_qualificacao" }'

POST/api/v1/accounts/{account_id}/pipeline_cards/reorder

Reordena cards dentro de um estagio.

Body

Nome	Tipo	Obrigatorio	Descricao
`card_ids`	`array`	Sim	Array de IDs na nova ordem

Status do Deal

POST/api/v1/accounts/{account_id}/pipeline/cards/{id}/deal_status/mark_won

Marca o deal como ganho.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/deal_status/mark_won" \
  -H "api_access_token: YOUR_TOKEN"

POST/api/v1/accounts/{account_id}/pipeline/cards/{id}/deal_status/mark_lost

Marca o deal como perdido.

Body

Nome	Tipo	Obrigatorio	Descricao
`lost_reason`	`string`	Nao	Motivo da perda

POST/api/v1/accounts/{account_id}/pipeline/cards/{id}/deal_status/reopen

Reabre um deal marcado como ganho ou perdido.

Timeline do Card

GET/api/v1/accounts/{account_id}/pipeline/cards/{id}/timeline

Retorna a timeline de atividades do card.

200Timeline de eventos

json

{
  "data": [
    {
      "type": "stage_change",
      "from_stage": "Prospeccao",
      "to_stage": "Qualificacao",
      "performed_by": "Maria Santos",
      "created_at": "2026-01-15T14:30:00Z"
    },
    {
      "type": "note_added",
      "content": "Cliente demonstrou interesse no plano enterprise",
      "performed_by": "Joao Silva",
      "created_at": "2026-01-14T10:00:00Z"
    }
  ]
}

Anexos do Card

GET/api/v1/accounts/{account_id}/pipeline/cards/{card_id}/attachments

Lista anexos de um card.

POST/api/v1/accounts/{account_id}/pipeline/cards/{card_id}/attachments

Adiciona um anexo ao card.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/attachments" \
  -H "api_access_token: YOUR_TOKEN" \
  -F "file=@/path/to/proposta.pdf"

DELETE/api/v1/accounts/{account_id}/pipeline/cards/{card_id}/attachments/{id}

Remove um anexo.

Operacoes em Lote

Em Desenvolvimento

O endpoint de bulk_assign esta em desenvolvimento e pode nao estar disponivel em todas as instalacoes.

POST/api/v1/accounts/{account_id}/pipeline/cards/bulk_assign

Atribui responsavel para varios cards de uma vez.

Body

Nome	Tipo	Obrigatorio	Descricao
`card_ids`	`array`	Sim	IDs dos cards
`owner_id`	`integer`	Sim	ID do novo responsavel

PATCH/api/v1/accounts/{account_id}/pipeline/cards/{id}/assign

Atribui um responsavel a um card especifico.

Body

Nome	Tipo	Obrigatorio	Descricao
`owner_id`	`integer`	Sim	ID do responsavel

Automacoes do Pipeline

Crie workflows automatizados que executam acoes quando cards mudam de estagio, atingem determinado score ou atendem condicoes especificas.

GET/api/v1/accounts/{account_id}/pipeline/automations

Lista todas as automacoes do pipeline.

200Lista de automacoes

json

{
  "data": [
    {
      "id": 1,
      "name": "Notificar ao entrar em Negociacao",
      "trigger": "stage_change",
      "conditions": { "to_stage": "Negociacao" },
      "actions": [{ "type": "send_notification", "to": "owner" }],
      "is_active": true,
      "executions_count": 23
    }
  ]
}

POST/api/v1/accounts/{account_id}/pipeline/automations

Cria uma nova automacao.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome da automacao
`trigger`	`string`	Sim	stage_change, card_created, score_threshold, etc.
`conditions`	`object`	Nao	Condicoes para acionar
`actions`	`array`	Sim	Acoes a executar

PATCH/api/v1/accounts/{account_id}/pipeline/automations/{id}

Atualiza uma automacao.

DELETE/api/v1/accounts/{account_id}/pipeline/automations/{id}

Remove uma automacao.

POST/api/v1/accounts/{account_id}/pipeline/automations/{id}/duplicate

Clona uma automacao existente.

Executar e Testar

POST/api/v1/accounts/{account_id}/pipeline/automations/{id}/execute

Executa manualmente uma automacao.

POST/api/v1/accounts/{account_id}/pipeline/automations/{id}/dry_run

Executa simulacao sem efeito real (teste).

Dry Run

Permite testar a automacao sem executar as acoes reais. Retorna o resultado esperado.

POST/api/v1/accounts/{account_id}/pipeline/automations/{id}/validate

Valida a configuracao da automacao.

GET/api/v1/accounts/{account_id}/pipeline/automations/{id}/executions

Historico de execucoes da automacao.

Estatisticas de Automacao

GET/api/v1/accounts/{account_id}/pipeline/automations/{id}/stats

Metricas de uma automacao especifica.

GET/api/v1/accounts/{account_id}/pipeline/automations/dashboard

Dashboard de todas as automacoes.

GET/api/v1/accounts/{account_id}/pipeline/automations/{id}/audit_logs

Logs de auditoria da automacao.