Pipeline (CRM)

Isolamento multi-tenant e segurança

Toda a API de Pipeline é escopada por conta. Você nunca consegue ler, alterar ou apagar dados de outra conta — nem por engano, nem de propósito. Entenda como o isolamento funciona antes de automatizar operações destrutivas.

Pipelines

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

[
  {
    "id": 1,
    "account_id": 1,
    "name": "Vendas B2B",
    "description": "Pipeline principal de vendas",
    "active": true,
    "stages": {
      "1_prospeccao": { "id": "1_prospeccao", "name": "Prospeccao", "color": "#3b82f6", "position": 0 },
      "1_proposta":   { "id": "1_proposta", "name": "Proposta", "color": "#f59e0b", "position": 1 },
      "1_ganho":      { "id": "1_ganho", "name": "Ganho", "color": "#10b981", "position": 2, "is_won_stage": true },
      "1_perdido":    { "id": "1_perdido", "name": "Perdido", "color": "#ef4444", "position": 3, "is_lost_stage": true }
    },
    "settings": { "require_won_value": false, "require_loss_reason": false },
    "inbox_id": null,
    "default_for_appointments": false,
    "created_at": "2025-06-01T00:00:00Z",
    "updated_at": "2025-06-01T00:00:00Z"
  }
]

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipelines/1/pipeline_cards?pipeline_stage=1_proposta&limit=50" \
  -H "api_access_token: YOUR_TOKEN" | jq .

Estágios do Pipeline

{
  "pipeline_id": 8143,
  "pipeline_name": "Clinica Medica - Jornada do Paciente",
  "stages": [
    {
      "id": "8143_entrada_de_lead",
      "name": "Entrada de Lead",
      "color": "#64748b",
      "icon": null,
      "position": 0,
      "description": "Entrada automática de leads via inbox",
      "is_entry_stage": true,
      "is_won_stage": false,
      "is_lost_stage": false
    },
    {
      "id": "8143_ganho",
      "name": "Ganho",
      "color": "#10b981",
      "position": 6,
      "is_entry_stage": false,
      "is_won_stage": true,
      "is_lost_stage": false
    }
  ]
}

Cards (Deals)

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

# Filtros avancados na rota legacy: prioridade alta, valor minimo, SLA vencido
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards?pipeline_id=1&priority[]=high&priority[]=urgent&value_min=5000&sla_exceeded=true" \
  -H "api_access_token: YOUR_TOKEN" | jq .

# Filtrar por labels, agente e intervalo de datas
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards?labels[]=vip&agent_id=5&date_start=2026-01-01&date_end=2026-06-30" \
  -H "api_access_token: YOUR_TOKEN" | jq .

# Cards sem responsavel
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards?agent_id=unassigned&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 .

{
  "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 },
      "active_sequence": { "id": 9, "name": "Onboarding", "status": "active", "current_step": 1, "total_steps": 3, "progress_percentage": 33 },
      "created_at": "2026-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "has_more": false,
    "next_cursor": null,
    "stage_counts": { "1_lead": 12, "1_qualificacao": 18, "1_ganho": 12 }
  }
}

Cards pela rota /pipeline/cards

O CRUD de cards existe em dois caminhos com controllers diferentes. Os campos aceitos na escrita são os mesmos (uma única lista compartilhada, envolta em pipeline_card), e os dois respeitam a visibilidade do usuário. O que muda é paginação, formato de resposta e tratamento de erro:

{
  "data": [ { "id": 5, "title": "Contrato Empresa XYZ", "pipeline_id": 1, "pipeline_stage": "1_proposta", "status": "open" } ],
  "meta": { "current_page": 1, "per_page": 25, "total_pages": 1, "total_count": 1 }
}

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_card": { "pipeline_id": 1, "pipeline_stage": "1_prospeccao", "title": "Novo lead", "contact_id": 10 } }'

Lixeira de Cards

