Crear Cliente

Registra un nuevo cliente en tu organización para agilizar la emisión de facturas. Los clientes registrados permiten emitir CFDIs usando solo su ID, sin necesidad de enviar los datos fiscales completos cada vez.

Endpoint

POST 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. Debe incluir el prefijo "Bearer " seguido del token.

↳Ejemplo: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

"x-organization-id": string,requerido

↳Identificador único de la organización a la que pertenecerá el cliente. 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"

"Content-Type": stringrequerido

↳Tipo de contenido del cuerpo de la petición.

↳Ejemplo: "application/json"

}

Body

Request BodyDatos fiscales del cliente a registrar

{

"rfc": string,requerido

↳Registro Federal de Contribuyentes del cliente. Debe coincidir exactamente con el registrado ante el SAT. Para personas morales son 12 caracteres, para personas físicas son 13 caracteres. Se valida el formato y la estructura según las reglas del SAT.

↳Longitud: 12-13 caracteres · Patrón: ^[A-ZÑ&]{3,4}[0-9]{6}[A-Z0-9]{3}$

↳Ejemplo: "XEXX010101000"

"legalName": string,requerido

↳Razón social o nombre completo del cliente tal como aparece en su Constancia de Situación Fiscal del SAT. Este valor se usará en el campo "Nombre" del receptor en los CFDIs emitidos. Debe coincidir exactamente con el registro del SAT para evitar rechazos del PAC.

↳Longitud: 1-254 caracteres

↳Ejemplo: "EMPRESA EJEMPLO SA DE CV"

"fiscalRegime": string,requerido

↳Clave del régimen fiscal del cliente según el catálogo c_RegimenFiscal del SAT. Debe corresponder a un régimen vigente y válido para el tipo de persona (física o moral) según el RFC proporcionado.

↳Catálogo SAT: c_RegimenFiscal · Longitud exacta: 3 caracteres

↳Valores permitidos: "601""603""605""606""607""608""610""611""612""614""615""616""620""621""622""623""624""625""626"

↳Ejemplo: "601"

"fiscalZipCode": string,requerido

↳Código postal del domicilio fiscal del cliente. Debe ser un código postal válido de México según el catálogo c_CodigoPostal del SAT. Este código determina el lugar de expedición del CFDI y debe coincidir con el registrado en la Constancia de Situación Fiscal del cliente.

↳Catálogo SAT: c_CodigoPostal · Longitud exacta: 5 caracteres · Patrón: ^[0-9]{5}$

↳Ejemplo: "06500"

"email": string,requerido

↳Correo electrónico principal del cliente donde se enviarán automáticamente los CFDIs emitidos (PDF y XML). Debe ser una dirección de correo válida y activa.

↳Formato: email · Longitud máxima: 254 caracteres

↳Ejemplo: "facturacion@empresa-ejemplo.com"

"phone": stringopcional

↳Número de teléfono de contacto del cliente. Se recomienda incluir el código de país. Este campo es informativo y no afecta la emisión de CFDIs.

↳Ejemplo: "+52 55 1234 5678"

}

---

Response

201 Created

Cliente creado exitosamente. El cliente queda disponible inmediatamente para ser usado en la emisión de facturas.

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

↳Objeto con los datos del cliente creado.

"id": string,requerido

↳Identificador único del cliente en Lummy. Use este ID en el campo "customerId" al crear facturas para este cliente.

↳Formato: UUID v4

↳Ejemplo: "550e8400-e29b-41d4-a716-446655440000"

"rfc": string,requerido

↳RFC del cliente registrado.

↳Ejemplo: "XEXX010101000"

"legalName": string,requerido

↳Razón social del cliente.

↳Ejemplo: "EMPRESA EJEMPLO SA DE CV"

"fiscalRegime": string,requerido

↳Clave del régimen fiscal.

↳Ejemplo: "601"

"fiscalZipCode": string,requerido

↳Código postal del domicilio fiscal.

↳Ejemplo: "06500"

"email": string,requerido

↳Email de contacto registrado.

↳Ejemplo: "facturacion@empresa-ejemplo.com"

"phone": string,opcional

↳Teléfono de contacto (si fue proporcionado).

↳Ejemplo: "+52 55 1234 5678"

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

},

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

}

400 Bad Request

Error de validación en los datos enviados.

{
  "requestId": "req_abc123-def456",
  "error": {
    "message": "RFC inválido: debe tener 12 o 13 caracteres",
    "code": "ValidationError",
    "status": 400
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/customers",
  "method": "POST"
}

409 Conflict

Ya existe un cliente con el mismo RFC en esta organización.

{
  "requestId": "req_abc123-def456",
  "error": {
    "message": "Ya existe un cliente con el RFC XEXX010101000 en esta organización",
    "code": "ConflictException",
    "status": 409
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/customers",
  "method": "POST"
}

401 Unauthorized

Token de autenticación inválido o expirado.

{
  "requestId": "req_abc123-def456",
  "error": {
    "message": "Token inválido o expirado",
    "code": "UnauthorizedException",
    "status": 401
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/customers",
  "method": "POST"
}

---

Ejemplos de Código

cURL

curl -X POST "https://api.lummy.io/customers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${ORG_ID}" \
  -d '{
    "rfc": "XEXX010101000",
    "legalName": "EMPRESA EJEMPLO SA DE CV",
    "fiscalRegime": "601",
    "fiscalZipCode": "06500",
    "email": "facturacion@empresa-ejemplo.com",
    "phone": "+52 55 1234 5678"
  }'

Node.js

const response = await fetch('https://api.lummy.io/customers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'x-organization-id': ORG_ID,
  },
  body: JSON.stringify({
    rfc: 'XEXX010101000',
    legalName: 'EMPRESA EJEMPLO SA DE CV',
    fiscalRegime: '601',
    fiscalZipCode: '06500',
    email: 'facturacion@empresa-ejemplo.com',
    phone: '+52 55 1234 5678',
  }),
});

const data = await response.json();
console.log('Cliente creado:', data.data.id);

Python

import requests

response = requests.post(
    'https://api.lummy.io/customers',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {ACCESS_TOKEN}',
        'x-organization-id': ORG_ID,
    },
    json={
        'rfc': 'XEXX010101000',
        'legalName': 'EMPRESA EJEMPLO SA DE CV',
        'fiscalRegime': '601',
        'fiscalZipCode': '06500',
        'email': 'facturacion@empresa-ejemplo.com',
        'phone': '+52 55 1234 5678',
    }
)

data = response.json()
print(f"Cliente creado: {data['data']['id']}")

---

Notas Importantes

Validación previa del RFC

Se recomienda validar el RFC del cliente usando el endpoint POST /rfc/validate antes de registrarlo, para verificar que no aparezca en las listas 69 y 69-B del SAT.

Coincidencia con datos del SAT

El RFC, razón social y régimen fiscal deben coincidir exactamente con los registrados en la Constancia de Situación Fiscal del cliente. Discrepancias causarán que el PAC rechace las facturas con el error CFDI40139.