Paybyidir.ai

Documentación

Guías oficiales para configurar y usar Pay by idir.ai.

API pública

La API pública permite consultar facturas y clientes desde integraciones externas usando tokens con scope de negocio. Está diseñada para lectura operativa y reporting; las mutaciones principales siguen viviendo en el dashboard y en las acciones protegidas de la aplicación.

Autenticación y alcance

  • Genera tokens desde el dashboard de gestión de API y cópialos en el momento de creación; el valor completo no se vuelve a mostrar.
  • Envía el token con `Authorization: Bearer <token>` en cada request.
  • Cada token queda asociado a uno o varios negocios. Si pides un `businessId` fuera de su scope, la API responde 403.
  • Los tokens revocados o caducados responden 401 y deben sustituirse, no reintentarse indefinidamente.

Endpoints disponibles

GET/api/invoices

Listar facturas

Devuelve facturas visibles para el token, con importes, estado, cliente, negocio y campos Veri*factu cuando existan registros asociados.

  • `businessId` filtra a un negocio concreto dentro del scope del token.
  • `status` acepta `draft`, `pending`, `paid`, `overdue` o `cancelled`.
  • `fromDate` y `toDate` usan formato `YYYY-MM-DD` sobre la fecha de factura.
  • `limit` acepta de 1 a 1000 resultados; por defecto se usan 200.
  • `offset` permite paginar desde 0.
GET/api/clients

Listar clientes

Devuelve clientes del negocio o negocios autorizados, con identificador interno, nombre, email si existe y fecha de creación.

  • `businessId` reduce la consulta a un negocio dentro del scope.
  • `limit` acepta de 1 a 1000 resultados; por defecto se usan 200.
  • `offset` permite paginar resultados.
GET/api/openapi

OpenAPI

Expone la especificación OpenAPI 3.0.3 para herramientas, documentación interactiva y generación de clientes internos.

  • No requiere token para leer la especificación pública.

Respuestas y errores

  • `200` devuelve `data`, `paging` y `scope` para que puedas saber cuántos resultados llegaron y qué negocios cubre el token.
  • `400` indica parámetros inválidos, por ejemplo fechas fuera de formato o `limit` fuera de rango.
  • `401` indica token ausente, inválido, revocado o caducado.
  • `403` indica que el token es válido, pero no tiene permiso para el negocio solicitado.

Ejemplo rápido

Usa dominios, UUID y tokens reales de tu entorno. Nunca pegues el token en código cliente.

curl -H "Authorization: Bearer idir_api_..." \
  "https://your-domain.example/api/invoices?businessId=<uuid>&status=paid&fromDate=2026-01-01&toDate=2026-03-31&limit=100"

Checklist antes de producción

  • Guardar el token en un gestor de secretos o variable de entorno del servidor.
  • Crear un token distinto por integración y por entorno.
  • Registrar errores, latencia, paginación y número de resultados importados.
  • Probar 401, 403 y 400 para que el sistema consumidor falle de forma clara.
  • Revocar tokens que ya no tengan dueño operativo.
Abrir OpenAPI interactivo