Saltar al contenido principal
Un pool de round robin distribuye los leads entrantes entre una lista ordenada de participantes mediante rotación por puntero: cada pool recuerda a quién le toca el siguiente turno, asigna el lead a ese participante y luego avanza el puntero al siguiente (volviendo al primero después del último). El orden de rotación es el orden del arreglo participantIds. Las conexiones enrutan los leads entrantes hacia un pool según su origen — un webhook genérico, una página/formulario/anuncio/campaña de meta, un proveedor de automation (Zapier, Make, n8n) o un workflow. Cuando llega un lead, FlowEstate elige el pool activo cuya conexión coincide con el origen del lead y lo asigna a través de la rotación de ese pool. Cada endpoint en esta página opera dentro del tenant de la organización que llama — no puedes leer ni escribir pools de round robin de otra organización con la misma key.
Ejecuta el round robin de punta a punta por REST — sin webhook universal. Puedes dejar que POST /leads cree, asigne y emita lead.assigned en una sola llamada (pasa roundRobinId para apuntar a un pool específico), o crear el lead primero y llamar a POST /round-robin/assign. Ambos caminos emiten el evento lead.assigned que dispara tus notificaciones al agente downstream. Un pool sin conexiones y con assignInboundLeads: true recibe estos leads como comodín inbound genérico.

Listar pools

Scope: round-robin:read. Lista los pools de round robin de la organización, del más reciente al más antiguo.

Query parameters

Request

Response 200

nextParticipantOrder es el valor de orden (base 1) del participante que recibirá el siguiente lead. participantCount cuenta solo a los participantes activos.

Crear un pool

Scope: round-robin:write

Request body

Objeto de conexión

Cada entrada en connections (y el body de POST .../connections) tiene esta forma:
Solo un pool por organización puede tener la conexión genérica webhook, y la integración de webhook universal de leads de la organización debe estar habilitada. Las conexiones duplicadas (idénticas campo por campo) se rechazan.

Request

Response 201

Errores comunes

  • 400 VALIDATION_ERROR — body inválido (participantIds vacío, conexión de automation sin provider, conexión de workflow sin workflowId, etc.).
  • 400 BAD_REQUEST — un participante o follower no es miembro de la organización, participantes duplicados o conexiones duplicadas.
  • 400 BAD_REQUEST — se solicitó una conexión webhook pero la integración de webhook universal de leads no está habilitada.
  • 409 CONFLICT — la conexión webhook universal ya está asignada a otro pool.

Obtener un pool

Scope: round-robin:read. Devuelve el pool con sus participantes ordenados, sus conexiones, un resumen settings y las estadísticas de asignación stats. 404 NOT_FOUND si el pool no existe o pertenece a otra organización.

Response 200

Los participantes se devuelven en orden de rotación (order ascendente).

Actualizar un pool

Scope: round-robin:write. El body es el de crear pero sin la obligatoriedad de name — todos los campos son opcionales; envía solo lo que quieras cambiar. 404 NOT_FOUND si el pool no existe o pertenece a otra organización.

Request

Reordenar la rotación y desactivar el pool:

Response 200

Errores comunes

  • 400 VALIDATION_ERROR / 400 BAD_REQUEST — mismas reglas de validación que crear (membresía, duplicados, requisitos de conexión).
  • 409 CONFLICT — la conexión webhook universal ya pertenece a otro pool.

Eliminar un pool

Scope: round-robin:write. Elimina el pool junto con sus participantes, conexiones e historial de asignaciones. 404 NOT_FOUND si el pool no existe o pertenece a otra organización.

Response 200


Agregar una conexión

Scope: round-robin:write. Agrega una única conexión de enrutamiento a un pool existente. El body es el objeto de conexión. 404 NOT_FOUND si el pool no existe o pertenece a otra organización.

Request

Response 201

Errores comunes

  • 400 VALIDATION_ERROR — conexión de automation sin provider, o conexión de workflow sin workflowId.
  • 400 BAD_REQUEST — se solicitó una conexión webhook pero la integración de webhook universal de leads no está habilitada.
  • 409 CONFLICT — ya existe una conexión idéntica en este pool, o la conexión webhook universal pertenece a otro pool.

Eliminar una conexión

Scope: round-robin:write. 404 NOT_FOUND si la conexión no existe en ese pool o pertenece a otra organización.

Response 200


Listar asignaciones

Scope: round-robin:read. Lista el historial de asignaciones del pool, de la más reciente a la más antigua.

Query parameters

Response 200

turnOrder es el valor de orden del participante al momento de la asignación. metadata es una cadena codificada en JSON (o null) que describe cómo el lead coincidió con una conexión.

Asignar un lead

Scope: round-robin:write. Pasa un lead por la rotación por puntero del pool activo que coincide, lo asigna al siguiente participante elegible, avanza el puntero y emite lead.assigned. Úsalo cuando el lead ya existe (si no, POST /leads hace crear + asignar en una sola llamada).

Request body

Request

Response 200

Cuando se asigna un participante:
Cuando no ocurre ninguna asignación — ningún pool activo coincide con el origen, el pool encontrado no tiene participantes elegibles, o el lead ya tiene un responsable asignado — la respuesta es:
El lead solo se asigna si actualmente no tiene responsable. Un lead que ya tiene dueño devuelve { "assigned": false } y queda intacto.

Efectos secundarios de webhooks

Cuando la asignación es exitosa, se dispara un evento lead.assigned (con autoAssigned: true) y se registra una actividad assigned en la línea de tiempo del lead. No se emite nada cuando la respuesta es { "assigned": false }.

Errores comunes

  • 400 VALIDATION_ERROR — leadId no es un UUID, o source no es un valor conocido.
  • 404 NOT_FOUND — el lead no existe o pertenece a otra organización.