Skip to main content
El portal del cliente es una página alojada en Finseed desde la que cualquier cliente puede ver y descargar sus facturas. Tú generas el enlace mediante la API y se lo envías; el cliente accede directamente, sin credenciales ni contraseñas. Toda la integración se reduce a una llamada. El contrato completo del endpoint, con los parámetros y todas las respuestas posibles, está en la API Reference.

​
Cómo funciona

El flujo tiene tres pasos:
  1. Tu servidor llama a POST /v1/customer_portal/sessions con el identificador externo del cliente.
  2. La API devuelve una URL firmada con una validez de una hora.
  3. Envías esa URL a tu cliente. Al abrirla, ve la lista de sus facturas y puede descargar cada una en PDF.
El cliente nunca ve tu clave API ni tiene acceso a los datos de otros clientes. El enlace es nominativo y caduca automáticamente.

​
Antes de empezar

La llamada a la API se autentica con una clave API. Si aún no tienes una, créala antes de continuar:
  1. Ve a Configuración > Claves API.
  2. Pulsa Nueva clave y dale un nombre descriptivo.
  3. Copia la clave en el momento. Solo se muestra una vez.
La clave está limitada a un entorno: una clave de test (ev_test_…) solo ve clientes de test y una clave de producción (ev_live_…) solo ve clientes reales. Genera el enlace siempre desde tu servidor y guarda la clave como un secreto, nunca en código del lado del cliente. El proceso completo está en Claves API.

​
Crear una sesión

Llama al endpoint con tu clave API y el identificador externo del cliente. El external_customer_id es el mismo que usas en tu integración (el identificador del cliente en Shopify, Stripe, tu base de datos, etc.).
La clave se envía como bearer token y está limitada a un único entorno: una clave de test solo ve clientes de test y una clave de producción solo ve clientes de producción. Consulta Authentication para los detalles. La respuesta incluye la URL del portal y la fecha de caducidad:
Envía la url a tu cliente por el canal que uses habitualmente: email de confirmación, área de cliente, notificación push, etc. La sesión se crea para cualquier external_customer_id, aunque ese cliente todavía no tenga facturas registradas en Finseed: el portal las consulta en el momento. Si no hay ninguna, muestra una lista vacía.

​
Cuándo añadir integration_id

Si tu entorno tiene más de una integración, añade el campo integration_id para indicar a qué integración pertenece el cliente:
Es necesario porque el mismo external_customer_id puede referirse a clientes distintos en integraciones distintas: los identificadores solo son únicos dentro de cada integración (por ejemplo, el cliente 42 de tu tienda WooCommerce y el cliente 42 de tu tienda Shopify son personas diferentes). Con una sola integración puedes omitirlo. Si tu entorno tiene varias integraciones y no envías integration_id, la API responde con 409 customer_ambiguous. Copia el valor desde Configuración > Integraciones: abre la integración y pulsa el icono de copiar junto a su ID. La lista completa de códigos está en Errors.

​
Idioma del portal

Para indicar el idioma del cliente, añade el campo locale al crear la sesión:
Pasa el idioma que tu cliente ya usa en tu tienda, como texto. Los valores admitidos son es y en, o una variante regional como es-ES o en_US: el portal usa el idioma principal de esa variante. Si omites el campo, o envías un idioma no reconocido, el portal usa el idioma del navegador del cliente y, si tampoco lo reconoce, español. Si envías un valor que no es texto (un número, por ejemplo), la petición completa falla con 400 invalid_request. El campo locale solo cambia el idioma de la página del portal. La factura en PDF se descarga en el idioma con el que se emitió: consulta Personalización de facturas. El cliente puede cambiar el idioma en cualquier momento con el selector que aparece en la parte superior del portal.

​
Qué ve el cliente

Al abrir el enlace, el cliente ve una tabla con todas sus facturas: número, fecha, estado e importe. Desde ahí puede descargar cada factura en PDF con un solo clic. Si el enlace ha caducado o no es válido, la página le indica que solicite uno nuevo.

​
Caducidad y seguridad

Cada sesión caduca una hora después de generarse. Pasado ese tiempo el enlace deja de funcionar. Si el cliente lo necesita de nuevo, genera una nueva sesión. El enlace es un token firmado criptográficamente. Finseed verifica la firma y la caducidad en cada visita. Un token alterado o expirado es rechazado sin revelar cuál de las dos comprobaciones ha fallado. Genera siempre el enlace bajo demanda desde tu servidor, nunca lo almacenes como URL permanente.