Guía: Emitir tu Primera Factura de Ingreso

Esta guía te ayudará a emitir tu primer Comprobante Fiscal Digital por Internet (CFDI) tipo Ingreso usando nuestra API de facturación electrónica. Al finalizar, obtendrás un CFDI 4.0 timbrado por el SAT con su UUID único.

Objetivo

Al completar esta guía habrás creado una factura de ingreso válida, sellada y timbrada, lista para enviarse a tu cliente.

Pre-requisitos

Antes de comenzar, asegúrate de tener:

API Key: Credencial de autenticación para consumir la API
Organization ID: Identificador único de tu organización en el sistema
CSD Activo: Tu organización debe tener un Certificado de Sello Digital (CSD) vigente configurado
Conocimiento básico: Familiaridad con REST APIs y formato JSON

Ambiente de pruebas

Para pruebas, usa el RFC genérico del SAT: XAXX010101000 (Público en General).

El Request: Crear una Factura

Endpoint

POST https://api.lummy.io/invoices

Headers

Header	Valor	Descripción
`Content-Type`	`application/json`	Formato del body
`x-organization-id`	`{tu-organization-id}`	ID de tu organización
`x-api-key`	`{tu-api-key}`	Tu API Key
`x-idempotency`	`{uuid-unico}`	UUID único para evitar duplicados

Idempotencia

El header x-idempotency es obligatorio. Usa un UUID único por cada factura. Si reenvías el mismo request con el mismo UUID, recibirás la misma factura sin duplicarla.

Body (JSON)

A continuación, un ejemplo completo y funcional de una factura de ingreso por servicios de consultoría:

{
  "tipoDeComprobante": "I",
  "receptor": {
    "rfc": "XAXX010101000",
    "nombre": "PUBLICO EN GENERAL",
    "regimenFiscal": "616",
    "domicilioFiscal": "06500"
  },
  "usoCFDI": "G03",
  "metodoPago": "PUE",
  "formaPago": "03",
  "fecha": "2025-11-18T14:30:00",
  "moneda": "MXN",
  "exportacion": "01",
  "lugarExpedicion": "06500",
  "conceptos": [
    {
      "claveProdServ": "84111506",
      "claveUnidad": "E48",
      "descripcion": "Servicio de Consultoría en Tecnología",
      "cantidad": 1,
      "valorUnitario": 1000.00,
      "objetoImp": "02",
      "impuestos": {
        "traslados": [
          {
            "base": 1000.00,
            "impuesto": "002",
            "tipoFactor": "Tasa",
            "tasaOCuota": 0.16
          }
        ]
      }
    }
  ]
}

Cálculos automáticos

No necesitas calcular subtotales, IVA ni totales. Nuestro sistema lo calcula automáticamente según las reglas del SAT.

Explicación de Campos Clave

Muchos campos del CFDI provienen de catálogos oficiales del SAT. A continuación, una referencia rápida:

Campos del Comprobante

Campo	Valor Ejemplo	Descripción
`tipoDeComprobante`	`I`	Ingreso, Egreso, Traslado, Pago, Nómina
`usoCFDI`	`G03`	Uso que dará el receptor al CFDI. Ver catálogo c_UsoCFDI
`metodoPago`	`PUE`	PUE: Pago en Una Exhibición, PPD: Pago en Parcialidades o Diferido
`formaPago`	`03`	`01`: Efectivo, `03`: Transferencia, `04`: Tarjeta. Ver catálogo c_FormaPago
`moneda`	`MXN`	Pesos Mexicanos. Usa `USD`, `EUR`, etc. para moneda extranjera
`exportacion`	`01`	`01`: No aplica, `02`: Definitiva, etc.
`lugarExpedicion`	`06500`	Código Postal donde se expide la factura

Campos del Receptor

Campo	Valor Ejemplo	Descripción
`rfc`	`XAXX010101000`	RFC del cliente. Para público general usa `XAXX010101000`
`regimenFiscal`	`616`	`616`: Sin obligaciones fiscales (público general), `601`: General de Ley, etc. Ver catálogo c_RegimenFiscal
`domicilioFiscal`	`06500`	Código Postal del domicilio fiscal del receptor

Campos de Conceptos

Campo	Valor Ejemplo	Descripción
`claveProdServ`	`84111506`	Clave del producto/servicio según catálogo SAT. Buscar aquí
`claveUnidad`	`E48`	Unidad de medida. `E48`: Servicio, `H87`: Pieza, `KGM`: Kilogramo, etc.
`objetoImp`	`02`	`01`: No objeto de impuesto, `02`: Sí objeto de impuesto, `03`: Sí objeto, pero exento

Campos de Impuestos

Campo	Valor Ejemplo	Descripción
`impuesto`	`002`	`001`: ISR, `002`: IVA, `003`: IEPS
`tipoFactor`	`Tasa`	`Tasa`, `Cuota` o `Exento`
`tasaOCuota`	`0.16`	Tasa del IVA al 16%. Para ISR retención usa `0.1` (10%), etc.
`base`	`1000.00`	Monto sobre el que se aplica el impuesto

Catálogos del SAT

Todos los catálogos están disponibles en el Anexo 20 del SAT.

El Response: Factura Timbrada

Si la solicitud es exitosa, recibirás un HTTP 201 Created con el siguiente formato:

{
  "invoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "cfdiUuid": "cfa52b8b-93f2-4e6b-8c73-64ad88deb17c",
  "verificationUrl": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=cfa52b8b-93f2-4e6b-8c73-64ad88deb17c&re=AAA010101AAA&rr=XAXX010101000&tt=1160.00&fe=/OAgdg==",
  "xmlS3Url": "https://lummy-invoices.s3.amazonaws.com/cfdi/cfa52b8b-93f2-4e6b-8c73-64ad88deb17c.xml",
  "pdfS3Url": "https://lummy-invoices.s3.amazonaws.com/cfdi/cfa52b8b-93f2-4e6b-8c73-64ad88deb17c.pdf"
}

