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

# API de clientes

> Consulta y opera los datos de tu empresa en Pruff desde tus sistemas.

La API de clientes te permite leer y operar desde tus sistemas lo mismo que gestionas en Pruff: facturas, cesiones, solicitudes de financiamiento, reportes, datos de tus clientes y usuarios.

## URL base

Todas las solicitudes van a esta URL base, siempre por HTTPS:

```text theme={null}
https://api.pruff.com/api/clients
```

Cada endpoint de esta referencia indica su path relativo a esa URL. Por ejemplo, `GET /invoices` es `GET https://api.pruff.com/api/clients/invoices`.

## Autenticación

Tu empresa se autentica con una API key, que creas desde Pruff. Envía la clave en el header `x-api-key` de cada solicitud:

```bash theme={null}
curl https://api.pruff.com/api/clients/invoices \
  -H "x-api-key: <tu-token>"
```

Usa la API key para consultar y operar los datos de tu empresa. Para crearla, rotarla o revocarla, consulta [Autenticación](https://docs.pruff.com/api/autenticacion.md). Guárdala en tu servidor y nunca la expongas en un navegador o en una aplicación móvil.

Si falta el header, su valor no es válido o la cuenta de API de tu empresa no está habilitada, la respuesta es `401`:

```json theme={null}
{
  "message": "Unauthorized: Invalid API Key"
}
```

## Formato

* Los bodies de solicitud y de respuesta son JSON, salvo los endpoints que suben o descargan archivos, que indican su formato.
* La mayoría de los nombres de propiedades están en `camelCase`. Algunas respuestas de Datahub conservan los nombres de su fuente (por ejemplo `bank_name` o los meses `JAN` a `DEC`), y cada esquema lo indica.
* Las fechas siguen [ISO 8601](https://es.wikipedia.org/wiki/ISO_8601). Una fecha con hora incluye su zona horaria (`2026-08-12T02:12:33.231Z`). Una fecha sin hora es solo el día (`2026-08-12`). Cada campo indica cuál de las dos usa.
* Los montos suelen ser números. Cuando un campo puede venir como string, su esquema lo indica. Cada campo indica su unidad.

## Paginación

Los endpoints que devuelven listas largas se paginan con dos query params:

| Query param | Descripción |
| - | - |
| `page` | Página que quieres, desde `1`. Por defecto, `1`. Un valor menor que `1` responde `400`. |
| `pageSize` | Elementos por página. Por defecto, `10`. El máximo depende del endpoint y aparece en su referencia. Un valor menor que `1` o mayor que el máximo responde `400`. |

La respuesta trae los elementos en `data` y los datos de paginación en `pagination`:

```bash theme={null}
curl "https://api.pruff.com/api/clients/invoices?page=2&pageSize=5" \
  -H "x-api-key: <tu-token>"
```

```json theme={null}
{
  "data": [
    { "folio": 1042 },
    { "folio": 1043 }
  ],
  "pagination": {
    "total": 7,
    "page": 2,
    "pageSize": 5,
    "totalPages": 2
  }
}
```

Para recorrer una lista completa, pide páginas sucesivas hasta llegar a `totalPages`.

## Códigos de estado

| Código | Significado |
| - | - |
| `200` | Solicitud procesada con éxito. |
| `201` | Recurso creado. |
| `204` | Solicitud procesada con éxito, sin contenido en la respuesta. |
| `400` | Solicitud inválida: falta un parámetro, un valor no tiene el formato esperado o el body no es un JSON válido. |
| `401` | Falta la API key, no es válida o la cuenta de API de tu empresa no está habilitada. |
| `403` | La operación no está permitida para esta solicitud. |
| `404` | El recurso no existe. |
| `409` | La operación entra en conflicto con el estado actual del recurso. |
| `413` | El body JSON que envías supera 500 KB, o la respuesta es demasiado grande. En el segundo caso, reduce el rango de fechas o agrega filtros. |
| `429` | Superaste el límite de solicitudes de tu empresa. |
| `500` | Error inesperado en Pruff. |
| `503` | Un servicio externo del que depende el endpoint, como el SII, no está disponible. También puede ocurrir brevemente durante un mantenimiento de Pruff: en ese caso el body no sigue el formato de la sección Errores. Reintenta. |
| `504` | La solicitud superó el tiempo máximo de 55 segundos. La operación puede haberse completado igual: antes de reintentar una solicitud que crea o modifica datos, verifica su estado. |

Cada endpoint lista en su referencia los códigos que puede devolver.

## Errores

Los errores responden con un body JSON con esta forma:

```json theme={null}
{
  "message": "invalid_format",
  "displayMessage": "El email del ejecutivo no es válido",
  "data": {
    "errors": [
      {
        "code": "invalid_format",
        "message": "El email del ejecutivo no es válido",
        "path": "executiveEmail"
      }
    ]
  }
}
```

| Campo | Descripción |
| - | - |
| `message` | Identifica el error. En algunos casos es un texto en inglés con valores variables. Para tu lógica, usa el código HTTP y, cuando exista, `data.code`. |
| `displayMessage` | Mensaje pensado para mostrarlo a una persona. Normalmente viene en español; algunos mensajes de validación vienen en inglés. No siempre viene. |
| `data` | Detalle adicional, cuando existe. En un error de validación, `data.errors` lista cada parámetro con problemas. |

En general, un `500` trae `"message": "Internal server error"` (las mayúsculas o el texto pueden variar), sin más detalle.

Si pides un path que no existe bajo la URL base, la respuesta es `404` sin body JSON, así que no sigue la forma de esta sección.

## Límite de solicitudes

Todas las API keys de tu empresa comparten un límite de 500 solicitudes por minuto. Algunos endpoints tienen además un límite propio, que aparece en su referencia. Al superarlo recibes `429`, con el header `Retry-After` indicando cuántos segundos esperar antes de reintentar.


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