> ## Documentation Index > Fetch the complete documentation index at: https://developers.tiendadepuntos.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar clientes > Devuelve los clientes del comercio, paginados y ordenados por puntos disponibles descendente. Para encontrar un cliente puntual por email o documento exacto conviene `GET /external/clients/search`; el parámetro `query` de este listado hace búsqueda parcial sobre nombre, email, documento, teléfono y tarjeta de afiliado. **Atención**: este endpoint devuelve `{ data, meta, links }` en la raíz, sin el envelope `{ success, status, message, data }`. ## OpenAPI ````yaml /api-reference/openapi.json get /external/clients openapi: 3.0.0 info: title: API de Tienda de Puntos description: >- API pública de Tienda de Puntos. Permite sumar puntos por compra, consultar clientes, validar canjes y consumir cupones desde tu POS, ERP o e-commerce. Todas las llamadas se autentican con el header `x-api-key`. version: 0.0.1 contact: {} servers: - url: https://api.tiendadepuntos.com description: Producción - url: https://apidev.tiendadepuntos.com description: Desarrollo security: - ApiKeyAuth: [] tags: [] paths: /external/clients: get: tags: - Clientes summary: Listar clientes description: >- Devuelve los clientes del comercio, paginados y ordenados por puntos disponibles descendente. Para encontrar un cliente puntual por email o documento exacto conviene `GET /external/clients/search`; el parámetro `query` de este listado hace búsqueda parcial sobre nombre, email, documento, teléfono y tarjeta de afiliado. **Atención**: este endpoint devuelve `{ data, meta, links }` en la raíz, sin el envelope `{ success, status, message, data }`. operationId: ExternalClientController_findAll parameters: - name: order required: false in: query description: Campo por el que ordenar. schema: type: string enum: - fullName - currentPoints - lastOperation - createdAt - name: levelId required: false in: query description: >- Devuelve solo los clientes de este nivel. Los IDs salen de `GET /external/levels`. schema: example: 3 type: number - name: tagId required: false in: query description: Devuelve solo los clientes con esta etiqueta del comercio. schema: example: 4 type: number - name: currentPointsMin required: false in: query description: Puntos disponibles mínimos. schema: example: 100 type: number - name: currentPointsMax required: false in: query description: Puntos disponibles máximos. schema: example: 5000 type: number - name: lastOperationFrom required: false in: query description: Clientes con última suma de puntos desde esta fecha (ISO 8601). schema: example: '2026-07-01' type: string - name: lastOperationTo required: false in: query description: Clientes con última suma de puntos hasta esta fecha (ISO 8601). schema: example: '2026-07-31' type: string - name: page required: false in: query schema: type: integer minimum: 1 default: 1 example: 1 - name: limit required: false in: query description: Cantidad de resultados por página. Máximo 200. schema: type: integer minimum: 1 maximum: 200 default: 10 example: 10 - name: query required: false in: query description: Búsqueda parcial por nombre. schema: type: string example: café - name: direction required: false in: query description: Sentido del orden. Solo aplica si se envía `order`. schema: type: string enum: - asc - desc default: desc responses: '200': description: Página de clientes. Sin envelope. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ExternalClientOutputDto' meta: type: object properties: totalItems: type: integer example: 128 itemCount: type: integer example: 10 itemsPerPage: type: integer example: 10 totalPages: type: integer example: 13 currentPage: type: integer example: 1 from: type: integer example: 1 to: type: integer example: 10 links: type: object properties: first: type: string example: external/clients?page=1&limit=10 previous: type: string example: null nullable: true next: type: string nullable: true example: external/clients?page=2&limit=10 last: type: string example: external/clients?page=13&limit=10 path: type: string example: external/clients firstPageUrl: type: string example: external/clients?page=1&limit=10 lastPageUrl: type: string example: external/clients?page=13&limit=10 '400': description: El cuerpo o los parámetros no pasaron la validación. content: application/json: schema: type: object properties: statusCode: type: integer example: 400 timestamp: type: string format: date-time example: '2026-07-31T14:05:12.431Z' path: type: string example: /external/tags/add method: type: string example: POST message: type: string example: Error de validación errors: type: array nullable: true items: type: object data: type: object nullable: true '404': description: >- Falta el header `x-api-key` (`Api Key is required`) o la API key no corresponde a ningún comercio (`Business not found`). También se usa cuando el recurso pedido no existe. content: application/json: schema: type: object properties: statusCode: type: integer example: 404 timestamp: type: string format: date-time example: '2026-07-31T14:05:12.431Z' path: type: string example: /external/tags/add method: type: string example: POST message: type: string example: Api Key is required errors: type: array nullable: true items: type: object data: type: object nullable: true security: - ApiKeyAuth: [] components: schemas: ExternalClientOutputDto: type: object properties: id: type: number description: ID del cliente en Tienda de Puntos example: 84213 name: type: string description: Nombre completo example: Juan Manuel Pérez first_name: type: string description: Nombre example: Juan Manuel last_name: type: string description: Apellido example: Pérez email: type: string description: Email example: juanma@mailinator.com nullable: true dni: type: string description: >- Número de documento. Alias de `document_number`, se mantiene por compatibilidad. example: '40100800' nullable: true document_number: type: string description: Número de documento example: '40100800' nullable: true document_type: type: string description: Tipo de documento example: DNI nullable: true phone: type: string description: Teléfono example: '+541164593678' nullable: true gender: type: number description: Género. 0 = masculino, 1 = femenino, 2 = otro, 3 = sin datos. enum: - 0 - 1 - 2 - 3 example: 0 affiliate_card: type: string description: Número de tarjeta de afiliado example: '00012345' nullable: true score: type: number description: Puntos disponibles del cliente example: 1250 total_score: type: number description: Puntos acumulados históricamente example: 8400 description: type: string description: Observaciones internas del comercio example: null nullable: true birthday: format: date-time type: string description: Fecha de nacimiento example: '1990-01-01T00:00:00.000Z' nullable: true status: type: string description: Estado del cliente en el programa de fidelidad enum: - SUSPEND - ACTIVE example: ACTIVE level: description: >- Nivel actual del cliente. `null` si el comercio no usa niveles o el cliente todavía no alcanzó el primero. nullable: true allOf: - $ref: '#/components/schemas/ExternalClientLevelOutputDto' created_at: format: date-time type: string description: Fecha de alta example: '2026-02-14T12:30:00.000Z' last_transaction: format: date-time type: string description: Fecha de la última transacción de puntos example: '2026-07-28T18:05:00.000Z' nullable: true purchases_counter: type: number description: Cantidad de canjes realizados example: 7 reads_counter: type: number description: Cantidad de operaciones de suma de puntos example: 32 required: - id - name - first_name - last_name - email - dni - document_number - document_type - phone - gender - affiliate_card - score - total_score - description - birthday - status - created_at - last_transaction - purchases_counter - reads_counter ExternalClientLevelOutputDto: type: object properties: id: type: number description: ID del nivel. example: 3 name: type: string description: Nombre del nivel. example: Nivel 2 required: - id - name securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key del comercio. Se genera desde el panel de Tienda de Puntos, en Configuración → Integraciones. ````