API Reference

Fynex ofrece una REST API para acceso programático. Todos los endpoints requieren autenticación mediante un token JWT de Supabase enviado en el header Authorization: Bearer <token>.

Base URL:

Development: http://localhost:3001
Production: https://api.fynex.solutions

Dispatch

Send Email

POST /api/dispatch/email

Parameter	Type	Required	Description
`account_id`	UUID	Yes	Cuenta objetivo
`template_id`	UUID	No	Plantilla de mensaje a usar
`action_type`	string	No	Tipo de acción (default: `reminder`)

Responses: 200 Email enviado, 401 Unauthorized, 422 Dispatch bloqueado.

Send SMS

POST /api/dispatch/sms

Parameter	Type	Required	Description
`account_id`	UUID	Yes	Cuenta objetivo
`template_id`	UUID	No	Plantilla de mensaje a usar
`action_type`	string	No	Tipo de acción (default: `reminder`)

Responses: 200 SMS enviado, 422 Dispatch bloqueado.

Send WhatsApp

POST /api/dispatch/whatsapp

Parameter	Type	Required	Description
`account_id`	UUID	Yes	Cuenta objetivo
`template_id`	UUID	No	Plantilla de mensaje a usar
`action_type`	string	No	Tipo de acción (default: `reminder`)

Responses: 200 Mensaje WhatsApp enviado, 422 Dispatch bloqueado.

Initiate Voice Call

POST /api/dispatch/voice

Parameter	Type	Required	Description
`account_id`	UUID	Yes	Cuenta objetivo
`agent_type`	string	No	`ai` (default) o `human`
`supervisor_user_id`	UUID	No	User ID para llamadas supervisadas
`voice_opening_mode`	string	No	Solo IA: `inherit` (default), `callee_first` o `agent_first`. Se ignora si `agent_type` es `human`.

Responses: 200 Llamada iniciada (incluye call_sid y conversation_id), 422 Dispatch bloqueado, 502 Error del proveedor.

Dispatch Validation

Todos los endpoints de dispatch aplican estas reglas antes de enviar:

Opt-out — Bloqueado si el contacto optó por no recibir más mensajes.
Frequency limits — Bloqueado si se excedería el máximo de contactos por día/semana.
Allowed hours — Bloqueado si está fuera del horario de contacto configurado por la organización.
Account paused — Bloqueado si el estado de la cuenta es paused.

Cuando se bloquea, la respuesta incluye { "blocked": true, "error": "reason" }.

Admin

Phone Numbers

POST /api/admin/phone-numbers

Parameter	Type	Required	Description
`action`	string	Yes	`search`, `buy` o `release`
`country`	string	No	Código de país para búsqueda
`areaCode`	string	No	Código de área para búsqueda
`phoneNumber`	string	No	Número a comprar o liberar
`organizationId`	UUID	No	Organización a asignar
`channelConfigId`	UUID	No	Channel config a actualizar

Email Domains

POST /api/admin/email-domains

Parameter	Type	Required	Description
`action`	string	Yes	`create` o `verify`
`domain`	string	No	Nombre del dominio
`organizationId`	UUID	No	Organización
`channelConfigId`	UUID	No	Channel config

ElevenLabs Agent

POST /api/admin/elevenlabs-agent

Parameter	Type	Required	Description
`action`	string	Yes	`provision`, `status` o `set_agent_id`
`organizationId`	UUID	No	Organización (suele inferirse del auth)
`agent_id`	string	Para `set_agent_id`	Agent ID de ElevenLabs a guardar en el canal de voz

provision crea o actualiza el agente ConvAI y, si hay número Twilio configurado pero aún no hay ID de teléfono en ElevenLabs, registra el número automáticamente. La respuesta puede incluir phone_number_id.

set_agent_id está pensado para organizaciones autogestionadas con agente propio.

Configuración de voz

GET /api/admin/voice-config
PATCH /api/admin/voice-config

GET devuelve los defaults actuales: llm, voice_id, voices (mapa por idioma), voice_opening_mode, agent_id, org_language, supported_llms, curated_voices.

PATCH actualiza organización y canal de voz en un solo request. Enviá al menos un campo:

Campo	Tipo	Descripción
`llm`	string	Id del LLM de IA conversacional (validado contra la lista soportada)
`voice_id`	string	Voz ElevenLabs por defecto para el idioma principal de la org
`voices`	object	Mapa código de idioma → id de voz ElevenLabs
`voice_opening_mode`	string	`callee_first` o `agent_first`
`agent_id`	string	Id de agente ElevenLabs (p. ej. modo autogestión)

Campañas

Crear Campaña

POST /api/admin/campaigns

Parameter	Type	Required	Description
`name`	string	Yes	Nombre de la campaña (1-200 caracteres)
`objective`	string	No	Objetivo de la campaña (máx 1000 caracteres)
`strategy_id`	UUID	No	Estrategia a asignar (requerida para activar)
`status`	string	No	Estado inicial (por defecto: `draft`)
`start_date`	string	No	Fecha de inicio (YYYY-MM-DD)
`end_date`	string	No	Fecha de fin (YYYY-MM-DD, debe ser >= inicio)

