Listar Clientes
Obtiene la lista de clientes registrados en tu organización con soporte para búsqueda y paginación.
Endpoint
GET https://api.lummy.io/v1/customers
| Entorno | URL |
|---|---|
| Producción | https://api.lummy.io/v1/customers |
| Sandbox | https://sandbox.lummy.io/v1/customers |
Request
Headers
Headers requeridos
{
"Authorization": string,requerido
↳Token JWT obtenido del endpoint de autenticación o API Key. Debe incluir el prefijo "Bearer " seguido del token para autenticación JWT.
↳Ejemplo:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." "x-organization-id": stringrequerido
↳Identificador único de la organización de la cual se desea listar los clientes. Debe ser un UUID válido de una organización a la que el usuario autenticado tenga acceso.
↳Formato: UUID v4
↳Ejemplo:
"550e8400-e29b-41d4-a716-446655440000"}
Query Parameters
Parámetros de búsqueda y paginación
{
"search": string,opcional
↳Término de búsqueda para filtrar clientes por RFC o razón social. La búsqueda es insensible a mayúsculas/minúsculas y realiza una coincidencia parcial.
↳Ejemplo:
"cliente" "page": number,opcional
↳Número de página a obtener. La primera página es 1. Si no se especifica, se devuelve la primera página.
↳Valor mínimo: 1 · Valor por defecto: 1
↳Ejemplo:
1 "limit": numberopcional
↳Cantidad de resultados por página. El valor máximo permitido es 100.
↳Rango: 1 - 100 · Valor por defecto: 20
↳Ejemplo:
20}
Response
200 OK
Listado de clientes obtenido exitosamente.
Response Body
{
"requestId": string,requerido
↳Identificador único de la petición. Útil para trazabilidad y soporte técnico.
↳Formato: UUID
↳Ejemplo:
"req_abc123-def456-ghi789" "data": [requerido
↳Arreglo con los clientes encontrados. Puede estar vacío si no hay resultados.
{
"id": string,requerido
↳Identificador único del cliente en Lummy.
↳Formato: UUID v4
↳Ejemplo:
"550e8400-e29b-41d4-a716-446655440000" "rfc": string,requerido
↳Registro Federal de Contribuyentes del cliente.
↳Ejemplo:
"XEXX010101000" "legalName": string,requerido
↳Razón social o nombre completo del cliente.
↳Ejemplo:
"Empresa Cliente S.A. de C.V." "fiscalRegime": string,requerido
↳Clave del régimen fiscal según el catálogo c_RegimenFiscal del SAT.
↳Ejemplo:
"601" "fiscalZipCode": string,requerido
↳Código postal del domicilio fiscal.
↳Ejemplo:
"06500" "email": string,requerido
↳Correo electrónico de contacto.
↳Ejemplo:
"facturacion@cliente.com" "phone": string,opcional
↳Número de teléfono de contacto (si fue proporcionado).
↳Ejemplo:
"+525512345678" "createdAt": string,requerido
↳Fecha y hora de creación del registro.
↳Formato: ISO 8601
↳Ejemplo:
"2025-01-15T10:30:00.000Z" "updatedAt": stringrequerido
↳Fecha y hora de la última actualización.
↳Formato: ISO 8601
↳Ejemplo:
"2025-01-15T10:30:00.000Z" }
],
"total": number,requerido
↳Número total de clientes que coinciden con los criterios de búsqueda.
↳Ejemplo:
1 "page": number,requerido
↳Página actual.
↳Ejemplo:
1 "limit": number,requerido
↳Cantidad de resultados por página.
↳Ejemplo:
20 "totalPages": number,requerido
↳Número total de páginas disponibles.
↳Ejemplo:
1 "timestamp": string,requerido
↳Marca de tiempo de la respuesta del servidor.
↳Formato: ISO 8601
↳Ejemplo:
"2025-01-15T10:30:00.000Z" "path": string,requerido
↳Ruta del endpoint invocado.
↳Ejemplo:
"/customers" "method": stringrequerido
↳Método HTTP utilizado.
↳Ejemplo:
"GET"}
Ejemplos de Código
- cURL
- Node.js (TypeScript)
- Python
- PHP (Guzzle)
curl -X GET "https://sandbox.lummy.io/customers?search=cliente&page=1&limit=20" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "x-organization-id: ${LUMMY_ORG_ID}"
import axios from 'axios';
interface Customer {
id: string;
rfc: string;
legalName: string;
email: string | null;
}
interface ListCustomersResponse {
data: Customer[];
meta: {
page: number;
limit: number;
total: number;
totalPages: number;
};
}
async function listarClientes(search?: string): Promise<ListCustomersResponse> {
const API_URL = 'https://sandbox.lummy.io/customers';
const response = await axios.get<ListCustomersResponse>(API_URL, {
headers: {
'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
'x-organization-id': process.env.LUMMY_ORG_ID!,
},
params: {
search,
page: 1,
limit: 20,
},
});
console.log(`Encontrados: ${response.data.meta.total} clientes`);
return response.data;
}
listarClientes('empresa');
import os
import requests
def listar_clientes(search=None):
api_url = "https://sandbox.lummy.io/customers"
headers = {
"Authorization": f"Bearer {os.getenv('ACCESS_TOKEN')}",
"x-organization-id": os.getenv("LUMMY_ORG_ID"),
}
params = {"page": 1, "limit": 20}
if search:
params["search"] = search
response = requests.get(api_url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(f"Encontrados: {data['meta']['total']} clientes")
return data
if __name__ == "__main__":
listar_clientes("empresa")
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
function listarClientes(?string $search = null): array
{
$client = new Client([
'base_uri' => 'https://sandbox.lummy.io',
'headers' => [
'Authorization' => 'Bearer ' . getenv('ACCESS_TOKEN'),
'x-organization-id' => getenv('LUMMY_ORG_ID'),
],
]);
$query = ['page' => 1, 'limit' => 20];
if ($search) {
$query['search'] = $search;
}
$response = $client->get('/customers', ['query' => $query]);
$data = json_decode($response->getBody(), true);
echo "Encontrados: " . $data['meta']['total'] . " clientes\n";
return $data;
}
listarClientes('empresa');