API de clientes

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:

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:

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

{
  "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. 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:

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

{
  "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:

{
  "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.

Inicio

Webhooks

Conector MCP