Responses: 201 Campaña creada, 422 Validación fallida (fechas inválidas, falta estrategia para estado activo).

Actualizar Campaña

PATCH /api/admin/campaigns/:id

Acepta los mismos campos que la creación. Las transiciones de estado son validadas:

draft → active (requiere strategy_id)
active → paused (cancela items pendientes de la cola)
active → completed
paused → active, paused → completed

Responses: 200 Campaña actualizada, 422 Transición de estado inválida o error de validación.

Eliminar Campaña

DELETE /api/admin/campaigns/:id

Elimina la campaña. Todas las cuentas asignadas quedan con campaign_id en null. Los items pendientes de la cola para esta campaña se cancelan.

Responses: 200 Campaña eliminada.

Resumen de Campaña

GET /api/admin/campaigns/:id/summary

Devuelve métricas computadas de la campaña:

Campo	Tipo	Descripción
`campaign`	object	Detalles de la campaña (id, nombre, estado, fechas)
`account_count`	number	Total de cuentas asignadas a esta campaña
`contacted_count`	number	Cuentas con al menos una interacción
`promise_count`	number	Promesas de pago de cuentas de la campaña
`total_recovered`	number	Suma de pagos de cuentas de la campaña
`contact_rate`	number	`contacted_count / account_count` (0.0 a 1.0)

Responses: 200 Datos del resumen.

Motor de Ejecución

Pausar Ejecución

POST /api/admin/execution/pause

Pausa el despacho automático para tu organización. Los items de la cola permanecen pero no se procesan.

Responses: 200 Ejecución pausada.

Reanudar Ejecución

POST /api/admin/execution/resume

Reanuda el procesamiento automático de despacho.

Responses: 200 Ejecución reanudada.

Estado de la Cola

GET /api/admin/execution/status

Devuelve conteos de items pendientes, en proceso, completados, fallidos y omitidos de hoy, más el flag de pausa.

Encolar Cuentas

POST /api/admin/execution/enqueue

Parameter	Type	Required	Description
`campaign_id`	UUID	No	Limitar a una campaña

Activa manualmente la evaluación y encolamiento de cuentas. Las cuentas elegibles se agregan a la cola de ejecución. Cuando se proporciona campaign_id, la campaña debe estar active y dentro de su rango de fechas.

Responses: 200 Devuelve { enqueued: <count> }, 422 Campaña no activa o fuera de rango de fechas.

Operaciones Masivas

Acciones Masivas en Cuentas

POST /api/admin/bulk/accounts

Parameter	Type	Required	Description
`account_ids`	UUID[]	Yes	Cuentas a modificar (máx 500)
`action`	string	Yes	`pause`, `resume`, `assign_campaign`, `assign_strategy`, `change_status`
`campaign_id`	UUID	No	Requerido para `assign_campaign`
`strategy_id`	UUID	No	Requerido para `assign_strategy`
`status`	string	No	Requerido para `change_status`

Responses: 200 Devuelve { affected: <count> }.

Facturación

Crear Sesión de Checkout

POST /api/billing/checkout

Parameter	Type	Required	Description
`price_id`	string	Yes	Stripe price ID
`success_url`	URL	Yes	URL de redirección tras el pago
`cancel_url`	URL	Yes	URL de redirección al cancelar

Responses: 200 Devuelve { url: "https://checkout.stripe.com/..." }, 503 Facturación no configurada.

Portal de Facturación

POST /api/billing/portal

Parameter	Type	Required	Description
`return_url`	URL	Yes	URL de redirección tras el portal

Responses: 200 Devuelve { url: "https://billing.stripe.com/..." }, 503 Facturación no configurada.

Notificaciones

Listar Notificaciones

GET /api/notifications

Devuelve todas las notificaciones del usuario autenticado, ordenadas de más reciente a más antigua.

Marcar Notificación como Leída

PATCH /api/notifications/:id/read

Marca una notificación individual como leída.

Marcar Todas como Leídas

POST /api/notifications/mark-all-read

Marca todas las notificaciones no leídas del usuario autenticado como leídas.

Voice

Get Signed URL

POST /api/voice/signed-url

Devuelve una URL WebSocket firmada para sesiones de voz desde el navegador.

Parameter	Type	Required	Description
`organization_id`	UUID	Yes	Organización

Response: { "signedUrl": "wss://..." }

Check Capabilities

POST /api/voice/capabilities

Verifica si una organización está lista para hacer llamadas de voz (credenciales Twilio, agente ElevenLabs, número de teléfono).

Parameter	Type	Required	Description
`organization_id`	UUID	Yes	Organización

Interacciones

Recuperar Transcripción de Voz

POST /api/interactions/:id/refresh-voice

Obtiene los datos de la conversación desde ElevenLabs para una interacción de voz cuyo webhook post-llamada no se recibió. Actualiza la transcripción, disposición, resultado de contacto, sentimiento y todos los metadatos de análisis. Si el paso de la estrategia estaba trabado en waiting_response, se desbloquea automáticamente.

