Saltar al contenido principal
Pruebe solicitudes firmadas en el navegador en el API Sandbox: pegue la clave y el secreto, y el playground firma solo.
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.
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.

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).
  • 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 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.

El lead

Toda acción que devuelve un lead devuelve este formato.

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.
requirements indica lo que 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).

Accion: get_lead

string
ID de SalesOS (UUID). O envíe external_id.
string
Su ID (hasta 255).
string
Junto con external_id. Por defecto api.
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

object
Todos opcionales, combinados con Y. Un filtro desconocido devuelve 400, para que un error de tipeo nunca devuelva todo.
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.
integer
1–500, por defecto 100. Por encima de 500, se reduce a 500.
string
El next_cursor de la página anterior.
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.

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.
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 y expected_version, opcionales;
  • corre en una sola transacción: graba todo o nada.
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

Solicitud

string
De dónde vienen los leads, en minúsculas: letras, números, _ . - (hasta 60). Por defecto api.
string
array
requerido
Lista de leads (hasta 100).
string
requerido
ID único del lead en su sistema (hasta 255).
string
Hasta 200. Para crear, envíe al menos uno entre name, email y phone.
string
E-mail del cliente.
string
Con código de país, p. ej. +5511987654321. Sin él, vale el país de la empresa.
string
CPF (11) o CNPJ (14) dígitos; la puntuación se ignora.
string
Hasta 200.
string
Hasta 300.
string[]
Hasta 20 etiquetas, 60 caracteres cada una.
string
Responsable. Desconocido o inactivo: el lead va al responsable por defecto, con aviso.
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.
object
Etiqueta → texto. Hasta 50 campos, 1.000 caracteres cada uno.
object
utm_source, utm_medium, utm_campaign, utm_term, utm_content, landing_page, referrer, form_id (500 caracteres cada uno).

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.
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.
object
requerido
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).
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.
string
requerido
ID de la etapa, de list_pipelines.
string
Cuando la etapa exige un documento: enlace http(s) al documento.
string | number
Cuando la etapa exige un campo (requirements.field).
string
Cuando la etapa de destino tiene outcome: "lost" (1–500 caracteres).
number
Actualiza el valor del lead junto con el cambio.
string
Mensaje al líder cuando la etapa exige aprobación (hasta 1.000).
Un requisito faltante devuelve 422 STAGE_REQUIREMENT_MISSING, y details indica qué enviar:

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.
string
requerido
won o lost.
string
Solo con lost.
number
Valor final.
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).
string
El lead. O envíe lead_external_id + lead_source.
string
Su ID del lead (con lead_source, por defecto api).
string
requerido
note, call, whatsapp, email, meeting o visit.
string
Hasta 5.000 caracteres. Obligatoria en note.
string
Cuándo pasó (ISO 8601). Por defecto: ahora. No puede estar en el futuro.
string
Quién lo hizo: un usuario activo de la empresa. Por defecto: el responsable del lead.
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.
string
inbound u outbound (llamadas, mensajes).
integer
0–86.400.
Respuesta 201 (creada) o 200 (ya existía):

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.
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.
string[]
Solo estos tipos, p. ej. ["note", "call"].
integer
1–500, por defecto 100.
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. 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

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.