Preparar Factura

Este endpoint permite a clientes con infraestructura de sellado propia (HSM, procesos corporativos) obtener el XML sin sellar y la cadena original para que sellen el CFDI externamente. NO persiste datos en la base de datos.

• Método HTTP: POST
• URL: /invoices/prepare

Cabeceras

Nombre	Descripción	Requerido
x-organization-id	ID de la organización del usuario.	Sí
x-api-key	API key para autenticación.	Sí

Estructura del Request

El cuerpo de la petición es un objeto JSON que representa el CrearComprobanteDto.

Objeto Principal: CrearComprobanteDto

Campo	Tipo	Requerido	Descripción	Catálogo SAT
sucursalId	string (UUID)	Opcional	ID de la sucursal emisora. Si se omite, se usa la matriz.
clienteId	string (UUID)	Opcional	ID de un cliente existente. Si se provee, se ignora el objeto receptor.
receptor	ReceptorDto	Condicional	Objeto con los datos del receptor. Requerido si no se provee clienteId.
tipoDeComprobante	string	Obligatorio	Tipo de Comprobante. Para facturas de ingreso, usar I.	c_TipoDeComprobante
usoCFDI	string	Condicional	Uso que el receptor le dará a la factura. Requerido si tipoDeComprobante es I o E.	c_UsoCFDI
metodoPago	string	Condicional	Método de pago. Requerido si tipoDeComprobante es I o E.	c_MetodoPago
formaPago	string	Condicional	Forma de pago. Requerido si tipoDeComprobante es I o E.	c_FormaPago
condicionesDePago	string	Opcional	Condiciones comerciales aplicables para el pago del comprobante.
serie	string	Opcional	Serie para el folio del comprobante.
folio	string	Opcional	Folio del comprobante.
fecha	string (ISO 8601)	Obligatorio	Fecha y hora de expedición del comprobante.
moneda	string	Obligatorio	Moneda del comprobante.	c_Moneda
tipoCambio	number	Condicional	Tipo de cambio. Requerido si moneda es diferente de MXN y XXX.
exportacion	string	Obligatorio	Clave que indica si el comprobante ampara una operación de exportación.	c_Exportacion
lugarExpedicion	string	Obligatorio	Código postal del lugar de expedición del comprobante.	c_CodigoPostal
conceptos	ConceptoDto[]	Condicional	Arreglo de conceptos. Requerido si tipoDeComprobante no es P.
cfdiRelacionados	CfdiRelacionadosDto	Opcional	Nodo para especificar información de CFDI relacionados.
informacionGlobal	InformacionGlobalDto	Condicional	Nodo para especificar información de la factura global. Requerido si el RFC del receptor es XAXX010101000.
complementoPago	ComplementoPagoDto	Condicional	Nodo para el Complemento de Recepción de Pagos. Requerido si tipoDeComprobante es P.
complementoCartaPorte	ComplementoCartaPorteDto	Condicional	Nodo para el Complemento Carta Porte. Requerido si tipoDeComprobante es T.
addenda	string	Opcional	Nodo XML de la addenda requerida por el cliente.
espaciosDeNombres	EspacioDeNombreDto[]	Condicional	Arreglo de namespaces (xmlns) requeridos por la addenda. Requerido si se incluye addenda.
complementos	ComplementoGenericoDto[]	Opcional	Arreglo para otros complementos de factura.

Objeto: ReceptorDto

Campo	Tipo	Requerido	Descripción	Catálogo SAT
rfc	string	Obligatorio	RFC del receptor.
nombre	string	Obligatorio	Nombre o Razón Social del receptor.
regimenFiscal	string	Obligatorio	Régimen Fiscal del receptor.	c_RegimenFiscal
domicilioFiscal	string	Obligatorio	Código Postal del domicilio fiscal del receptor.	c_CodigoPostal

Objeto: ConceptoDto

Campo	Tipo	Requerido	Descripción	Catálogo SAT
descripcion	string	Obligatorio	Descripción del concepto.
valorUnitario	number	Obligatorio	Precio unitario del concepto.
cantidad	number	Obligatorio	Cantidad de bienes o servicios del concepto.
claveProdServ	string	Obligatorio	Clave de producto o servicio.	c_ClaveProdServ
claveUnidad	string	Obligatorio	Clave de unidad de medida.	c_ClaveUnidad
objetoImp	string	Obligatorio	Clave que indica si el concepto es objeto de impuesto.	c_ObjetoImp
descuento	number	Opcional	Monto del descuento aplicable al concepto.
impuestos	ConceptoImpuestosDto	Condicional	Nodo de impuestos del concepto. Requerido si objetoImp es 02.
aCuentaTerceros	ACuentaTercerosDto	Opcional	Nodo para especificar información de cuenta de terceros.
cuentaPredial	string	Opcional	Número de cuenta predial.
informacionAduanera	InformacionAduaneraDto[]	Opcional	Nodo para especificar información aduanera.
partes	ParteDto[]	Opcional	Nodo para especificar las partes del concepto.
complementoConcepto	string	Opcional	Nodo XML del complemento de concepto.

