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.Antes de empezar
- Un endpoint, una acción por llamada. Toda llamada es un
POSTahttps://api.play2sell.com/functions/v1/default-integrationcon"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 exigeleads:write. Uno no incluye al otro, y ninguno abresync_collaboratorsnisync_activities. Una clave sin el alcance recibe403concode: "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_pipelinesy lea ganado/perdido enstage.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 yget_lead aceptan una de las formas:
lead_id: el ID de SalesOS (UUID);external_id+source: su ID, dentro delsourceusado al crearlo (por defectoapi).
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
200: { "data": { "found": true, "lead": { … } } }, o { "found": false, "lead": null } cuando el lead no existe en la empresa.
Accion: list_leads
Todos opcionales, combinados con Y. Un filtro desconocido devuelve
400, para que un error de tipeo nunca devuelva todo.{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }. Por defecto: updated_at ascendente cuando hay updated_since; si no, los más nuevos primero.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_keyyexpected_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 lastage_id enviada.
Cómo se reconoce el lead
Para cada ítem buscamos un lead activo de la empresa en este orden:- el mismo
external_iden el mismosource(dos orígenes nunca se mezclan); - el mismo
email(sin distinguir mayúsculas); - el mismo
phone.
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
Opcional. Vea Reintentar sin duplicar.
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.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 constatus: "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.
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).200 con { "data": { "result": "updated", "lead": { … } } }.
Accion: move_lead_stage
Mueve el lead astage_id, una etapa del propio embudo del lead. Avanzar sigue las reglas de la etapa exactamente como en la app; retroceder siempre está permitido.
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 eseoutcome, con las mismas reglas de move_lead_stage.
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 desync_activities).
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.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.
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.{ "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 unaidempotency_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 laversion 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.
