Integraciones

La API de integraciones permite a un sistema externo (por ejemplo un CRM) crear y gestionar empresas, sincronizar empleados y abrir sesión a sus usuarios en FichaChat sin que tengan que iniciar sesión a mano, tanto por enlace directo como incrustando la app en un iframe.

URL base

https://api.fichachat.com/api/v1/integrations/

Todas las respuestas son JSON. Las listas están paginadas al estilo Django REST Framework (count, next, previous, results; 20 elementos por página).

Autenticación: claves de API

Todos los endpoints de integración, salvo el intercambio de tokens SSO, requieren una clave de plataforma en la cabecera:

X-API-Key: fc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Características de las claves:

• Formato fc_ seguido de 43 caracteres aleatorios.
• Son de plataforma: una misma clave puede gestionar varias empresas.
• Se almacenan hasheadas; el valor solo se muestra una vez, al crearla.
• Ámbito (scope): read (solo lectura) o write (lectura y escritura, por defecto).
• Planes permitidos (allowed_plans): lista de planes de suscripción que la clave puede asignar a las empresas que crea (por ejemplo ["bikecrm"]).
• Orígenes permitidos (allowed_origins): dominios autorizados a incrustar FichaChat en un iframe con esa clave.

Las claves las crea el equipo de FichaChat para cada integrador. Para solicitar una: contacto@smartupsoft.com.

Errores

Código	Significado
200	Correcto
201	Creado
204	Sin contenido (borrado correcto)
400	Petición inválida (error de validación)
401	Clave de API ausente o inválida
403	Permisos insuficientes (por ejemplo, clave read en una escritura)
404	No encontrado
500	Error del servidor

Formato de los errores:

{ "error": "Mensaje de error" }

o, en errores de validación, un objeto con los campos afectados:

{ "email": ["Introduce una dirección de correo válida."] }

Límites de uso

Actualmente no se aplican límites de peticiones en la API de integraciones. Los valores orientativos previstos son 60/min para la creación de tokens SSO, 120/min para su intercambio y 1000/hora para el resto; no dependas de que estén activos hoy.

Buenas prácticas

1. Guarda la clave en el servidor. Nunca en código de frontend ni en la app móvil.
2. Usa employee_code como identificador estable entre tu sistema y FichaChat.
3. Los tokens SSO caducan a los 5 minutos: genera uno nuevo en cada intento de acceso, no los almacenes.
4. Reintenta ante errores de red y registra los errores que devuelva la sincronización masiva.

Secciones

• Empresas y empleados: alta y actualización de empresas, CRUD y sincronización masiva de empleados.
• SSO e iframes: tokens de un solo uso, enlaces de acceso directo, iframe del empleado y del responsable.
• Acceso de empleados por subdominio: endpoints públicos del portal <slug>.web.fichachat.com.