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

# Acceso API personal

> Activa credenciales de member, trabaja la cartera de leads y conecta Zapier o Make como member.

El acceso API personal permite a un **member** conectar herramientas (Zapier, Make, n8n, scripts) a **su cartera actual de leads**: los asignados ahora y no deshabilitados.

Empieza **apagado**. Un owner o admin lo enciende en el panel en **Configuración → Claves API** (`Acceso API de members`). Después cada member crea su propia credencial. Apagar el interruptor bloquea el uso nuevo; no deshace lo ya guardado en el CRM. Reactivarlo no recupera las claves revocadas.

> [!WARNING]
>
> El secreto completo se muestra **una sola vez**. Si lo pierdes, revócalo y crea uno nuevo.

## Identidad

Una credencial personal (API key u OAuth) está atada a **una membresía** y **una organización**. Toda lectura y escritura queda en esa cartera.

* Pedir scopes OAuth extra no concede administración. Se recortan al perfil operativo al emitir el token (y otra vez al autenticar si el grant era anterior).
* Ascender a admin **no** amplía una credencial personal ya creada.
* Irse y volver **no** reactiva las claves ni autorizaciones de la membresía anterior. Hay que crear otras.

Ver [Autenticación](https://developers.flowestate.app/es/authentication.md) y [Scopes](https://developers.flowestate.app/es/scopes.md).

## Perfil operativo

Las credenciales personales llevan siempre este set:

`leads:read`, `leads:write`, `pipeline:read`, `sequences:read`, `sequences:write`, `whatsapp:read`, `whatsapp:write`.

Las rutas fuera de este perfil responden `403 FORBIDDEN` (`This credential cannot perform this operation`), aunque el mismo path exista para otras credenciales.

## Qué puedes hacer

| Acción | Método |
| - | - |
| Listar / buscar / ficha / historial | `GET /leads`, `/leads/search`, `/leads/{leadId}`, `/leads/{leadId}/activities` |
| Etapas del pipeline | `GET /pipeline/stages` |
| Nota | `POST /leads/{leadId}/notes` |
| Comunicación registrada (no envía) | `POST /leads/{leadId}/communications` |
| Seguimiento comercial | `PATCH /leads/{leadId}/commercial` |
| Enriquecimiento | `POST /leads/{leadId}/enrichment` |
| Secuencias activas | `GET /sequences` |
| Participaciones de un lead | `GET` / `POST /leads/{leadId}/sequence-contacts` |
| Pausar / reanudar / retirar | `PATCH /leads/{leadId}/sequence-contacts/{contactId}` |
| WhatsApp propio | `GET /whatsapp/accounts`, `POST /whatsapp/send` |
| Probar conexión | `GET /me` |

El detalle está en la referencia de [Leads](https://developers.flowestate.app/es/api-reference/leads.md), [Secuencias](https://developers.flowestate.app/es/api-reference/sequences.md) y [WhatsApp](https://developers.flowestate.app/es/api-reference/whatsapp.md).

Un lead (o una participación en secuencia) que no está en la cartera **actual** responde `404 NOT_FOUND`. Una reasignación o un disable vale de inmediato.

## Seguimiento comercial

`PATCH /leads/{leadId}/commercial` actualiza `status`, `stageId`, `temperature`, `estimatedValue` y el próximo seguimiento (`followUpAt`, `followUpChannel`, `followUpNote`, `completeFollowUp`). No cambia asignación, fuente, consentimientos ni `customFields`.

`stageId` desconocido → `400 INVALID_STAGE`. Un seguimiento activo que se pisaría → `409 FOLLOW_UP_ACTIVE` (complétalo o límpialo antes).

## Enriquecimiento

`POST /leads/{leadId}/enrichment` por defecto solo completa campos **vacíos** (`firstName`, `lastName`, `email`, `phone`, `company`, `jobTitle`, `city`, `state`, `country`).

Para sobrescribir un valor que ya existe, envía `correct: [{ field, expected }]`. Si `expected` ya no coincide → `409 STALE_CORRECTION`. Si el email o el teléfono ya pertenecen a otro lead → `409 IDENTITY_CONFLICT` (no se revela esa otra ficha).

## Secuencias

`GET /sequences` con una credencial personal solo devuelve secuencias **activas** (`running`), como `{ id, name, channel, status }`. No incluye `channelConfig`, criterios de audiencia, throttle ni el progreso agregado de la organización.

* `POST .../sequence-contacts` inscribe un lead de la cartera. Fallos: `400 SEQUENCE_INACTIVE`, `400 INELIGIBLE`, `409 ALREADY_ENROLLED`.
* `pause` es una pausa manual; el progreso se conserva.
* `resume` solo deshace esa pausa si la secuencia sigue activa y el lead sigue siendo elegible. Conserva `scheduledAt` si aún es futuro.
* `withdraw` termina la participación. El member no puede volver a inscribir ese lead en la misma secuencia (`409 WITHDRAWN` si ya terminó).

## WhatsApp

Solo la **cuenta conectada propia** del member. Listar pide `whatsapp:read`; enviar, `whatsapp:write`. Un envío rechazado no llega al proveedor. La auditoría no guarda el cuerpo del mensaje.

Usar la cuenta de otro member o la cuenta global → `403 FORBIDDEN`. Baja del canal → `400 OPTED_OUT`. Cuenta no utilizable → `400 ACCOUNT_UNAVAILABLE`. Número pausado o sin presupuesto → `429 NUMBER_RATE_LIMITED`.

## Auditoría

En **Configuración → Actividad API** queda quién hizo qué. El member ve lo suyo (y nunca el detalle de un lead que ya no es de su cartera). Owners y admins ven la actividad de la organización. Pueden registrarse nombres de campos; el cuerpo de WhatsApp no.

## Cortar el acceso

Apaga **Acceso API de members** y/o revoca claves personales y autorizaciones OAuth. Eso no deshace los cambios de negocio ya persistidos.


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