Card excluído vai para a lixeira (discarded_at) e pode ser restaurado. Os três endpoints abaixo são restritos a administradores.

{
  "data": [
    {
      "id": 5,
      "title": "Contrato Empresa XYZ",
      "discarded_at": "2026-09-20T14:00:00Z",
      "discarded_by": { "id": 3, "name": "Administrador" },
      "discard_reason": "Duplicado",
      "days_until_permanent_deletion": 23
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total_pages": 1, "total_count": 1 }
}

Importar Cards (CSV)

Importe cards (deals) em lote a partir de um arquivo CSV. O processamento é assíncrono: a API valida e enfileira o import, e o job cria os cards em background. Ambos os endpoints exigem permissão de administrador.

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/template" \
  -H "api_access_token: YOUR_TOKEN" \
  -o pipeline_cards_import_template.csv

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/import" \
  -H "api_access_token: YOUR_TOKEN" \
  -F "import_file=@pipeline_cards.csv" \
  -F "pipeline_id=1"

{
  "message": "Importação iniciada. Os cards serão criados em segundo plano.",
  "import_id": 42
}

{ "error": "Pipeline obrigatorio para importar cards." }

Exportar Cards (CSV)

Exporta os cards da conta como um arquivo CSV, respeitando os mesmos filtros da listagem legacy /pipeline_cards. O resultado é escopado à conta autenticada (a visibilidade por pipeline do usuário também se aplica).

# Exportar cards abertos de um pipeline que correspondem a busca textual
curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/export?pipeline_id=1&status=open&search=Acme" \
  -H "api_access_token: YOUR_TOKEN" \
  -o pipeline_cards_export.csv

Contatos e Conversas adicionais (multi-vínculo)

Além do contato e da conversa primários do card (contact_id / conversation_display_id), um card pode ter contatos e conversas adicionais vinculados. Isso permite representar um deal com vários envolvidos (ex: decisor + influenciador) ou várias conversas relacionadas. Os vínculos primários não mudam — estes endpoints apenas adicionam/removem vínculos extras (join aditivo, many-to-many).

Novos campos no recurso do card

{
  "id": 5,
  "contact_id": 10,
  "conversation_display_id": 42,
  "additional_contacts": [
    {
      "id": 3,
      "contact_id": 27,
      "name": "Joao Comprador",
      "email": "joao@empresa.com",
      "phone_number": "+5511999999999",
      "avatar_url": "",
      "role": "decisor"
    }
  ],
  "additional_conversations": [
    { "id": 8, "conversation_display_id": 57 }
  ]
}

Contatos adicionais

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/contacts" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": 27, "role": "decisor" }'

{
  "data": {
    "id": 3,
    "contact_id": 27,
    "name": "Joao Comprador",
    "email": "joao@empresa.com",
    "phone_number": "+5511999999999",
    "avatar_url": "",
    "role": "decisor"
  }
}

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/contacts/3" \
  -H "api_access_token: YOUR_TOKEN"

Conversas adicionais

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/conversations" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "conversation_display_id": 57 }'

{
  "data": {
    "id": 8,
    "conversation_display_id": 57
  }
}

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/conversations/8" \
  -H "api_access_token: YOUR_TOKEN"

Mover Card entre Estágios

{
  "error": "This agent bot is not allowed to perform this action on pipeline cards",
  "reason": "action_not_allowed_for_bot",
  "allowed_actions": ["cards_move"]
}

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" }'

# Destino terminal: o fechamento acontece dentro da propria rota.
# Pegue o identificador real da etapa de Ganho em GET /pipelines/1/stages
# (o estagio com is_won_stage = true).
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": "<id da etapa de Ganho>", "won_value": 18000 }'

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline_cards/reorder" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": 1,
    "positions": [
      { "id": 5, "position": 0, "pipeline_stage": "1_qualificacao" },
      { "id": 9, "position": 1, "pipeline_stage": "1_qualificacao" }
    ]
  }'

