> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción a la API

> Conecta tu sistema con FileXpress: autenticación, permisos, formato de respuestas y errores

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.

<Warning>
  El playground envía solicitudes **reales** al negocio de tu API Key. Usa una integración del [ambiente de pruebas](#ambiente-de-pruebas) para experimentar, nunca la de producción.
</Warning>

## 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:

<Steps>
  <Step title="Solicita a soporte un negocio en ambiente de pruebas">
    Escribe a [soporte@filexpress.com](mailto:soporte@filexpress.com) indicando el nombre de tu integración y los módulos que vas a usar.
  </Step>

  <Step title="Crea una integración en ese negocio y usa su API Key en tu desarrollo y en el playground" />

  <Step title="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.
  </Step>
</Steps>

<Tip>
  El ambiente actual de un negocio se ve en **Soporte → Información de la Empresa → Ambiente**.
</Tip>

## Autenticación

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

```bash theme={null}
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](/docs/gestion/integraciones).

<Warning>
  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.
</Warning>

## 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:

```http theme={null}
GET /branches
```

```json theme={null}
{
  "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:

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

| Módulo | Permiso | Endpoints |
| - | - | - |
| Facturación | `sales` | [Ventas](/docs/api/facturacion/ventas) |
| Facturación | `expenses` | [Compras](/docs/api/facturacion/compras) |
| Facturación | `customers` | [Clientes](/docs/api/facturacion/clientes) |
| Facturación | `providers` | [Proveedores](/docs/api/facturacion/proveedores) |
| Facturación | `products` | [Productos](/docs/api/facturacion/productos) |
| RRHH | `hr.employees` | [Empleados](/docs/api/rrhh/empleados) (consulta y puestos) |
| RRHH | `hr.employees.write` | [Empleados](/docs/api/rrhh/empleados#crear-empleado) (alta y edición) |
| RRHH | `hr.attendances` | [Asistencia](/docs/api/rrhh/asistencia) |
| RRHH | `hr.leave_requests` | [Permisos y vacaciones](/docs/api/rrhh/permisos) |
| RRHH | `hr.payrolls` | [Planillas](/docs/api/rrhh/planillas) |
| Contabilidad | `accounting.accounts` | [Catálogo y períodos](/docs/api/contabilidad/catalogo) |
| Contabilidad | `accounting.journal_entries` | [Partidas](/docs/api/contabilidad/partidas) |
| Contabilidad | `accounting.reports` | [Estados financieros](/docs/api/contabilidad/reportes) |
| — | Sin permiso | `GET /branches` y [catálogos](/docs/api/facturacion/catalogos) |

<Note>
  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.
</Note>

## Formato de respuestas

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

```json theme={null}
// É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:

```json theme={null}
// É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:

```json theme={null}
{
  "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`:

```json theme={null}
{ "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](mailto:soporte@filexpress.com).

## 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

```http theme={null}
GET /health
```

Responde `Working` sin requerir autenticación.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.