Introducción a la API

La API Externa de FileXpress permite que sistemas de terceros (POS, ERP, tiendas en línea, relojes biométricos, sistemas de nómina o de BI) se integren con un negocio de FileXpress para:

Facturación: emitir ventas (DTE), registrar compras y gestionar clientes, proveedores y productos.
Recursos Humanos: consultar empleados y planillas, enviar marcaciones de asistencia y crear solicitudes de permiso.
Contabilidad: consultar el catálogo de cuentas y los estados financieros, y crear partidas en borrador.

URL base

https://api.filexpress.app/api/external

Todas las rutas de esta documentación son relativas a esa URL. Los cuerpos y respuestas son JSON (Content-Type: application/json).

Probar la API

Cada endpoint tiene una página en Referencia interactiva con un playground: ingresas tu API Key, completas los parámetros y ejecutas la solicitud real desde el navegador. Cada página incluye ejemplos de código (cURL, JavaScript, Python y PHP) y ejemplos de respuesta exitosa y de error.

El playground envía solicitudes reales al negocio de tu API Key. Usa una integración del ambiente de pruebas para experimentar, nunca la de producción.

Ambiente de pruebas

FileXpress no usa una URL distinta para pruebas: el ambiente lo define el negocio al que pertenece la integración.

Ambiente	Uso	Documentos electrónicos
Pruebas (`00`)	Desarrollo e integración	Se transmiten al ambiente de pruebas de Hacienda. No tienen validez fiscal.
Producción (`01`)	Operación real	Se transmiten a Hacienda con validez fiscal.

Para desarrollar tu integración:

Solicita a soporte un negocio en ambiente de pruebas

Escribe a soporte@filexpress.com indicando el nombre de tu integración y los módulos que vas a usar.

Crea una integración en ese negocio y usa su API Key en tu desarrollo y en el playground

Al pasar a producción, crea la integración en el negocio real

Solo cambia la API Key: la URL y los endpoints son los mismos.

El ambiente actual de un negocio se ve en Soporte → Información de la Empresa → Ambiente.

Autenticación

Cada solicitud debe incluir la API Key de la integración en el encabezado X-API-Key:

curl https://api.filexpress.app/api/external/branches \
  -H "X-API-Key: fx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

La API Key se obtiene al crear la integración en FileXpress (Integraciones → Nueva Integración), donde también se asignan sus permisos. Ver Integraciones Externas.

Guarda la API Key como un secreto: quien la tenga puede operar con los permisos de la integración. Si se expone, regenérala desde FileXpress; la anterior deja de funcionar de inmediato.

Alcance de los datos

Una integración pertenece a un negocio. Todas las consultas y escrituras se limitan automáticamente a ese negocio: un ID de otro negocio responde 404, igual que uno inexistente.

Obtener las sucursales (`branch_id`)

Muchos endpoints requieren el branch_id de la sucursal. Este endpoint no requiere permisos:

GET /branches

{
  "status": true,
  "data": [
    { "id": "9d1c5a3e-...", "name": "Casa Matriz", "code": "M001" },
    { "id": "9d1c5a40-...", "name": "Sucursal Santa Ana", "code": "S002" }
  ]
}

Permisos

Cada integración solo puede usar los grupos de endpoints que se le asignaron. Si llama a uno sin permiso, recibe 403 con el permiso requerido:

{
  "status": false,
  "message": "This integration does not have the 'hr.employees' permission.",
  "required_scope": "hr.employees"
}

Módulo	Permiso	Endpoints
Facturación	`sales`	Ventas
Facturación	`expenses`	Compras
Facturación	`customers`	Clientes
Facturación	`providers`	Proveedores
Facturación	`products`	Productos
RRHH	`hr.employees`	Empleados (consulta y puestos)
RRHH	`hr.employees.write`	Empleados (alta y edición)
RRHH	`hr.attendances`	Asistencia
RRHH	`hr.leave_requests`	Permisos y vacaciones
RRHH	`hr.payrolls`	Planillas
Contabilidad	`accounting.accounts`	Catálogo y períodos
Contabilidad	`accounting.journal_entries`	Partidas
Contabilidad	`accounting.reports`	Estados financieros
—	Sin permiso	`GET /branches` y catálogos

Los permisos de RRHH y Contabilidad exponen datos personales, salariales y financieros. Nunca se otorgan por defecto: el administrador del negocio debe habilitarlos uno por uno.

Formato de respuestas

Los módulos de RRHH, Contabilidad y los endpoints de ventas, compras y sucursales responden:

// Éxito
{ "status": true, "data": { } }

// Error
{ "status": false, "message": "Validation errors", "errors": { "start_date": ["The start date field is required."] } }

Los endpoints de clientes, proveedores, productos y catálogos usan el formato heredado:

// Éxito
{ "success": true, "data": { }, "message": "Data retrieved successfully." }

// Error de validación (código 404)
{ "success": false, "message": "Validation Error.", "data": { "email": ["The email field is required."] } }

Listados paginados

Los listados de empleados y partidas son paginados (per_page, máximo 200; page para navegar) y devuelven:

{
  "status": true,
  "data": {
    "data": [ ],
    "pagination": { "current_page": 1, "last_page": 4, "per_page": 50, "total": 187 }
  }
}

Fechas y montos

Fechas: YYYY-MM-DD. Horas: HH:MM en formato 24 h.
Montos: números decimales con 2 posiciones, en la moneda del negocio.

Códigos de estado

Código	Significado
`200` / `201`	Éxito (`201` cuando se crea un recurso)
`401`	Falta el encabezado `X-API-Key` o la llave no es válida
`403`	La integración está desactivada o no tiene el permiso del endpoint
`404`	Recurso inexistente o de otro negocio
`409`	Conflicto (por ejemplo, un permiso que se cruza con otro existente)
`422`	Error de validación: revisa `errors`
`429`	Límite de peticiones excedido
`500`	Error interno: repórtalo a soporte con la hora de la petición

Límite de peticiones

Cada integración tiene un límite de peticiones por minuto definido por FileXpress (100 por defecto). Al superarlo, la API responde 429:

{ "status": false, "message": "Rate limit exceeded. Please try again later.", "rate_limit": 100 }

Espera unos segundos y reintenta con backoff exponencial. Si tu caso de uso necesita un límite mayor, solicítalo a soporte.

Registro de llamadas

Cada llamada queda registrada en FileXpress (endpoint, método, código de respuesta, duración y errores). El administrador del negocio puede revisarla en Integraciones → Logs / Estadísticas, lo que facilita diagnosticar problemas de integración.

Verificar la conexión

GET /health

Responde Working sin requerir autenticación.

​URL base

​Probar la API

​Ambiente de pruebas

​Autenticación

​Alcance de los datos

​Obtener las sucursales (branch_id)

​Permisos

​Formato de respuestas

​Listados paginados

​Fechas y montos

​Códigos de estado

​Límite de peticiones

​Registro de llamadas

​Verificar la conexión

URL base

Probar la API

Ambiente de pruebas

Autenticación

Alcance de los datos

Obtener las sucursales (`branch_id`)

Permisos

Formato de respuestas

Listados paginados

Fechas y montos

Códigos de estado

Límite de peticiones

Registro de llamadas

Verificar la conexión