> ## 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

> Lea, cree, actualice y mueva leads por el embudo de cada empresa — por ID, nunca por el nombre de la etapa.

> [!TIP]
>
> Pruebe solicitudes firmadas en el navegador en el [API Sandbox](https://play2sellsa.github.io/api-sandbox/): pegue la clave y el secreto, y el playground firma solo.

> [!NOTE]
>
> Los ejemplos muestran el encabezado `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE` tal como viaja. Para calcular la firma en su código, use el `signedRequest` de [Autenticación](https://docs.play2sell.com/es/api/authentication.md).

La API de Leads permite que su sistema trabaje con los leads de la empresa de la clave: listar y leer, crear y actualizar, mover por el embudo, marcar ganado o perdido, archivar y registrar notas y actividades. Mantener dos sistemas sincronizados está paso a paso en [Sincronización en los dos sentidos](https://docs.play2sell.com/es/api/integrations/leads-sync.md).

## Antes de empezar

* **Un endpoint, una acción por llamada.** Toda llamada es un `POST` a `https://api.play2sell.com/functions/v1/default-integration` con `"action"` en el cuerpo. Los filtros también van en el cuerpo, porque la firma cubre el cuerpo y no la query string (vea [Convenciones](https://docs.play2sell.com/es/api/conventions.md)).
* **Alcances.** Leer exige `leads:read`; escribir exige `leads:write`. Uno no incluye al otro, y ninguno abre `sync_collaborators` ni `sync_activities`. Una clave sin el alcance recibe `403` con `code: "scope_insufficient"`. Las claves se crean en **Admin > Integraciones > Claves de API**.
* **Cada empresa tiene su propio embudo.** Nombres y orden de las etapas se configuran por empresa y pueden cambiar en cualquier momento. Use siempre el **ID de la etapa** de [`list_pipelines`](#accion-list_pipelines) y lea **ganado/perdido en `stage.outcome`** (`open`, `won`, `lost`), nunca en el nombre.
* **Los puntos quedan en Misiones.** Lo que cambia por esta API actualiza el lead, la etapa y el historial, pero **no suma puntos** en misiones ni campañas. Los puntos de integración vienen solo de [`sync_activities`](https://docs.play2sell.com/es/api/integrations/activities).

| Acción | Alcance | Qué hace |
| - | - | - |
| [`list_pipelines`](#accion-list_pipelines) | `leads:read` | Embudos y etapas, con IDs, resultado y requisitos de cada etapa |
| [`list_lead_fields`](#accion-list_lead_fields) | `leads:read` | Los campos del lead de la empresa, incluidos los personalizados, y dónde aparece cada valor en el lead |
| [`get_lead`](#accion-get_lead) | `leads:read` | Un lead, por `lead_id` o por su `external_id` |
| [`list_leads`](#accion-list_leads) | `leads:read` | Lista filtrada y paginada por cursor; también es el feed de cambios de la sincronización |
| [`get_lead_history`](#accion-get_lead_history) | `leads:read` | Cada cambio del lead, con antes/después y quién lo hizo |
| [`sync_leads`](#accion-sync_leads) | `leads:write` | Crea o actualiza hasta 100 leads por llamada (formularios, landing pages, otros sistemas) |
| [`update_lead`](#accion-update_lead) | `leads:write` | Cambia solo los campos enviados |
| [`move_lead_stage`](#accion-move_lead_stage) | `leads:write` | Mueve el lead a una etapa, siguiendo sus reglas |
| [`close_lead`](#accion-close_lead) | `leads:write` | Marca ganado o perdido, sea cual sea el nombre de las etapas |
| [`archive_lead`](#accion-archive_lead--restore_lead) / `restore_lead` | `leads:write` | Archiva y restaura |
| [`add_lead_activity`](#accion-add_lead_activity) | `leads:write` | Registra nota, llamada, WhatsApp, e-mail, reunión o visita en el lead |
| [`list_lead_activities`](#accion-list_lead_activities) | `leads:read` | La línea de tiempo de un lead, o todas las actividades de la empresa desde una fecha |

## El lead

Toda acción que devuelve un lead devuelve 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",
  "phone": "+5511987654321",
  "document": "12345678909",
  "company_name": "Empresa S.A.",
  "product": "Plan anual",
  "status": "open",
  "pipeline": { "id": "1b0e…", "name": "Leads" },
  "stage": { "id": "c4d2…", "key": "qualified", "name": "Calificado", "order": 2, "outcome": "open" },
  "owner": { "email": "maria@suempresa.com", "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": ["sitio", "vip"],
  "custom_fields": { "Color preferido": "azul" },
  "notes": "Prefiere WhatsApp después de las 18 h",
  "lost_reason": null,
  "attribution": {
    "first_touch": { "utm_source": "linkedin", "landing_page": "https://www.ejemplo.com/" },
    "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` (del `outcome` de la etapa) o `archived` |
| `stage.key` | Identificador estable de la etapa. **No cambia** cuando la empresa renombra la etapa. En las llamadas, use `stage.id` |
| `custom_fields` | Campos personalizados de la empresa, etiqueta → texto. Vea [`list_lead_fields`](#accion-list_lead_fields) |
| `version` | Sube 1 con cada cambio de un campo de este contrato. Sirve para [`expected_version`](#evitar-sobrescrituras-expected_version) |
| `last_change` | Quién hizo el último cambio: `origin` es `api` (por esta API; `api_key_id` indica qué clave) o `app` (cualquier otro camino) |
| `closed_at` | Cuándo el lead se ganó o se perdió; `null` mientras está abierto |

## Cómo identificar un lead

Las acciones de escritura y `get_lead` aceptan **una** de las formas:

* `lead_id`: el ID de SalesOS (UUID);
* `external_id` + `source`: su ID, dentro del `source` usado al crearlo (por defecto `api`).

Enviar las dos devuelve `400`. Un lead de otra empresa nunca se encuentra: la respuesta es `404 LEAD_NOT_FOUND`.

***

## Lectura

### Accion: list\_pipelines

Embudos y etapas de la empresa, en orden. Llámela una vez, guárdela y actualícela cuando se rechace un ID de etapa.

```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": "Nuevo", "order": 0, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": false, "approval_required": false, "field": null } },
          { "id": "b2…", "key": "proposal", "name": "Propuesta", "order": 3, "outcome": "open", "is_terminal": false,
            "requirements": { "document_required": true, "approval_required": false,
                              "field": { "label": "Monto de la propuesta", "type": "number", "required": true } } },
          { "id": "c3…", "key": "won", "name": "Ganado", "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` indica lo que [`move_lead_stage`](#accion-move_lead_stage) pedirá cuando un lead **avance** a esa etapa.

### Accion: list\_lead\_fields

Los campos del lead de la empresa en el orden de la pantalla, incluidos los personalizados. `path` indica dónde aparece el valor en el lead (`null` = no expuesto por la API).

```json theme={null}
{
  "data": {
    "fields": [
      { "key": "customer_phone", "label": "Teléfono", "type": "phone", "is_custom": false, "required": true, "options": null, "path": "phone" },
      { "key": "color_preferido", "label": "Color preferido", "type": "select", "is_custom": true, "required": false,
        "options": ["azul", "verde"], "path": "custom_fields.color_preferido" }
    ]
  }
}
```

### Accion: get\_lead

**lead\_id** `string`

ID de SalesOS (UUID). O envíe `external_id`.

**external\_id** `string`

Su ID (hasta 255).

**source** `string`

Junto con `external_id`. Por defecto `api`.

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

La respuesta siempre es `200`: `{ "data": { "found": true, "lead": { … } } }`, o `{ "found": false, "lead": null }` cuando el lead no existe en la empresa.

### Accion: list\_leads

**filters** `object`

Todos opcionales, combinados con Y. Un filtro desconocido devuelve `400`, para que un error de tipeo nunca devuelva todo.

| Filtro | Tipo | |
| - | - | - |
| `pipeline_id` | UUID | |
| `stage_ids` | UUID\[] (1–50) | Cualquiera |
| `status` | texto o lista | `open`, `won`, `lost`, `archived` |
| `owner_email` | texto | |
| `source`, `external_id` | texto | |
| `tags` | texto\[] (1–20) | Cualquiera |
| `q` | texto (2–100) | Busca en nombre, e-mail, empresa o teléfono |
| `ids` | UUID\[] (1–100) | |
| `created_since`, `created_until`, `updated_since`, `updated_until` | ISO 8601 | |
| `include_archived` | booleano | Los archivados quedan fuera, salvo con `true` (o `status` con `archived`) |
| `exclude_own_changes` | booleano | Quita los leads cuyo **último** cambio lo hizo la propia clave. Vea [Sincronización en los dos sentidos](https://docs.play2sell.com/es/api/integrations/leads-sync.md) |

**sort** `object`

`{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }`. Por defecto: `updated_at` ascendente cuando hay `updated_since`; si no, los más nuevos primero.

**limit** `integer`

1–500, por defecto 100. Por encima de 500, se reduce a 500.

**cursor** `string`

El `next_cursor` de la página anterior.

```json theme={null}
{ "action": "list_leads", "filters": { "status": "open", "tags": ["sitio"] }, "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
  }
}
```

El cursor queda atado a los filtros y al orden que lo generaron. Cambiarlos a mitad de la paginación devuelve `400` (`cursor`): empiece de nuevo sin cursor.

**Feed de cambios.** Con `updated_since`, la lista viene en `updated_at` ascendente y la respuesta trae `sync_watermark`. Cuando `has_more` sea `false`, use `sync_watermark` como el próximo `updated_since`: ningún cambio anterior a él aparecerá después. Vea [Sincronización en los dos sentidos](https://docs.play2sell.com/es/api/integrations/leads-sync.md).

### Accion: get\_lead\_history

Cada cambio del lead, del más antiguo al más nuevo: qué cambió (antes/después), el tipo de cambio y quién lo hizo.

```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` es `created`, `updated`, `stage_changed`, `archived` o `restored`. `changes` trae solo los campos que cambiaron, cada uno con `old` y `new`. El registro vale para los leads del embudo de leads.

***

## Escritura

Toda acción de escritura:

* responde con el lead **tal como quedó después del cambio**, más `result`;
* acepta [`idempotency_key`](#reintentar-sin-duplicar-idempotency_key) y [`expected_version`](#evitar-sobrescrituras-expected_version), opcionales;
* corre en una sola transacción: graba todo o nada.

[`add_lead_activity`](#accion-add_lead_activity) responde con la actividad en lugar del lead y no usa `expected_version`.

### Accion: sync\_leads

Crea o actualiza **hasta 100 leads por llamada**: formulario del sitio, landing page, otro sistema.

El lead nuevo entra en el embudo de leads por defecto de la empresa, en la **primera etapa** o en la `stage_id` enviada.

#### Cómo se reconoce el lead

Para cada ítem buscamos un lead **activo** de la empresa en este orden:

1. el mismo `external_id` **en el mismo `source`** (dos orígenes nunca se mezclan);
2. el mismo `email` (sin distinguir mayúsculas);
3. el mismo `phone`.

Si lo encuentra: **actualiza**. Si no: **crea**. Si el e-mail es de un lead y el teléfono de otro, el ítem vuelve con `IDENTITY_CONFLICT` y **no se graba nada** para él. La misma persona dos veces en el lote crea un lead y actualiza ese mismo lead la segunda vez.

#### Qué hace una actualización

| Campo | Comportamiento |
| - | - |
| Ausente o vacío | No cambia nada (nunca borra) |
| `name`, `email`, `phone`, `document`, `company_name`, `product` | Reemplazado |
| `tags` | **Se suman** a las etiquetas del lead |
| `extra_fields` | Se combinan: una etiqueta enviada reemplaza la misma etiqueta; las demás quedan |
| `attribution` | La **primera** queda como origen del lead; cada llamada pasa a ser el último toque y entra en el historial de conversiones (últimas 20) |
| `owner_email` | Cambia el responsable solo si es un usuario **activo** de la empresa |
| `stage_id` | Vale solo para **crear**. En un lead existente se ignora, con el aviso `stage_ignored_use_move_lead_stage` |
| `source`, notas | Esta acción nunca los cambia |

#### Solicitud

**source** `string`

De dónde vienen los leads, en minúsculas: letras, números, `_ . -` (hasta 60). Por defecto `api`.

**idempotency\_key** `string`

Opcional. Vea [Reintentar sin duplicar](#reintentar-sin-duplicar-idempotency_key).

**leads** `array` *required*

Lista de leads (hasta **100**).

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

ID único del lead en su sistema (hasta 255).

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

Hasta 200. Para **crear**, envíe al menos uno entre `name`, `email` y `phone`.

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

E-mail del cliente.

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

Con código de país, p. ej. `+5511987654321`. Sin él, vale el país de la empresa.

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

CPF (11) o CNPJ (14) dígitos; la puntuación se ignora.

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

Hasta 200.

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

Hasta 300.

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

Hasta 20 etiquetas, 60 caracteres cada una.

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

Responsable. Desconocido o inactivo: el lead va al responsable por defecto, con aviso.

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

Opcional, solo para leads nuevos: una etapa **abierta** del embudo de leads **sin requisitos** (vea `list_pipelines`). Si no, el ítem falla con `STAGE_NOT_ALLOWED_ON_CREATE` o `STAGE_NOT_FOUND`.

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

Etiqueta → texto. Hasta 50 campos, 1.000 caracteres cada uno.

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

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

```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","phone":"+5511987654321","product":"Plan anual","tags":["sitio"],"attribution":{"utm_source":"linkedin","landing_page":"https://www.ejemplo.com/"}}]}'
```

#### Respuesta (200)

Un resultado **por lead, en el orden de la solicitud**. Un ítem con problema no hace fallar el lote: vuelve con `status: "error"` y los demás siguen.

```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` o `error` |
| `matched_by` | Cómo se reconoció el lead existente: `external_id`, `email` o `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` |

Los errores del **lote entero** (`leads` vacío o con más de 100, `source` o `idempotency_key` inválidos) responden `400 VALIDATION_ERROR`.

### Accion: update\_lead

Cambia **solo los campos enviados**. `null` limpia un campo opcional. Un campo desconocido devuelve `400`.

**fields** `object` *required*

`name` (no se puede limpiar), `email`, `phone`, `document`, `company_name`, `product`, `value` (≥ 0), `expected_close_date` (`AAAA-MM-DD`), `priority` (`low`, `medium`, `high`, `urgent`), `notes` (hasta 5.000), `buying_moment`, `is_important`, `is_starred`, `owner_email`, `custom_fields` (etiqueta → texto, o `null` para quitar el campo; hasta 50), `add_tags`, `remove_tags` (hasta 20 cada uno).

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

Respuesta: `200` con `{ "data": { "result": "updated", "lead": { … } } }`.

### Accion: move\_lead\_stage

Mueve el lead a `stage_id`, una etapa **del propio embudo del lead**. **Avanzar** sigue las reglas de la etapa exactamente como en la app; **retroceder** siempre está permitido.

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

ID de la etapa, de `list_pipelines`.

**document\_url** `string`

Cuando la etapa exige un documento: enlace `http(s)` al documento.

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

Cuando la etapa exige un campo (`requirements.field`).

**lost\_reason** `string`

Cuando la etapa de destino tiene `outcome: "lost"` (1–500 caracteres).

**value** `number`

Actualiza el valor del lead junto con el cambio.

**message** `string`

Mensaje al líder cuando la etapa exige aprobación (hasta 1.000).

| `result` | HTTP | Significado |
| - | - | - |
| `moved` | 200 | El lead está en la nueva etapa; `status` sigue el `outcome` de la etapa |
| `unchanged` | 200 | El lead ya estaba en esa etapa |
| `pending_approval` | **202** | La etapa exige aprobación del líder. El lead **no se movió**: el líder recibió el pedido, y la respuesta trae `approval_id` |

Un requisito faltante devuelve `422 STAGE_REQUIREMENT_MISSING`, y `details` indica qué enviar:

```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": "Monto de la propuesta", "type": "number" }
  }
}
```

### Accion: close\_lead

Marca el lead como ganado o perdido **por el resultado**, sea cual sea el nombre de las etapas. Lo lleva a la primera etapa del embudo con ese `outcome`, con las mismas reglas de `move_lead_stage`.

**outcome** `string` *required*

`won` o `lost`.

**lost\_reason** `string`

Solo con `lost`.

**value** `number`

Valor final.

```json theme={null}
{ "action": "close_lead", "lead_id": "6f1c…", "outcome": "lost", "lost_reason": "Compró a la competencia" }
```

Si el embudo no tiene una etapa con ese resultado: `422 NO_STAGE_FOR_OUTCOME`. Para reabrir, use `move_lead_stage` hacia una etapa abierta.

### Accion: archive\_lead / restore\_lead

`archive_lead` saca el lead del embudo (`status: "archived"`) sin borrar nada. `restore_lead` lo devuelve con la situación que tenía. Responden `result: "archived"`, `"restored"` o `"unchanged"`. Un lead archivado no se puede cambiar ni mover (`409 LEAD_ARCHIVED`) hasta que se restaure.

***

## Notas y actividades

### Accion: add\_lead\_activity

Registra algo que pasó con el lead. Aparece en la línea de tiempo del lead en la app, como las actividades registradas allí, y **no suma puntos** (los puntos vienen de [`sync_activities`](https://docs.play2sell.com/es/api/integrations/activities)).

**lead\_id** `string`

El lead. O envíe `lead_external_id` + `lead_source`.

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

Su ID del lead (con `lead_source`, por defecto `api`).

**type** `string` *required*

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

**description** `string`

Hasta 5.000 caracteres. Obligatoria en `note`.

**occurred\_at** `string`

Cuándo pasó (ISO 8601). Por defecto: ahora. No puede estar en el futuro.

**author\_email** `string`

Quién lo hizo: un usuario activo de la empresa. Por defecto: el responsable del lead.

**external\_id** `string`

Su ID de **esta actividad** (con `source`, por defecto `api`). Enviar el mismo par de nuevo devuelve la actividad existente (`result: "existing"`, `200`) en lugar de crear otra.

**direction** `string`

`inbound` u `outbound` (llamadas, mensajes).

**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": "Hablamos de financiamiento; envía los documentos el lunes",
  "author_email": "maria@suempresa.com",
  "external_id": "call-99812", "source": "my-crm"
}
```

Respuesta `201` (creada) o `200` (ya existía):

```json theme={null}
{
  "data": {
    "result": "created",
    "activity": {
      "id": "5e7a…", "lead_id": "6f1c…", "type": "call",
      "description": "Hablamos de financiamiento; envía los documentos el lunes",
      "occurred_at": "2026-11-20T14:02:00.000Z",
      "author": { "email": "maria@suempresa.com", "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…" }
    }
  }
}
```

### Accion: list\_lead\_activities

La línea de tiempo de un lead (`lead_id`, o `external_id` + `source`), o **todas las actividades de la empresa** desde `since`. Incluye lo registrado en la app y por integraciones, de la más antigua a la más nueva. Los cambios de etapa vienen como `type: "status_change"`, con `stage_change.from_stage_id` / `to_stage_id`.

**since** `string`

ISO 8601. Obligatorio cuando no se indica un lead. Filtra por `occurred_at`: una actividad registrada después con `occurred_at` en el pasado no aparece en un feed que ya pasó esa fecha.

**types** `string[]`

Solo estos tipos, p. ej. `["note", "call"]`.

**limit** `integer`

1–500, por defecto 100.

**cursor** `string`

El `next_cursor` de la página anterior.

Respuesta: `{ "data": { "found": true, "items": [ … ], "next_cursor": null, "has_more": false } }`. Para un lead que no existe, `found` es `false`.

***

## Reintentar sin duplicar: idempotency\_key

La red falla. Para reintentar una escritura sin hacerla dos veces, envíe una `idempotency_key` (8–255 caracteres: letras, números, `_ . : -`) única para esa operación, como el ID del evento en su sistema.

| Situación | Respuesta |
| - | - |
| Primera llamada con la clave | Se ejecuta y se guarda la respuesta |
| Misma clave, **misma solicitud**, dentro de 24 h | La respuesta guardada, con `"idempotent_replayed": true`. No se graba nada de nuevo |
| Misma clave, **otra solicitud** | `422 IDEMPOTENCY_KEY_REUSED` |
| Misma clave con la primera llamada aún en curso | La segunda espera a la primera y recibe su respuesta |
| La llamada terminó en error | No se guarda nada: corrija y reintente con la misma clave |

La clave vale por clave de API: dos claves nunca la comparten. Va en el **cuerpo**, que está firmado, y no en un encabezado.

## Evitar sobrescrituras: expected\_version

Para cambiar un lead solo si nadie lo tocó desde que lo leyó, envíe la `version` leída como `expected_version`. Si el lead ya está en otra versión, no se graba nada y la respuesta es `409 VERSION_CONFLICT`, con `details.current_version`. Léalo de nuevo, combine los cambios y reintente.

## Errores

| HTTP | `error.code` | Causa | Qué hacer |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | Campo faltante, de tipo incorrecto o desconocido. `details` lista cada uno | Corrija la solicitud |
| 404 | `LEAD_NOT_FOUND` | No existe ese lead en la empresa de la clave | Revise `lead_id`, o `external_id` + `source` |
| 409 | `LEAD_ARCHIVED` | El lead está archivado | `restore_lead` antes |
| 409 | `VERSION_CONFLICT` | El lead cambió desde `expected_version` | Léalo de nuevo y reintente |
| 409 | `APPROVAL_PENDING` | Ya hay un cambio de etapa de ese lead esperando aprobación | Espere al líder |
| 409 | `NO_APPROVER` | La etapa exige aprobación y el responsable no tiene líder | Pida al admin que defina el líder del equipo |
| 422 | `STAGE_NOT_FOUND` | `stage_id` no es una etapa del embudo del lead | Actualice `list_pipelines` |
| 422 | `STAGE_REQUIREMENT_MISSING` | La etapa exige un documento o un campo | Envíe lo que pide `details` |
| 422 | `NO_STAGE_FOR_OUTCOME` | El embudo no tiene etapa de ganado/perdido | Pida al admin que defina el resultado de la etapa |
| 422 | `OWNER_NOT_FOUND` | `owner_email` no es un usuario activo de la empresa | Use el e-mail de un usuario activo |
| 422 | `AUTHOR_NOT_FOUND` | `author_email` no es un usuario activo de la empresa | Use el e-mail de un usuario activo, u omítalo |
| 422 | `IDEMPOTENCY_KEY_REUSED` | Misma `idempotency_key`, otra solicitud | Use una clave nueva para una operación nueva |

Los errores de autenticación (`401`, y `403 scope_insufficient` cuando a la clave le falta `leads:read` o `leads:write`) y de límite de llamadas (`429`) tienen formato propio, el mismo en todos los endpoints: vea [Autenticación](https://docs.play2sell.com/es/api/authentication.md).


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