Objeto: ConceptoImpuestosDto

Campo	Tipo	Requerido	Descripción
traslados	ConceptoTrasladoDto[]	Opcional	Arreglo de traslados de impuestos.
retenciones	ConceptoRetencionDto[]	Opcional	Arreglo de retenciones de impuestos.

Objeto: ConceptoTrasladoDto

Campo	Tipo	Requerido	Descripción	Catálogo SAT
base	number	Obligatorio	Base imponible para el cálculo del impuesto.
impuesto	string	Obligatorio	Clave del impuesto.	c_Impuesto
tipoFactor	string	Obligatorio	Tipo de factor.	c_TipoFactor
tasaOCuota	number	Obligatorio	Tasa o cuota del impuesto.

Objeto: ConceptoRetencionDto

Campo	Tipo	Requerido	Descripción	Catálogo SAT
base	number	Obligatorio	Base imponible para el cálculo del impuesto.
impuesto	string	Obligatorio	Clave del impuesto.	c_Impuesto
tipoFactor	string	Obligatorio	Tipo de factor.	c_TipoFactor
tasaOCuota	number	Obligatorio	Tasa o cuota del impuesto.

Ejemplos de Código

cURL

curl -X POST https://sandbox-api.lummy.com/invoices/prepare \
  -H "Content-Type: application/json" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}" \
  -d '{
    "tipoDeComprobante": "I",
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "PUBLICO EN GENERAL",
      "regimenFiscal": "616",
      "domicilioFiscal": "06500"
    },
    "usoCFDI": "G03",
    "metodoPago": "PUE",
    "formaPago": "03",
    "fecha": "2025-11-19T10:00:00",
    "moneda": "MXN",
    "exportacion": "01",
    "lugarExpedicion": "06500",
    "conceptos": [
      {
        "claveProdServ": "81111500",
        "claveUnidad": "E48",
        "descripcion": "Desarrollo de Software - Sistema Web a Medida",
        "cantidad": 1,
        "valorUnitario": 15000.00,
        "objetoImp": "02",
        "impuestos": {
          "traslados": [
            {
              "base": 15000.00,
              "impuesto": "002",
              "tipoFactor": "Tasa",
              "tasaOCuota": 0.16
            }
          ]
        }
      }
    ]
  }'

Python

import os
import requests

headers = {
    'Content-Type': 'application/json',
    'x-organization-id': os.environ.get('LUMMY_ORG_ID'),
    'x-api-key': os.environ.get('LUMMY_API_KEY'),
}

json_data = {
    'tipoDeComprobante': 'I',
    'receptor': {
        'rfc': 'XAXX010101000',
        'nombre': 'PUBLICO EN GENERAL',
        'regimenFiscal': '616',
        'domicilioFiscal': '06500',
    },
    'usoCFDI': 'G03',
    'metodoPago': 'PUE',
    'formaPago': '03',
    'fecha': '2025-11-19T10:00:00',
    'moneda': 'MXN',
    'exportacion': '01',
    'lugarExpedicion': '06500',
    'conceptos': [
        {
            'claveProdServ': '81111500',
            'claveUnidad': 'E48',
            'descripcion': 'Desarrollo de Software - Sistema Web a Medida',
            'cantidad': 1,
            'valorUnitario': 15000.0,
            'objetoImp': '02',
            'impuestos': {
                'traslados': [
                    {
                        'base': 15000.0,
                        'impuesto': '002',
                        'tipoFactor': 'Tasa',
                        'tasaOCuota': 0.16,
                    },
                ],
            },
        },
    ],
}

response = requests.post('https://sandbox-api.lummy.com/invoices/prepare', headers=headers, json=json_data)

print(response.json())

Respuesta Exitosa

En caso de éxito, la respuesta será un objeto JSON con la estructura PrepareInvoiceResponseDto.

{
  "unsignedXml": "<?xml version=...",
  "originalString": "||1.0|..."
}

Respuestas de Error

Código HTTP	Descripción
400	Datos de entrada inválidos.
404	Sucursal o CSD no encontrado.