Status do Deal

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/deal_status/mark_won" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "won_value": 15000,
        "won_note": "Fechado no plano anual",
        "pipeline_product_id": 7,
        "quantity": 2,
        "unit_value": 7500
      }'

Timeline do Card

{
  "timeline": [
    {
      "date": "2026-01-15",
      "activities": [
        {
          "id": 1780508401,
          "type": "history_event",
          "event_type": "stage_changed",
          "details": {
            "user": { "id": 5, "name": "Maria Santos", "avatar_url": "" },
            "old_stage": "1_prospeccao",
            "new_stage": "1_qualificacao"
          },
          "user": { "id": 5, "name": "Maria Santos", "avatar_url": "" },
          "created_at": "2026-01-15T14:30:00Z",
          "timestamp": "2026-01-15T14:30:00Z"
        }
      ]
    }
  ]
}

Anexos do Card

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

curl -OJ "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/5/attachments/31" \
  -H "api_access_token: YOUR_TOKEN"

Arquivos de notas

Arquivos anexados a uma nota do card são enviados à parte e depois referenciados pelo id na nota salva em item_details.notes[].attachments[]. Um arquivo enviado e nunca referenciado por uma nota é descartado automaticamente após cerca de 24 horas. Os dois endpoints exigem permissão de edição no card.

{
  "id": 88,
  "attachment_url": "https://chat.seudominio.com/rails/active_storage/...",
  "message": "Attachment uploaded successfully"
}

Sequências de Atividade no Card

Inscreve um card numa sequência de atividades (cadência automatizada de etapas, definida previamente em pipeline/activity_sequences). Sequências estão incluídas em toda licença NooviChat válida; o acesso depende das permissões do usuário e da configuração operacional da conta. Um card só pode ter uma sequência ativa/pausada da mesma definição por vez (422 em duplicidade).

{
  "data": [
    {
      "id": 14,
      "status": "active",
      "current_step": 1,
      "total_steps": 4,
      "progress_percentage": 25,
      "definition": { "id": 3, "name": "Cadência de prospeccao" },
      "next_step_at": "2026-06-15T12:00:00-03:00",
      "steps_log": [],
      "created_at": "2026-06-13T09:00:00-03:00",
      "updated_at": "2026-06-13T09:00:00-03:00"
    }
  ]
}

{
  "data": {
    "summary": {
      "2026-09-27": { "started": 4, "completed": 2, "failed": 0 },
      "2026-09-26": { "started": 3, "completed": 1, "failed": 1 }
    },
    "active_sequences_count": 12,
    "completed_today": 2,
    "avg_completion_days": 6.5,
    "top_definitions": [ { "id": 3, "name": "Onboarding", "starts": 18 } ]
  }
}

Operações em Lote

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/cards/bulk_assign" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "item_ids": [5, 9, 12], "owner_id": 3 }'

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/bulk_actions/delete" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "card_ids": [5, 9, 12], "reason": "Leads duplicados" }'

{ "success": true, "deleted": 3, "failed": 0, "failed_items": [] }

{ "success": true, "updated": 2, "updated_ids": [5, 9], "failed": 0, "failed_items": [] }

Automações do Pipeline

Crie workflows automatizados que executam ações quando cards mudam de estágio, atingem determinado score ou atendem condições específicas.

[
  {
    "id": 1,
    "name": "Notificar ao entrar em Negociação",
    "description": "Avisa o responsável quando um card chega na negociação",
    "active": true,
    "trigger_type": "event",
    "pipeline_id": 1,
    "trigger": { "event": "stage_change", "to_stage": "1_negociacao" },
    "conditions": [],
    "actions": [{ "type": "send_notification", "to": "owner" }],
    "flow": { "nodes": [], "connections": [], "viewport": { "x": 0, "y": 0, "zoom": 1 } },
    "stats": {
      "total_executions": 23,
      "success_count": 22,
      "failure_count": 1,
      "success_rate": 96
    }
  }
]