Este endpoint es idempotente — llamarlo sobre una interacción que ya tiene transcripción la sobrescribe con los datos más recientes de ElevenLabs.

Parámetro	Tipo	Ubicación	Requerido	Descripción
`id`	UUID	path	Sí	ID de interacción

Respuestas:

Código	Descripción
200	Transcripción recuperada; devuelve la interacción actualizada
404	Interacción no encontrada o de otra organización
422	No es interacción de voz, sin conversation ID, o llamada aún en curso
502	Falló la consulta a la API de ElevenLabs

API Pública v1

La API v1 proporciona acceso programático para integración con sistemas externos. Autenticación mediante header X-API-Key o Bearer JWT.

Autenticación

Método	Header	Caso de uso
API Key	`X-API-Key: fynex_pk_...`	Integraciones máquina a máquina
JWT	`Authorization: Bearer <token>`	Acceso desde navegador

Cuentas

POST /api/v1/accounts

Crear o actualizar una cuenta. Si se proporciona external_id y coincide con una cuenta existente, la actualiza.

Parámetro	Tipo	Requerido	Descripción
external_id	string	No	ID único de tu sistema para esta cuenta
source_system	string	No	Etiqueta del sistema de origen
contact	object	Sí	Datos de contacto (nombre requerido, email/teléfono/whatsapp opcionales)
total_amount	number	Sí	Monto total de la deuda
pending_balance	number	No	Por defecto igual a total_amount
reference	string	No	Número de referencia legible
currency	string	No	Código ISO 4217 (default: ARS)

GET /api/v1/accounts

Listar cuentas con paginación.

Parámetro	Tipo	Requerido	Descripción
limit	number	No	Máximo de resultados (default 50, máx 1000)
offset	number	No	Saltar los primeros N resultados
status	string	No	Filtrar por collection_status
external_id	string	No	Filtrar por external_id

GET /api/v1/accounts/:id

Obtener cuenta por ID de Fynex. Usá ?by=external_id para buscar por ID externo.

PATCH /api/v1/accounts/:id

Actualizar campos de la cuenta.

Contactos

POST /api/v1/contacts
GET /api/v1/contacts
GET /api/v1/contacts/:id
PATCH /api/v1/contacts/:id

Mismo patrón que cuentas. Soporta upsert por external_id.

Pagos

POST /api/v1/payments

Registrar un pago externo. Proporcioná account_id o account_external_id.

Importación y Exportación

POST /api/v1/import

Iniciar importación masiva asíncrona. Devuelve { job_id, status }.

GET /api/v1/import/:jobId

Consultar progreso del trabajo de importación.

POST /api/v1/export/accounts

Exportar cuentas como JSON o CSV con filtros.

Suscripciones a Webhooks

POST /api/v1/webhooks
GET /api/v1/webhooks
PATCH /api/v1/webhooks/:id
DELETE /api/v1/webhooks/:id
POST /api/v1/webhooks/:id/test

Gestionar suscripciones de webhooks salientes.

Límites de Tasa

Todos los endpoints v1: 100 solicitudes cada 15 minutos por API key.

Webhooks

Estos endpoints reciben callbacks de proveedores externos. No son llamados por aplicaciones cliente.

Endpoint	Provider	Validation
`POST /api/webhooks/twilio`	Twilio	HMAC-SHA1 signature
`POST /api/webhooks/resend`	Resend	Svix HMAC-SHA256
`POST /api/webhooks/elevenlabs`	ElevenLabs	HMAC-SHA256
`POST /api/webhooks/agent-tool-handler`	ElevenLabs	HMAC-SHA256
`POST /api/webhooks/stripe`	Stripe	Stripe signature

System

Health Check

GET /health

Devuelve { "status": "ok", "timestamp": "..." } cuando el servidor está corriendo.

API Reference ​

Dispatch ​

Send Email ​

Send SMS ​

Send WhatsApp ​

Initiate Voice Call ​

Dispatch Validation ​

Admin ​

Phone Numbers ​

Email Domains ​

ElevenLabs Agent ​

Configuración de voz ​

Campañas ​

Crear Campaña ​

Actualizar Campaña ​

Eliminar Campaña ​

Resumen de Campaña ​

Motor de Ejecución ​

Pausar Ejecución ​

Reanudar Ejecución ​

Estado de la Cola ​

Encolar Cuentas ​

Operaciones Masivas ​

Acciones Masivas en Cuentas ​

Facturación ​

Crear Sesión de Checkout ​

Portal de Facturación ​

Notificaciones ​

Listar Notificaciones ​

Marcar Notificación como Leída ​

Marcar Todas como Leídas ​

Voice ​

Get Signed URL ​

Check Capabilities ​

Interacciones ​

Recuperar Transcripción de Voz ​

API Pública v1 ​

Autenticación ​

Cuentas ​

Contactos ​

Pagos ​

Importación y Exportación ​

Suscripciones a Webhooks ​

Límites de Tasa ​

Webhooks ​

System ​

Health Check ​