> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Leads

> Leia, crie, atualize e mova leads pelo funil de cada empresa — por ID, nunca pelo nome da etapa.

> [!TIP]
>
> Teste requisições assinadas no navegador no [API Sandbox](https://play2sellsa.github.io/api-sandbox/): cole a chave e o segredo, e o playground assina sozinho.

> [!NOTE]
>
> Os exemplos mostram o cabeçalho `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE` como vai na rede. Para calcular a assinatura no seu código, use o `signedRequest` de [Autenticação](https://docs.play2sell.com/pt/api/authentication.md).

A API de Leads deixa o seu sistema trabalhar com os leads da empresa da chave: listar e ler, criar e atualizar, mover pelo funil, marcar ganho ou perdido, arquivar e registrar notas e atividades. Manter dois sistemas sincronizados está passo a passo em [Sincronização nos dois sentidos](https://docs.play2sell.com/pt/api/integrations/leads-sync.md).

## Antes de começar

* **Um endpoint, uma ação por chamada.** Toda chamada é um `POST` para `https://api.play2sell.com/functions/v1/default-integration` com `"action"` no corpo. Filtros também vão no corpo, porque a assinatura cobre o corpo e não a query string (veja [Convenções](https://docs.play2sell.com/pt/api/conventions.md)).
* **Escopos.** Ler exige `leads:read`; gravar exige `leads:write`. Um não inclui o outro, e nenhum dos dois abre `sync_collaborators` ou `sync_activities`. Chave sem o escopo recebe `403` com `code: "scope_insufficient"`. As chaves são criadas em **Admin > Integrações > Chaves de API**.
* **Cada empresa tem o próprio funil.** Nomes e ordem das etapas são configurados por empresa e podem mudar a qualquer momento. Use sempre o **ID da etapa** que vem de [`list_pipelines`](#acao-list_pipelines) e leia **ganho/perdido em `stage.outcome`** (`open`, `won`, `lost`), nunca no nome.
* **Pontos ficam com Missões.** O que muda por esta API atualiza o lead, a etapa e o histórico, mas **não pontua** em missões nem campanhas. Pontos de integração vêm só de [`sync_activities`](https://docs.play2sell.com/pt/api/integrations/activities).

| Ação | Escopo | O que faz |
| - | - | - |
| [`list_pipelines`](#acao-list_pipelines) | `leads:read` | Funis e etapas, com IDs, resultado e exigências de cada etapa |
| [`list_lead_fields`](#acao-list_lead_fields) | `leads:read` | Os campos do lead da empresa, inclusive os personalizados, e onde cada valor aparece no lead |
| [`get_lead`](#acao-get_lead) | `leads:read` | Um lead, por `lead_id` ou pelo seu `external_id` |
| [`list_leads`](#acao-list_leads) | `leads:read` | Lista filtrada e paginada por cursor; também é o feed de mudanças da sincronização |
| [`get_lead_history`](#acao-get_lead_history) | `leads:read` | Cada mudança do lead, com antes/depois e quem fez |
| [`sync_leads`](#acao-sync_leads) | `leads:write` | Cria ou atualiza até 100 leads por chamada (formulários, landing pages, outros sistemas) |
| [`update_lead`](#acao-update_lead) | `leads:write` | Muda só os campos enviados |
| [`move_lead_stage`](#acao-move_lead_stage) | `leads:write` | Move o lead para uma etapa, seguindo as regras dela |
| [`close_lead`](#acao-close_lead) | `leads:write` | Marca ganho ou perdido, seja qual for o nome das etapas |
| [`archive_lead`](#acao-archive_lead--restore_lead) / `restore_lead` | `leads:write` | Arquiva e traz de volta |
| [`add_lead_activity`](#acao-add_lead_activity) | `leads:write` | Registra nota, ligação, WhatsApp, e-mail, reunião ou visita no lead |
| [`list_lead_activities`](#acao-list_lead_activities) | `leads:read` | A linha do tempo de um lead, ou todas as atividades da empresa desde uma data |

## O lead

Toda ação que devolve um lead devolve este formato.

```json theme={null}
{
  "id": "6f1c2a9e-1b7d-4c1e-9a55-3f0b8e7d2c10",
  "external_id": "crm-48213",
  "source": "my-crm",
  "name": "Ana Souza",
  "email": "ana@empresa.com.br",
  "phone": "+5511987654321",
  "document": "12345678909",
  "company_name": "Empresa Ltda",
  "product": "Plano anual",
  "status": "open",
  "pipeline": { "id": "1b0e…", "name": "Leads" },
  "stage": { "id": "c4d2…", "key": "qualified", "name": "Qualificado", "order": 2, "outcome": "open" },
  "owner": { "email": "maria@suaempresa.com.br", "name": "Maria Santos" },
  "value": 12000,
  "expected_close_date": "2026-12-15",
  "win_probability": 40,
  "priority": "high",
  "buying_moment": "3 meses",
  "is_important": false,
  "is_starred": true,
  "tags": ["site", "vip"],
  "custom_fields": { "Cor preferida": "azul" },
  "notes": "Prefere WhatsApp depois das 18h",
  "lost_reason": null,
  "attribution": {
    "first_touch": { "utm_source": "linkedin", "landing_page": "https://www.exemplo.com.br/" },
    "last_touch": { "utm_source": "google" }
  },
  "version": 7,
  "last_change": { "origin": "api", "api_key_id": "0d9e…" },
  "created_at": "2026-11-02T13:05:11.204Z",
  "updated_at": "2026-11-20T10:41:52.880Z",
  "stage_changed_at": "2026-11-18T09:12:00.000Z",
  "closed_at": null
}
```

| Campo | Significado |
| - | - |
| `status` | `open`, `won`, `lost` (vem do `outcome` da etapa) ou `archived` |
| `stage.key` | Identificador estável da etapa. **Não muda** quando a empresa renomeia a etapa. Nas chamadas, use `stage.id` |
| `custom_fields` | Campos personalizados da empresa, rótulo → texto. Veja [`list_lead_fields`](#acao-list_lead_fields) |
| `version` | Sobe 1 a cada mudança de um campo deste contrato. Serve para o [`expected_version`](#evitar-sobrescrever-expected_version) |
| `last_change` | Quem fez a última mudança: `origin` é `api` (por esta API; `api_key_id` diz qual chave) ou `app` (qualquer outro caminho) |
| `closed_at` | Quando o lead foi ganho ou perdido; `null` enquanto aberto |

## Como apontar um lead

As ações de escrita e o `get_lead` aceitam **uma** das formas:

* `lead_id`: o ID do SalesOS (UUID);
* `external_id` + `source`: o seu ID, dentro do `source` usado na criação (padrão `api`).

Mandar as duas dá `400`. Lead de outra empresa nunca é encontrado: a resposta é `404 LEAD_NOT_FOUND`.

***

## Leitura

### Acao: list\_pipelines

Funis e etapas da empresa, em ordem. Chame uma vez, guarde e atualize quando um ID de etapa for recusado.

```bash theme={null}
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_pipelines"}'
```

```json theme={null}
{
  "data": {
    "pipelines": [
      {
        "id": "1b0e…", "key": "lead_pipeline", "name": "Leads", "is_default": true,
        "stages": [
          { "id": "a1…", "key": "new", "name": "Novo", "order": 0, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": false, "approval_required": false, "field": null } },
          { "id": "b2…", "key": "proposal", "name": "Proposta", "order": 3, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": true, "approval_required": false,
                              "field": { "label": "Valor da proposta", "type": "number", "required": true } } },
          { "id": "c3…", "key": "won", "name": "Ganho", "order": 5, "outcome": "won", "is_terminal": true,
            "requirements": { "document_required": false, "approval_required": true, "field": null } }
        ]
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "2026-11-20T10:00:00.000Z" }
}
```

`requirements` diz o que o [`move_lead_stage`](#acao-move_lead_stage) vai pedir quando um lead **avançar** para aquela etapa.

### Acao: list\_lead\_fields

Os campos do lead da empresa na ordem da tela, inclusive os personalizados. `path` diz onde o valor aparece no lead (`null` = não exposto pela API).

```json theme={null}
{
  "data": {
    "fields": [
      { "key": "customer_phone", "label": "Telefone", "type": "phone", "is_custom": false, "required": true, "options": null, "path": "phone" },
      { "key": "cor_preferida", "label": "Cor preferida", "type": "select", "is_custom": true, "required": false,
        "options": ["azul", "verde"], "path": "custom_fields.cor_preferida" }
    ]
  }
}
```

### Acao: get\_lead

**lead\_id** `string`

ID do SalesOS (UUID). Ou mande `external_id`.

**external\_id** `string`

O seu ID (até 255).

**source** `string`

Junto com `external_id`. Padrão `api`.

```json theme={null}
{ "action": "get_lead", "external_id": "crm-48213", "source": "my-crm" }
```

A resposta é sempre `200`: `{ "data": { "found": true, "lead": { … } } }`, ou `{ "found": false, "lead": null }` quando o lead não existe na empresa.

### Acao: list\_leads

**filters** `object`

Todos opcionais, combinados com E. Filtro desconhecido dá `400`, para um erro de digitação nunca devolver tudo.

| Filtro | Tipo | |
| - | - | - |
| `pipeline_id` | UUID | |
| `stage_ids` | UUID\[] (1–50) | Qualquer um |
| `status` | texto ou lista | `open`, `won`, `lost`, `archived` |
| `owner_email` | texto | |
| `source`, `external_id` | texto | |
| `tags` | texto\[] (1–20) | Qualquer uma |
| `q` | texto (2–100) | Busca em nome, e-mail, empresa ou telefone |
| `ids` | UUID\[] (1–100) | |
| `created_since`, `created_until`, `updated_since`, `updated_until` | ISO 8601 | |
| `include_archived` | booleano | Arquivados ficam de fora, salvo com `true` (ou `status` com `archived`) |
| `exclude_own_changes` | booleano | Tira os leads cuja **última** mudança foi feita pela própria chave. Veja [Sincronização nos dois sentidos](https://docs.play2sell.com/pt/api/integrations/leads-sync.md) |

**sort** `object`

`{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }`. Padrão: `updated_at` crescente quando há `updated_since`; senão, os mais novos primeiro.

**limit** `integer`

1–500, padrão 100. Acima de 500, vira 500.

**cursor** `string`

O `next_cursor` da página anterior.

```json theme={null}
{ "action": "list_leads", "filters": { "status": "open", "tags": ["site"] }, "limit": 50 }
```

```json theme={null}
{
  "data": {
    "items": [ { "id": "6f1c…", "name": "Ana Souza", "…": "…" } ],
    "next_cursor": "eyJ2IjoxLCJvIjoi…",
    "has_more": true,
    "server_time": "2026-11-20T10:41:57.120Z",
    "sync_watermark": null
  }
}
```

O cursor fica preso aos filtros e à ordem que o geraram. Mudar no meio da paginação dá `400` (`cursor`): recomece sem cursor.

**Feed de mudanças.** Com `updated_since`, a lista vem em `updated_at` crescente e a resposta traz `sync_watermark`. Quando `has_more` for `false`, use o `sync_watermark` como próximo `updated_since`: nenhuma mudança anterior a ele aparece depois. Veja [Sincronização nos dois sentidos](https://docs.play2sell.com/pt/api/integrations/leads-sync.md).

### Acao: get\_lead\_history

Cada mudança do lead, da mais antiga para a mais nova: o que mudou (antes/depois), o tipo de mudança e quem fez.

```json theme={null}
{ "action": "get_lead_history", "lead_id": "6f1c…", "limit": 100 }
```

```json theme={null}
{
  "data": {
    "found": true,
    "items": [
      {
        "id": 98121, "version": 7, "kind": "stage_changed",
        "changes": {
          "stage_id": { "old": "a1…", "new": "c4d2…" }
        },
        "change_source": { "origin": "app", "api_key_id": null },
        "changed_at": "2026-11-18T09:12:00.000Z"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
```

`kind` é `created`, `updated`, `stage_changed`, `archived` ou `restored`. `changes` traz só os campos que mudaram, cada um com `old` e `new`. O registro vale para os leads do funil de leads.

***

## Escrita

Toda ação de escrita:

* responde com o lead **como ficou depois da mudança**, mais `result`;
* aceita [`idempotency_key`](#repetir-sem-duplicar-idempotency_key) e [`expected_version`](#evitar-sobrescrever-expected_version), opcionais;
* roda numa transação só: grava tudo ou nada.

O [`add_lead_activity`](#acao-add_lead_activity) responde com a atividade em vez do lead e não usa `expected_version`.

### Acao: sync\_leads

Cria ou atualiza **até 100 leads por chamada**: formulário do site, landing page, outro sistema.

O lead novo entra no funil de leads padrão da empresa, na **primeira etapa** ou na `stage_id` enviada.

#### Como o lead é reconhecido

Para cada item, procuramos um lead **ativo** da empresa nesta ordem:

1. o mesmo `external_id` **no mesmo `source`** (duas origens nunca se misturam);
2. o mesmo `email` (sem diferenciar maiúsculas);
3. o mesmo `phone`.

Achou: **atualiza**. Não achou: **cria**. Se o e-mail é de um lead e o telefone de outro, o item volta com `IDENTITY_CONFLICT` e **nada é gravado** para ele. A mesma pessoa duas vezes no lote cria um lead e atualiza esse mesmo lead na segunda.

#### O que uma atualização faz

| Campo | Comportamento |
| - | - |
| Ausente ou vazio | Nada muda (nunca apaga) |
| `name`, `email`, `phone`, `document`, `company_name`, `product` | Substituído |
| `tags` | **Somadas** às etiquetas do lead |
| `extra_fields` | Mesclados: rótulo enviado substitui o mesmo rótulo; os outros ficam |
| `attribution` | A **primeira** fica como origem do lead; cada chamada vira o último toque e entra no histórico de conversões (últimas 20) |
| `owner_email` | Troca o responsável só se for usuário **ativo** da empresa |
| `stage_id` | Vale só para **criar**. Em lead existente é ignorado, com o aviso `stage_ignored_use_move_lead_stage` |
| `source`, anotações | Esta ação nunca muda |

#### Pedido

**source** `string`

De onde vêm os leads, em minúsculas: letras, números, `_ . -` (até 60). Padrão `api`.

**idempotency\_key** `string`

Opcional. Veja [Repetir sem duplicar](#repetir-sem-duplicar-idempotency_key).

**leads** `array` *required*

Lista de leads (até **100**).

**leads\[].external\_id** `string` *required*

ID único do lead no seu sistema (até 255).

**leads\[].name** `string`

Até 200. Para **criar**, mande pelo menos um entre `name`, `email` e `phone`.

**leads\[].email** `string`

E-mail do cliente.

**leads\[].phone** `string`

Com DDI, ex.: `+5511987654321`. Sem DDI, vale o país da empresa.

**leads\[].document** `string`

CPF (11) ou CNPJ (14) dígitos; a pontuação é ignorada.

**leads\[].company\_name** `string`

Até 200.

**leads\[].product** `string`

Até 300.

**leads\[].tags** `string[]`

Até 20 etiquetas, 60 caracteres cada.

**leads\[].owner\_email** `string`

Responsável. Desconhecido ou inativo: o lead vai para o responsável padrão, com aviso.

**leads\[].stage\_id** `string`

Opcional, só para lead novo: uma etapa **aberta** do funil de leads **sem exigências** (veja `list_pipelines`). Fora disso, o item falha com `STAGE_NOT_ALLOWED_ON_CREATE` ou `STAGE_NOT_FOUND`.

**leads\[].extra\_fields** `object`

Rótulo → texto. Até 50 campos, 1.000 caracteres cada.

**leads\[].attribution** `object`

`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `landing_page`, `referrer`, `form_id` (500 caracteres cada).

```bash theme={null}
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"action":"sync_leads","source":"website","idempotency_key":"form-2026-11-11-0001","leads":[{"external_id":"form-2026-11-11-0001","name":"Ana Souza","email":"ana@empresa.com.br","phone":"+5511987654321","product":"Plano anual","tags":["site"],"attribution":{"utm_source":"linkedin","landing_page":"https://www.exemplo.com.br/"}}]}'
```

#### Resposta (200)

Um resultado **por lead, na ordem do pedido**. Item com problema não derruba o lote: volta com `status: "error"` e os outros seguem.

```json theme={null}
{
  "data": {
    "created": 1, "updated": 1, "errors": 1, "total": 3,
    "results": [
      { "index": 0, "external_id": "form-1", "status": "created", "lead_id": "6f1c…", "matched_by": null, "warnings": ["owner_fallback"] },
      { "index": 1, "external_id": "form-2", "status": "updated", "lead_id": "9a2d…", "matched_by": "email", "warnings": [] },
      { "index": 2, "external_id": "form-3", "status": "error", "lead_id": null, "matched_by": null, "warnings": [],
        "error": { "code": "INVALID_PHONE", "message": "Phone with country code (E.164), e.g. +5511987654321", "field": "phone" } }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "2026-11-11T19:30:00.000Z" }
}
```

| Campo | Significado |
| - | - |
| `status` | `created`, `updated` ou `error` |
| `matched_by` | Como o lead existente foi reconhecido: `external_id`, `email` ou `phone` |
| `warnings` | `owner_fallback`, `owner_not_found`, `stage_ignored_use_move_lead_stage`, `event_not_emitted` |
| `error.code` | `INVALID_ITEM`, `MISSING_EXTERNAL_ID`, `MISSING_CONTACT`, `INVALID_EMAIL`, `INVALID_PHONE`, `INVALID_DOCUMENT`, `INVALID_FIELD`, `IDENTITY_CONFLICT`, `STAGE_NOT_FOUND`, `STAGE_NOT_ALLOWED_ON_CREATE`, `NO_PIPELINE`, `NO_ACTIVE_USER`, `WRITE_FAILED` |

Erros do **lote inteiro** (`leads` vazio ou acima de 100, `source` ou `idempotency_key` inválidos) respondem `400 VALIDATION_ERROR`.

### Acao: update\_lead

Muda **só os campos enviados**. `null` limpa um campo opcional. Campo desconhecido dá `400`.

**fields** `object` *required*

`name` (não pode ser limpo), `email`, `phone`, `document`, `company_name`, `product`, `value` (≥ 0), `expected_close_date` (`AAAA-MM-DD`), `priority` (`low`, `medium`, `high`, `urgent`), `notes` (até 5.000), `buying_moment`, `is_important`, `is_starred`, `owner_email`, `custom_fields` (rótulo → texto, ou `null` para tirar o campo; até 50), `add_tags`, `remove_tags` (até 20 cada).

```json theme={null}
{
  "action": "update_lead",
  "external_id": "crm-48213", "source": "my-crm",
  "fields": { "value": 15000, "owner_email": "joao@suaempresa.com.br", "add_tags": ["vip"], "custom_fields": { "Cor preferida": null } },
  "idempotency_key": "crm-48213-v8"
}
```

Resposta: `200` com `{ "data": { "result": "updated", "lead": { … } } }`.

### Acao: move\_lead\_stage

Move o lead para `stage_id`, uma etapa **do próprio funil do lead**. **Avançar** segue as regras da etapa exatamente como no app; **recuar** é sempre livre.

**stage\_id** `string` *required*

ID da etapa, de `list_pipelines`.

**document\_url** `string`

Quando a etapa exige documento: link `http(s)` dele.

**field\_value** `string | number`

Quando a etapa exige um campo (`requirements.field`).

**lost\_reason** `string`

Quando a etapa de destino tem `outcome: "lost"` (1–500 caracteres).

**value** `number`

Atualiza o valor do lead junto com a mudança.

**message** `string`

Recado ao líder quando a etapa exige aprovação (até 1.000).

| `result` | HTTP | Significado |
| - | - | - |
| `moved` | 200 | O lead está na nova etapa; `status` acompanha o `outcome` dela |
| `unchanged` | 200 | O lead já estava nessa etapa |
| `pending_approval` | **202** | A etapa exige aprovação do líder. O lead **não mudou**: o líder recebeu o pedido, e a resposta traz `approval_id` |

Exigência faltando dá `422 STAGE_REQUIREMENT_MISSING`, e `details` diz o que mandar:

```json theme={null}
{
  "error": {
    "code": "STAGE_REQUIREMENT_MISSING",
    "message": "The stage requires input before the lead can advance",
    "details": { "requirement": "field", "field": "field_value", "label": "Valor da proposta", "type": "number" }
  }
}
```

### Acao: close\_lead

Marca o lead como ganho ou perdido **pelo resultado**, seja qual for o nome das etapas. Leva o lead para a primeira etapa do funil com aquele `outcome`, com as mesmas regras do `move_lead_stage`.

**outcome** `string` *required*

`won` ou `lost`.

**lost\_reason** `string`

Só com `lost`.

**value** `number`

Valor final.

```json theme={null}
{ "action": "close_lead", "lead_id": "6f1c…", "outcome": "lost", "lost_reason": "Comprou do concorrente" }
```

Funil sem etapa com esse resultado: `422 NO_STAGE_FOR_OUTCOME`. Para reabrir, use `move_lead_stage` para uma etapa aberta.

### Acao: archive\_lead / restore\_lead

`archive_lead` tira o lead do funil (`status: "archived"`) sem apagar nada. `restore_lead` traz de volta com a situação que ele tinha. Respondem `result: "archived"`, `"restored"` ou `"unchanged"`. Lead arquivado não pode ser alterado nem movido (`409 LEAD_ARCHIVED`) até ser restaurado.

***

## Notas e atividades

### Acao: add\_lead\_activity

Registra algo que aconteceu com o lead. Aparece na linha do tempo do lead no app, como as atividades registradas lá, e **não pontua** (pontos vêm de [`sync_activities`](https://docs.play2sell.com/pt/api/integrations/activities)).

**lead\_id** `string`

O lead. Ou mande `lead_external_id` + `lead_source`.

**lead\_external\_id** `string`

O seu ID do lead (com `lead_source`, padrão `api`).

**type** `string` *required*

`note`, `call`, `whatsapp`, `email`, `meeting` ou `visit`.

**description** `string`

Até 5.000 caracteres. Obrigatória em `note`.

**occurred\_at** `string`

Quando aconteceu (ISO 8601). Padrão: agora. Não pode ser no futuro.

**author\_email** `string`

Quem fez: usuário ativo da empresa. Padrão: o responsável pelo lead.

**external\_id** `string`

O seu ID **desta atividade** (com `source`, padrão `api`). Mandar o mesmo par de novo devolve a atividade existente (`result: "existing"`, `200`) em vez de criar outra.

**direction** `string`

`inbound` ou `outbound` (ligações, mensagens).

**duration\_seconds** `integer`

0–86.400.

```json theme={null}
{
  "action": "add_lead_activity",
  "lead_external_id": "crm-48213", "lead_source": "my-crm",
  "type": "call", "direction": "outbound", "duration_seconds": 312,
  "description": "Conversamos sobre financiamento; manda os documentos na segunda",
  "author_email": "maria@suaempresa.com.br",
  "external_id": "call-99812", "source": "my-crm"
}
```

Resposta `201` (criada) ou `200` (já existia):

```json theme={null}
{
  "data": {
    "result": "created",
    "activity": {
      "id": "5e7a…", "lead_id": "6f1c…", "type": "call",
      "description": "Conversamos sobre financiamento; manda os documentos na segunda",
      "occurred_at": "2026-11-20T14:02:00.000Z",
      "author": { "email": "maria@suaempresa.com.br", "name": "Maria Santos" },
      "external_id": "call-99812", "source": "my-crm",
      "direction": "outbound", "duration_seconds": 312,
      "stage_change": null,
      "change_source": { "origin": "api", "api_key_id": "0d9e…" }
    }
  }
}
```

### Acao: list\_lead\_activities

A linha do tempo de um lead (`lead_id`, ou `external_id` + `source`), ou **todas as atividades da empresa** a partir de `since`. Inclui o que foi registrado no app e por integrações, da mais antiga para a mais nova. Mudança de etapa vem como `type: "status_change"`, com `stage_change.from_stage_id` / `to_stage_id`.

**since** `string`

ISO 8601. Obrigatório quando nenhum lead é informado. Filtra por `occurred_at`: atividade registrada depois com `occurred_at` no passado não aparece num feed que já passou daquela data.

**types** `string[]`

Só estes tipos, ex.: `["note", "call"]`.

**limit** `integer`

1–500, padrão 100.

**cursor** `string`

O `next_cursor` da página anterior.

Resposta: `{ "data": { "found": true, "items": [ … ], "next_cursor": null, "has_more": false } }`. Para lead que não existe, `found` é `false`.

***

## Repetir sem duplicar: idempotency\_key

A rede falha. Para repetir uma escrita sem fazê-la duas vezes, mande uma `idempotency_key` (8–255 caracteres: letras, números, `_ . : -`) única para aquela operação, como o ID do evento no seu sistema.

| Situação | Resposta |
| - | - |
| Primeira chamada com a chave | Executa e guarda a resposta |
| Mesma chave, **mesmo pedido**, em até 24 h | A resposta guardada, com `"idempotent_replayed": true`. Nada é gravado de novo |
| Mesma chave, **outro pedido** | `422 IDEMPOTENCY_KEY_REUSED` |
| Mesma chave com a primeira chamada ainda em andamento | A segunda espera a primeira e recebe a resposta dela |
| A chamada terminou em erro | Nada fica guardado: corrija e repita com a mesma chave |

A chave vale por chave de API: duas chaves nunca compartilham. Ela vai no **corpo**, que é assinado, e não num cabeçalho.

## Evitar sobrescrever: expected\_version

Para mudar um lead só se ninguém mexeu nele desde a sua leitura, mande a `version` lida como `expected_version`. Se o lead já estiver em outra versão, nada é gravado e a resposta é `409 VERSION_CONFLICT`, com `details.current_version`. Leia de novo, junte as mudanças e repita.

## Erros

| HTTP | `error.code` | Causa | O que fazer |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | Campo faltando, de tipo errado ou desconhecido. `details` lista cada um | Corrija o pedido |
| 404 | `LEAD_NOT_FOUND` | Não há esse lead na empresa da chave | Confira `lead_id`, ou `external_id` + `source` |
| 409 | `LEAD_ARCHIVED` | O lead está arquivado | `restore_lead` antes |
| 409 | `VERSION_CONFLICT` | O lead mudou desde o `expected_version` | Leia de novo e repita |
| 409 | `APPROVAL_PENDING` | Já há mudança de etapa desse lead esperando aprovação | Aguarde o líder |
| 409 | `NO_APPROVER` | A etapa exige aprovação e o responsável não tem líder | Peça ao admin para definir o líder da equipe |
| 422 | `STAGE_NOT_FOUND` | `stage_id` não é etapa do funil do lead | Atualize o `list_pipelines` |
| 422 | `STAGE_REQUIREMENT_MISSING` | A etapa exige documento ou campo | Mande o que `details` pede |
| 422 | `NO_STAGE_FOR_OUTCOME` | O funil não tem etapa de ganho/perda | Peça ao admin para definir o resultado da etapa |
| 422 | `OWNER_NOT_FOUND` | `owner_email` não é usuário ativo da empresa | Use o e-mail de um usuário ativo |
| 422 | `AUTHOR_NOT_FOUND` | `author_email` não é usuário ativo da empresa | Use o e-mail de um usuário ativo, ou omita |
| 422 | `IDEMPOTENCY_KEY_REUSED` | Mesma `idempotency_key`, outro pedido | Use chave nova para operação nova |

Erros de autenticação (`401`, e `403 scope_insufficient` quando falta `leads:read` ou `leads:write` na chave) e de limite de chamadas (`429`) têm formato próprio, o mesmo em todos os endpoints: veja [Autenticação](https://docs.play2sell.com/pt/api/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.