Contrato canônico do fluxo visual

O objeto flow usa nodes, connections e, opcionalmente, viewport. Cada node possui id, type, dados em data e pode incluir position. O objeto node.data é extensível: o backend preserva chaves e tipos JSON necessários para cada ação, remove tags HTML de strings e valida a estrutura executável. Por isso, a API não define um schema fechado de parâmetros para todas as ações.

{ "valid": true, "errors": [], "warnings": [] }

{
  "valid": false,
  "errors": ["Node trigger-1: conflicting values for pipeline_id, pipelineId"],
  "warnings": []
}

Executar e Testar

{
  "executions": [
    {
      "id": 901,
      "status": "failed",
      "trigger_event": "stage_change",
      "started_at": "2026-09-27T11:59:58Z",
      "completed_at": "2026-09-27T11:59:59Z",
      "execution_time_ms": 842,
      "nodes_executed": 3,
      "error_message": "...",
      "failed_node_id": "node_3",
      "failed_node_error": "...",
      "conversation_id": null,
      "contact_id": 10,
      "pipeline_item_id": null,
      "pipeline_card_id": 5,
      "logs": [],
      "created_at": "2026-09-27T11:59:58Z",
      "automation": { "id": 1, "name": "Notificar ao entrar em Negociação" }
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

Estatísticas de Automação

{
  "audit_logs": [
    {
      "id": 44,
      "action": "update",
      "resource_name": "Notificar ao entrar em Negociação",
      "description": "...",
      "changes": {},
      "user": { "id": 3, "name": "Administrador", "email": "admin@exemplo.com" },
      "created_at": "2026-09-27T10:00:00Z",
      "automation": { "id": 1, "name": "Notificar ao entrar em Negociação", "active": true }
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

{
  "automation_id": 1,
  "automation_name": "Notificar ao entrar em Negociação",
  "rate_limit": {
    "enabled": true,
    "automation": { "limit": 100, "used": 12, "remaining": 88 },
    "account": { "limit": 1000, "used": 140, "remaining": 860 },
    "window_seconds": 3600,
    "window_minutes": 60
  },
  "within_limit": true
}

{
  "account": { "limit": 1000, "used": 140, "remaining": 860, "window_minutes": 60 },
  "automations": [
    { "id": 1, "name": "Notificar ao entrar em Negociação", "limit": 100, "used": 12, "remaining": 88, "within_limit": true }
  ]
}

Gatilho por Webhook

Uma automação com gatilho de webhook recebe uma URL própria, com um token secreto no caminho. Qualquer sistema externo que faça um POST nessa URL dispara a automação. A URL não aparece na representação comum da automação (que traz apenas webhook_configured); ela é lida e rotacionada pelos dois endpoints abaixo, restritos a administradores. As respostas vêm com Cache-Control: no-store.

{
  "webhook_configured": true,
  "webhook_url": "https://chat.seudominio.com/api/v1/pipeline_automation_webhooks/<token>"
}

{ "webhook_configured": true, "webhook_url": "https://chat.seudominio.com/api/v1/pipeline_automation_webhooks/<novo_token>" }

Endpoint público de disparo

curl -X POST "https://chat.seudominio.com/api/v1/pipeline_automation_webhooks/<token>" \
  -H "Content-Type: application/json" \
  -d '{ "pedido": "1234", "valor": 490 }'

{ "accepted": true, "triggered_at": "2026-09-27T12:00:00Z" }

Templates de Automação

Modelos prontos de automação, comuns a todas as contas e somente leitura. Qualquer usuário autenticado pode consultá-los; criar uma automação a partir de um modelo exige administrador ou pipeline_manage.

{
  "templates": [
    {
      "id": 7,
      "name": "Boas-vindas ao novo lead",
      "description": "...",
      "category": "sales",
      "category_label": "Vendas",
      "icon": "...",
      "is_system": true,
      "is_featured": true,
      "usage_count": 42
    }
  ],
  "categories": ["general", "sales", "support", "marketing", "onboarding", "notifications", "integrations"]
}

{ "categories": [ { "id": "sales", "label": "Vendas", "count": 5 } ] }

Catálogo de Produtos

O que a conta vende. Cadastrado aqui, o produto fica selecionável ao fechar um card como ganho — e é esse vínculo que permite medir receita por produto. Ler o catálogo acompanha o acesso ao Pipeline; criar, editar e desativar exigem permissão de gestão.

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/products" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_product": { "name": "Consultoria de Implantacao", "sku": "CONS-IMPL", "default_value": 3000 } }'

curl "https://chat.seudominio.com/api/v1/accounts/1/pipeline/products/performance?won_start=2026-07-01&won_end=2026-07-31" \
  -H "api_access_token: YOUR_TOKEN"

Razão de Vendas do Card

Cada venda de um card é um lançamento. O razão é append-only: correção se faz por estorno, nunca apagando a linha — e por isso o histórico consegue distinguir uma correção de um sumiço.

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-27", "time_zone": "America/Sao_Paulo" },
  "totals_by_currency": [
    { "currency": "BRL", "revenue": "48000.0", "sales_count": 12, "average_ticket": "4000.0", "items_sold": "15.0" }
  ],
  "voided_by_currency": [],
  "by_pipeline": [ { "pipeline_id": 1, "pipeline_name": "Vendas B2B", "currency": "BRL", "revenue": "48000.0", "sales_count": 12 } ],
  "by_seller": [ { "user_id": 3, "user_name": "Vendedor", "currency": "BRL", "revenue": "30000.0", "sales_count": 7 } ],
  "by_source": [ { "source": "manual", "sales_count": 12 } ],
  "timeline": [ { "date": "2026-09-02", "currency": "BRL", "sales_count": 2, "revenue": "8000.0" } ],
  "repeat": { "first_cycle_sales": 10, "repeat_sales": 2 }
}

Webhooks do Pipeline

Receba eventos do Pipeline em tempo real numa URL externa. Gerenciar webhooks requer permissão de administrador.

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/pipeline/webhooks" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_webhook": {
      "name": "Integracao CRM",
      "url": "https://example.com/hooks/pipeline",
      "events": ["pipeline_card_won", "pipeline_card_lost"]
    }
  }'

{ "id": 71, "name": "Integracao CRM", "url": "https://example.com/hooks/pipeline", "pipeline_id": null, "pipeline_name": null, "events": ["pipeline_card_won", "pipeline_card_lost"], "active": true, "secret": "<64 hex>" }

Eventos disponíveis

Oito eventos:

• pipeline_card_created — card criado
• pipeline_card_updated — card atualizado
• pipeline_card_deleted — card removido (soft delete)
• pipeline_card_stage_changed — mudou de estágio (inclui from_stage/to_stage)
• pipeline_card_won — marcado como ganho; won_at fica em data.card e pre_won_stage em data.card.item_details
• pipeline_card_lost — marcado como perdido; lost_reason fica em data.card e pre_lost_stage em data.card.item_details
• pipeline_card_owner_changed — responsável alterado
• pipeline_card_sla_exceeded — o card passou do prazo na etapa. Único evento que nasce de um relógio, não de uma ação: é justamente o que acontece sem ninguém olhando. Além do card, o payload traz sla_hours (o prazo da etapa), seconds_in_stage (o tempo já gasto) e stage — só "estourou" não distingue um minuto de atraso de uma semana parada.

Formato do payload

{
  "event": "pipeline_card_won",
  "timestamp": "2026-06-03T23:21:38Z",
  "data": {
    "card": {
      "id": 12473,
      "pipeline_id": 8143,
      "pipeline_stage": "8143_ganho",
      "won_at": "...",
      "contact_id": 21,
      "item_details": { "pre_won_stage": "8143_negociacao" }
    }
  }
}

import crypto from "crypto";
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-pipeline-webhook-signature"]));