API de clientes potenciales
Lea los clientes potenciales y actualice su estado desde sus propios sistemas con una clave de API de alcance limitado.
Esta página fue traducida del inglés. Si hay alguna diferencia, prevalece la versión en inglés. Leer en inglés
La API de clientes potenciales permite que su CRM, almacén de datos o automatización lea sus clientes potenciales y actualice su estado.
Cree las claves en Studio, en Integrations → Leads API → New key. Cada clave tiene:
- un nombre;
- permisos:
leads:read(Read leads) y, opcionalmente,leads:write-status(Change lead status); - una caducidad de 30, 90, 180 días o 1 año.
Las claves tienen la forma atl_lead_ seguida de 43 caracteres. Se muestran una sola vez, se almacenan únicamente como una huella digital, se comprueban en cada solicitud y pueden revocarse en cualquier momento (Revoke key). Un entorno de sitio puede tener hasta 20 claves activas. Crear una clave puede requerir una segunda confirmación en su teléfono.
URL base y autenticación
Sección titulada «URL base y autenticación»https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXLas respuestas llevan Cache-Control: private, no-store. Los errores usan el formato application/problem+json de la RFC 9457.
Listar clientes potenciales
Sección titulada «Listar clientes potenciales»GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| Parámetro | Notas |
|---|---|
since |
Solo los clientes potenciales actualizados a partir de este momento. ISO 8601 con zona horaria |
limit |
De 1 a 200; 50 de forma predeterminada |
cursor |
El nextCursor de la respuesta anterior |
Los clientes potenciales llegan empezando por el cambio más antiguo. La respuesta es { "leads": [ … ], "nextCursor": "…" | null }. Siga paginando hasta que nextCursor sea null y almacene el último updatedAt para obtener solo los cambios la próxima vez.
La lista incluye clientes potenciales fusionados, anonimizados y de prueba. Compruebe mergedInto, anonymisedAt e isTest.
Obtener un cliente potencial
Sección titulada «Obtener un cliente potencial»GET /leads/{leadId}
| Campo | Notas |
|---|---|
id, source |
El origen es el formulario o chatbot del que procede el cliente potencial |
form |
{ key, name }, o null para los clientes potenciales del chatbot |
name, email, phone, company, message |
Vacíos después de que la retención haya eliminado los datos personales |
details |
Cualquier otra respuesta |
status |
new, contacted, qualified, won, lost o spam |
isTest |
Envíos de prueba de Studio |
version |
Envíela de vuelta cuando cambie el estado |
mergedInto, anonymisedAt |
Se define cuando el cliente potencial se fusionó o se anonimizó |
createdAt, updatedAt |
Marcas de tiempo ISO 8601 |
Cambiar el estado de un cliente potencial
Sección titulada «Cambiar el estado de un cliente potencial»PATCH /leads/{leadId}/status con { "status": "qualified", "expectedVersion": 4 }. Requiere el permiso Change lead status. El cambio aparece en el historial del cliente potencial como realizado por la clave.
Errores y límites
Sección titulada «Errores y límites»| Estado | Código | Significado |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
Clave ausente, incorrecta, caducada o revocada |
| 403 | CP_FORBIDDEN |
La clave carece del permiso para esta solicitud |
| 404 | CP_NOT_FOUND |
No existe ese cliente potencial en este entorno |
| 409 | CP_VERSION_CONFLICT |
El cliente potencial cambió desde que lo leyó. Léalo de nuevo |
| 422 | REQUEST_SCHEMA_INVALID |
El cuerpo de la solicitud o un parámetro no es válido |
| 422 | CURSOR_INVALID |
No se pudo leer el cursor |
| 429 | RATE_LIMITED |
Más de 300 solicitudes por minuto. Espere y reintente |
El límite de frecuencia se aplica por cada servidor de API de Atlas, así que considere las 300 solicitudes por minuto como un máximo, no como una garantía.