GET /v1/clients

Devuelve los clientes de tu empresa, ordenados por nombre (A→Z).

Sirve para recuperar el id de un cliente que ya creaste sin tener que guardarlo tú — por ejemplo, antes de emitir una venta exonerada.

Solicitud

curl "https://integration.contadito.com/v1/clients?page=1&limit=50" \
  -H "Authorization: Bearer $CONTADITO_API_KEY"

Parámetro	Ubicación	Tipo	Req.	Notas
page	query	number	No	Página, empezando en 1. Requiere también limit.
limit	query	number	No	Clientes por página. Requiere también page.

información

La paginación es opcional, pero es todo o nada

Sin page ni limit se devuelven todos los clientes de tu empresa. La paginación solo se aplica cuando mandas los dos: si mandas únicamente page, se ignora y recibes la lista completa igual.

Ambos deben ser enteros mayores o iguales a 1. Un 0, un negativo o un valor no numérico da 400 VALIDATION_FAILED.

Respuesta 200

{
  "clients": [
    {
      "id": 1042,
      "clientName": "Servicios Digitales S. de R.L.",
      "email": "facturacion@cliente.hn",
      "legalId": "08011999123456",
      "phone": "+504 9999-9999",
      "address": "Tegucigalpa, Honduras",
      "createdAt": "2026-08-10T15:04:05.000Z"
    },
    {
      "id": 1108,
      "clientName": "Zapatería La Buena S.A.",
      "email": "compras@labuena.hn",
      "legalId": null,
      "phone": null,
      "address": null,
      "createdAt": "2026-08-11T09:12:00.000Z"
    }
  ],
  "count": 2
}

Campo	Tipo	Descripción
clients	array	Los clientes de esta página. Cada elemento tiene la misma forma que la respuesta de POST /v1/clients.
count	number	Total de clientes de tu empresa, no el tamaño de esta página.

aviso

count es el total, no lo que viene en clients

Con ?page=1&limit=50 sobre 380 clientes, clients trae 50 y count trae 380. Ese es el número que usas para calcular cuántas páginas hay: Math.ceil(count / limit).

La respuesta es un objeto, no un arreglo suelto, justamente para poder agregar metadatos de paginación más adelante sin romper el contrato.

Alcance de la consulta

La consulta se limita en SQL a la empresa de tu API key: devuelve tus clientes y no recibe ningún parámetro para cambiar ese alcance.

Errores

HTTP	code	Causa
400	VALIDATION_FAILED	page o limit no es un entero ≥ 1.
401	MISSING_API_KEY / INVALID_API_KEY	Credencial ausente o inválida.
403	INTEGRATION_NOT_ENABLED	La empresa no tiene la integración habilitada.

Ver el catálogo completo de errores.

Recorrer todas las páginas

async function todosLosClientes(limit = 100) {
  const clientes = [];
  let page = 1;

  for (;;) {
    const res = await fetch(
      `${BASE}/v1/clients?page=${page}&limit=${limit}`,
      {headers: {Authorization: `Bearer ${process.env.CONTADITO_API_KEY}`}},
    );
    const {clients, count} = await res.json();

    clientes.push(...clients);
    if (clientes.length >= count || clients.length === 0) return clientes;
    page++;
  }
}

consejo

No lo llames antes de cada factura

Este endpoint no filtra por RTN ni por nombre: te devuelve la lista. Si la usas para resolver un cliente en cada venta, estás bajando todo el padrón por factura.

Lo correcto: guarda el id de Contadito junto a tu propio id de cliente cuando lo creas, y usa este endpoint para la carga inicial, para reconciliar, o para recuperarte de un id perdido. El filtrado hazlo de tu lado.