Campos del Response

Campo	Descripción
`invoiceId`	ID interno de la factura en nuestro sistema
`cfdiUuid`	UUID del timbre fiscal emitido por el SAT. Este es el identificador oficial del CFDI
`verificationUrl`	URL para verificar el CFDI en el portal del SAT
`xmlS3Url`	URL pública para descargar el archivo XML timbrado
`pdfS3Url`	URL pública para descargar el PDF de la factura

UUID es la clave

El cfdiUuid es el Folio Fiscal oficial. Es único para cada CFDI y debe incluirse en todas las representaciones impresas de la factura.

Troubleshooting: Errores Comunes

1. RFC Inválido

Error:

{
  "statusCode": 400,
  "message": "RFC inválido: debe tener 12 o 13 caracteres",
  "error": "Bad Request"
}

Solución:

Verifica que el RFC tenga el formato correcto:
- Persona Física: 13 caracteres (ej. XAXX010101000)
- Persona Moral: 12 caracteres (ej. AAA010101AAA)
Usa mayúsculas sin espacios ni guiones

2. CSD No Encontrado o Vencido

Error:

{
  "statusCode": 404,
  "message": "No se encontró CSD activo para la sucursal",
  "error": "Not Found"
}

Solución:

Verifica que tu organización tenga un Certificado de Sello Digital (CSD) vigente
Contacta a tu administrador para cargar un CSD si no existe
Asegúrate de que la fecha de vigencia del CSD no haya expirado

3. Clave de Catálogo Inválida

Error:

{
  "statusCode": 400,
  "message": "Clave de producto/servicio '99999999' no existe en el catálogo c_ClaveProdServ",
  "error": "Bad Request"
}

Solución:

Verifica que todas las claves (claveProdServ, claveUnidad, usoCFDI, etc.) existan en los catálogos del SAT
Usa el buscador de claves del SAT
Consulta nuestro Anexo de Catálogos SAT (próximamente)

4. Idempotencia Duplicada

Error:

{
  "statusCode": 409,
  "message": "La clave de idempotencia ya ha sido usada",
  "error": "Conflict"
}

Solución:

El header x-idempotency debe ser único para cada factura
Si recibes este error, significa que ya existe una factura con ese UUID de idempotencia
Genera un nuevo UUID si realmente quieres crear una factura diferente
Si es un reintento, obtén la factura original mediante el endpoint GET /invoices/{invoiceId}

Siguientes Pasos

¡Felicidades! Ya sabes cómo emitir una factura de ingreso. Ahora puedes:

Emitir una Nota de Crédito (Egreso) (próximamente)
Emitir un Complemento de Pago (REP 2.0) (próximamente)
Emitir una Factura de Traslado con Carta Porte (próximamente)
Consultar el estado de una factura (próximamente)

Preguntas Frecuentes

¿Puedo emitir facturas sin tener un CSD?

No. El Certificado de Sello Digital (CSD) es obligatorio para sellar y timbrar CFDIs según las reglas del SAT.

¿Qué pasa si mi solicitud falla después de consumir un timbre?

Nuestro sistema usa transacciones atómicas. Si el timbrado falla, el saldo de timbres NO se afecta.

¿Puedo cancelar una factura después de timbrada?

Sí, pero debes hacerlo a través del endpoint de cancelación (próximamente). Recuerda que el SAT tiene reglas estrictas sobre cancelaciones.

¿Qué diferencia hay entre `metodoPago` y `formaPago`?

metodoPago indica si el pago es inmediato (PUE) o diferido (PPD)
formaPago indica el medio de pago: efectivo, transferencia, cheque, etc.

Soporte

¿Necesitas ayuda? Contáctanos en:

Email: soporte@lummy.io
Slack Community: lummy-dev.slack.com (próximamente)
Documentación: docs.lummy.io

Pre-requisitos​

El Request: Crear una Factura​

Endpoint​

Headers​

Body (JSON)​

Explicación de Campos Clave​

Campos del Comprobante​

Campos del Receptor​

Campos de Conceptos​

Campos de Impuestos​

El Response: Factura Timbrada​

Campos del Response​

Troubleshooting: Errores Comunes​

1. RFC Inválido​

2. CSD No Encontrado o Vencido​

3. Clave de Catálogo Inválida​

4. Idempotencia Duplicada​

Siguientes Pasos​

Preguntas Frecuentes​

¿Puedo emitir facturas sin tener un CSD?​

¿Qué pasa si mi solicitud falla después de consumir un timbre?​

¿Puedo cancelar una factura después de timbrada?​

¿Qué diferencia hay entre metodoPago y formaPago?​

Soporte​

Pre-requisitos

El Request: Crear una Factura

Endpoint

Headers

Body (JSON)

Explicación de Campos Clave

Campos del Comprobante

Campos del Receptor

Campos de Conceptos

Campos de Impuestos

El Response: Factura Timbrada

Campos del Response

Troubleshooting: Errores Comunes

1. RFC Inválido

2. CSD No Encontrado o Vencido

3. Clave de Catálogo Inválida

4. Idempotencia Duplicada

Siguientes Pasos

Preguntas Frecuentes

¿Puedo emitir facturas sin tener un CSD?

¿Qué pasa si mi solicitud falla después de consumir un timbre?

¿Puedo cancelar una factura después de timbrada?

¿Qué diferencia hay entre `metodoPago` y `formaPago`?

Soporte