Casos de uso API
La API pública está pensada para integraciones de lectura seguras: reporting financiero, conciliación, portales internos y sincronización controlada con sistemas existentes. Esta guía explica qué patrón encaja en cada caso y qué límites conviene respetar.
Reporting interno y cierre mensual
Útil para equipos que necesitan descargar facturas por periodo, revisar importes cobrados y pendientes, o alimentar un cuadro de mando sin entrar en el dashboard cada vez.
- Consulta `/api/invoices` con `fromDate`, `toDate` y `status` para acotar el periodo de trabajo.
- Filtra por `businessId` cuando el token tenga acceso a más de un negocio.
- Usa `limit` y `offset`; no asumas que un único request debe traer todo el histórico.
- Guarda el momento de extracción y el rango usado para que el cierre sea reproducible.
- Trata los importes de IVA, IRPF y total como campos separados: no recalcules desde el cliente salvo que sea para conciliación propia.
Sincronización con ERP, CRM o BI
Este patrón encaja cuando Pay by idir.ai es la fuente operativa de clientes y facturas, pero otro sistema centraliza contabilidad, relación comercial o analítica.
- Lee clientes desde `/api/clients` y facturas desde `/api/invoices` en procesos programados.
- Usa tokens separados por entorno y por negocio para evitar mezclas de datos.
- Registra la última sincronización correcta y reintenta desde un rango temporal controlado.
- Diseña la integración como idempotente: repetir una importación no debe duplicar clientes ni facturas.
- Respeta los errores 401, 403 y 400 como señales operativas diferentes: credencial inválida, scope incorrecto o parámetros mal formados.
Portales o backoffices propios
Algunos equipos solo necesitan enseñar datos de facturación a finanzas, operaciones o dirección, sin conceder acceso completo a la aplicación.
- Construye vistas de solo lectura para importes, estados, clientes y referencias Veri*factu cuando existan.
- Mantén una capa de permisos propia si el portal interno tiene usuarios con perfiles distintos.
- No expongas el token de API en navegadores, aplicaciones móviles ni repositorios.
- Haz las llamadas desde tu servidor y entrega al frontend solo los campos necesarios.
- Evita replicar toda la aplicación: empieza por listados, filtros y exportables concretos.
Preparación para auditoría o asesoría
Cuando un asesor externo pide datos recurrentes, la API puede reducir envíos manuales siempre que el alcance esté bien definido.
- Crea un token limitado al negocio que corresponda y revócalo si deja de usarse.
- Entrega rangos cerrados de facturas y conserva el criterio de extracción.
- Incluye `invoice_number`, fechas, cliente, bases, impuestos y estado de cobro en el dataset interno.
- Si el asesor necesita documentación completa, combina la API con exportes PDF/CSV del dashboard.
Ciclo recomendado de integración
- Crear un token con alcance mínimo y nombre descriptivo.
- Probar contra un rango pequeño de fechas y validar que los totales coinciden con el dashboard.
- Automatizar con paginación, trazas de ejecución y alertas ante 401/403/400.
- Revisar tokens y jobs programados de forma periódica, especialmente tras cambios de equipo o negocio.
Buenas prácticas de implementación
- Usa un token con el menor alcance posible.
- No expongas tokens en frontend público.
- Documenta reintentos, paginación y errores esperables.
- Acompaña cada caso de uso con ejemplos y criterios de seguridad.
- Valida UUID, fechas y estados antes de llamar a la API para evitar errores de integración repetidos.
- Mantén un inventario de qué sistema usa cada token y quién es responsable de revocarlo.