Oportunidades (deals)

O recurso deals expõe as oportunidades do funil de vendas, os cartões que você vê no CRM, com cliente, etapa atual, valor estimado, responsável e datas de entrada na etapa e de fechamento. A sub-rota /v1/deals/stages descreve as etapas do funil da sua conta.

Acesso


Módulo	`crm_funil`
Escopos	`deals:read` (ou `:read`, ou `:write`)
Operações	somente leitura

Sem o módulo no contrato, a resposta é 403 module_not_enabled. Sem o escopo na chave, é 403 insufficient_scope. O mesmo escopo cobre as oportunidades e as etapas.

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/deals`	Lista oportunidades, com paginação por cursor
`GET`	`/v1/deals/stages`	Lista as etapas do funil
`GET`	`/v1/deals/{id}`	Retorna uma oportunidade pelo `id`

A listagem de oportunidades usa o envelope padrão com data, pagination e meta, e aceita limit (1 a 100, padrão 20), cursor, sort e fields. Veja Paginação, filtros e ordenação.

Etapas do funil

GET /v1/deals/stages responde com o envelope de item: data é o vetor de etapas, sem pagination. A resposta traz até 100 etapas ordenadas por position crescente, e não aceita limit, cursor, sort, fields nem filtros.

curl "$LIGGA_BASE/v1/deals/stages" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "6f1b2a3c-5d4e-4f3a-9b2c-1a0d9e8f7c6b",
      "name": "Primeiro contato",
      "color": "#4899C1",
      "position": 1,
      "milestone": null,
      "is_active": true
    },
    {
      "id": "0c9b8a7d-6e5f-4a3b-8c1d-0e9f8a7b6c5d",
      "name": "Proposta enviada",
      "color": "#14D484",
      "position": 2,
      "milestone": null,
      "is_active": true
    }
  ],
  "meta": { "request_id": "req_01J9ZQ8V2K5M7N9P0R1S2T3U4V" }
}

Campos

`Deal`

Campo	Tipo	Descrição
`id`	`uuid`	Identificador da oportunidade
`customer_id`	`uuid`	Cliente associado, do recurso `customers`
`stage_id`	`uuid`	Etapa atual do funil, de `/v1/deals/stages`
`status`	`string`	Situação da oportunidade, por exemplo `open`, `won`, `lost`
`origin_channel`	`string`	Canal de origem, por exemplo `whatsapp`, `instagram`, `indicacao`
`estimated_value`	`number \| null`	Valor estimado da oportunidade
`assigned_to_user_id`	`uuid \| null`	Usuário responsável
`lost_reason`	`string \| null`	Motivo da perda, quando `status` é `lost`
`quote_transaction_id`	`uuid \| null`	Transação de orçamento vinculada
`won_transaction_id`	`uuid \| null`	Transação gerada ao ganhar a oportunidade
`entered_stage_at`	`timestamp (ISO 8601)`	Quando a oportunidade entrou na etapa atual
`closed_at`	`timestamp (ISO 8601) \| null`	Quando a oportunidade foi fechada, ganha ou perdida
`created_at`	`timestamp (ISO 8601)`	Criação do registro
`updated_at`	`timestamp (ISO 8601)`	Última atualização

`DealStage`

Campo	Tipo	Descrição
`id`	`uuid`	Identificador da etapa, o valor usado em `stage_id`
`name`	`string`	Nome da etapa, por exemplo `Primeiro contato`
`color`	`string \| null`	Cor da etapa no quadro do CRM, em hexadecimal
`position`	`integer`	Ordem da etapa no funil, crescente
`milestone`	`string \| null`	Marco da etapa, por exemplo `won` ou `lost`, quando houver
`is_active`	`boolean \| null`	Se a etapa está ativa no funil

Filtros e ordenação

Os filtros valem para GET /v1/deals.

Campo	Operadores	Exemplo
`status`	`eq`, `in`	`filter[status][eq]=open`
`stage_id`	`eq`	`filter[stage_id][eq]=6f1b2a3c-5d4e-4f3a-9b2c-1a0d9e8f7c6b`
`customer_id`	`eq`	`filter[customer_id][eq]=9c8d7e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f`

Filtros combinam com AND. A ordenação padrão é -created_at; sort também aceita created_at, updated_at, entered_stage_at e closed_at, com - na frente para ordem decrescente. Para ver o funil na ordem em que as oportunidades chegaram à etapa atual, use sort=-entered_stage_at.

Exemplos

Listar

curl "$LIGGA_BASE/v1/deals?filter[status][eq]=open&limit=2&sort=-created_at" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "3f9a1b7e-2c4d-4e8f-b6a1-5d0c9e8f7a2b",
      "customer_id": "9c8d7e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "stage_id": "6f1b2a3c-5d4e-4f3a-9b2c-1a0d9e8f7c6b",
      "status": "open",
      "origin_channel": "whatsapp",
      "estimated_value": 1890.5,
      "assigned_to_user_id": "b4a3c2d1-e0f9-4a8b-9c7d-6e5f4a3b2c1d",
      "lost_reason": null,
      "quote_transaction_id": "7e6d5c4b-3a2b-4c1d-8e9f-0f1e2d3c4b5a",
      "won_transaction_id": null,
      "entered_stage_at": "2026-07-08T14:22:10.000Z",
      "closed_at": null,
      "created_at": "2026-07-01T09:15:00.000Z",
      "updated_at": "2026-07-08T14:22:10.000Z"
    },
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "customer_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
      "stage_id": "0c9b8a7d-6e5f-4a3b-8c1d-0e9f8a7b6c5d",
      "status": "open",
      "origin_channel": "indicacao",
      "estimated_value": null,
      "assigned_to_user_id": null,
      "lost_reason": null,
      "quote_transaction_id": null,
      "won_transaction_id": null,
      "entered_stage_at": "2026-06-28T11:05:44.000Z",
      "closed_at": null,
      "created_at": "2026-06-28T11:05:44.000Z",
      "updated_at": "2026-06-28T11:05:44.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImExYjJjM2Q0LWU1ZjYtNGE3Yi04YzlkLTBlMWYyYTNiNGM1ZCIsInYiOiIyMDI2LTA2LTI4VDExOjA1OjQ0LjAwMFoifQ",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01J9ZQ8V2K5M7N9P0R1S2T3U4V" }
}

Para a próxima página, repita a chamada com cursor=<pagination.next_cursor> enquanto has_more for true.

Buscar por id

curl "$LIGGA_BASE/v1/deals/3f9a1b7e-2c4d-4e8f-b6a1-5d0c9e8f7a2b?fields=id,status,stage_id,estimated_value" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "3f9a1b7e-2c4d-4e8f-b6a1-5d0c9e8f7a2b",
    "status": "open",
    "stage_id": "6f1b2a3c-5d4e-4f3a-9b2c-1a0d9e8f7c6b",
    "estimated_value": 1890.5
  },
  "meta": { "request_id": "req_01J9ZQ8V2K5M7N9P0R1S2T3U4V" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`insufficient_scope`	Chave sem `deals:read`
403	`module_not_enabled`	Módulo `crm_funil` fora do contrato
404	`not_found`	`id` inexistente ou de outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Veja também

Paginação, filtros e ordenação — limit, cursor, sort e fields
Módulos e escopos — o que o módulo crm_funil libera
Clientes (customers) — o cliente em customer_id
Erros — o corpo de erro completo