Crear Complemento de Pago

Este endpoint permite crear y sellar un CFDI de Recepción de Pagos (Complemento de Pago).

Método HTTP: POST
URL: /invoices

Cabeceras

Nombre	Descripción	Requerido
`x-user-id`	ID del usuario validado por el servicio de autenticación.	Sí
`x-organization-id`	ID de la organización del usuario.	Sí
`x-api-key`	API key para autenticación.	Sí
`x-idempotency`	Clave de idempotencia para evitar duplicados.	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
`tipoDeComprobante`	`string`	Obligatorio	Debe ser `P` para Complemento de Pago.	`c_TipoDeComprobante`
`receptor`	`ReceptorDto`	Obligatorio	Objeto con los datos del receptor.
`conceptos`	`ConceptoDto[]`	Obligatorio	Arreglo de conceptos.
`moneda`	`string`	Obligatorio	Debe ser `XXX`.	`c_Moneda`
`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`
`fecha`	`string` (ISO 8601)	Obligatorio	Fecha y hora de expedición del comprobante.
`complementoPago`	`ComplementoPagoDto`	Obligatorio	Nodo para el Complemento de Recepción de Pagos.

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	Debe ser `Pago`.
`valorUnitario`	`number`	Obligatorio	Debe ser `0`.
`cantidad`	`number`	Obligatorio	Debe ser `1`.
`claveProdServ`	`string`	Obligatorio	Debe ser `84111506`.	`c_ClaveProdServ`
`claveUnidad`	`string`	Obligatorio	Debe ser `ACT`.	`c_ClaveUnidad`
`objetoImp`	`string`	Obligatorio	Debe ser `01`.	`c_ObjetoImp`

Objeto Principal: `ComplementoPagoDto`

Campo	Tipo	Requerido	Descripción
`pagos`	`PagoDto[]`	Obligatorio	Arreglo de pagos recibidos.

Objeto: `PagoDto`

Campo	Tipo	Requerido	Descripción	Catálogo SAT
`fechaPago`	`string` (ISO 8601)	Obligatorio	Fecha y hora en que se recibió el pago.
`formaDePagoP`	`string`	Obligatorio	Forma en que se recibió el pago.	`c_FormaPago`
`monedaP`	`string`	Obligatorio	Moneda en la que se recibió el pago.	`c_Moneda`
`tipoCambioP`	`number`	Condicional	Tipo de cambio de la moneda del pago a MXN. Requerido si `monedaP` es diferente de `MXN` y `XXX`.
`monto`	`number`	Obligatorio	Monto total del pago recibido.
`numOperacion`	`string`	Opcional	Número de operación del pago (ej. SPEI).
`tipoCadPago`	`string`	Condicional	Clave del tipo de cadena de pago. Requerido para pagos SPEI (`01`).	`c_TipoCadenaPago`
`certPago`	`string`	Condicional	Certificado del pago entregado por el banco (Base64). Requerido si existe `tipoCadPago`.
`cadPago`	`string`	Condicional	Cadena original del comprobante de pago del banco. Requerido si existe `tipoCadPago`.
`selloPago`	`string`	Condicional	Sello digital del pago entregado por el banco. Requerido si existe `tipoCadPago`.
`documentosRelacionados`	`DocumentoRelacionadoDto[]`	Obligatorio	Lista de facturas de ingreso que se saldan con este pago.
`impuestosP`	`PagoImpuestosDto`	Obligatorio	Nodo de impuestos del pago.

Objeto: `DocumentoRelacionadoDto`

Campo	Tipo	Requerido	Descripción	Catálogo SAT
`idDocumento`	`string` (UUID)	Obligatorio	UUID (Folio Fiscal) de la factura de ingreso que se está pagando.
`serie`	`string`	Opcional	Serie de la factura que se paga.
`folio`	`string`	Opcional	Folio de la factura que se paga.
`monedaDR`	`string`	Obligatorio	Moneda de la factura que se paga.	`c_Moneda`
`equivalenciaDR`	`number`	Opcional	Tipo de cambio de la moneda del documento relacionado a la moneda del pago.
`numParcialidad`	`number`	Obligatorio	Número de la parcialidad que se está pagando.
`impSaldoAnt`	`number`	Obligatorio	Monto del saldo anterior de la parcialidad.
`impPagado`	`number`	Obligatorio	Monto de este pago que se aplica a la parcialidad.
`objetoImpDR`	`string`	Obligatorio	Objeto de impuesto de la factura relacionada.	`c_ObjetoImp`
`impuestosDR`	`DocumentoRelacionadoImpuestosDto`	Condicional	Nodo de impuestos del documento relacionado. Requerido si `objetoImpDR` es `02`.

Objeto: `PagoImpuestosDto`

Campo	Tipo	Requerido	Descripción
`trasladosP`	`PagoTrasladoDto[]`	Opcional	Arreglo de traslados de impuestos.
`retencionesP`	`PagoRetencionDto[]`	Opcional	Arreglo de retenciones de impuestos.

Objeto: `PagoTrasladoDto`

Campo	Tipo	Requerido	Descripción	Catálogo SAT
`importeP`	`number`	Obligatorio	Monto del impuesto trasladado.
`baseP`	`number`	Obligatorio	Base del impuesto.
`impuestoP`	`string`	Obligatorio	Clave del impuesto.	`c_Impuesto`
`tipoFactorP`	`string`	Obligatorio	Tipo de factor.	`c_TipoFactor`
`tasaOCuotaP`	`number`	Obligatorio	Tasa o cuota del impuesto.

Objeto: `PagoRetencionDto`

Campo	Tipo	Requerido	Descripción	Catálogo SAT
`impuestoP`	`string`	Obligatorio	Clave del impuesto.	`c_Impuesto`
`importeP`	`number`	Obligatorio	Monto del impuesto retenido.

Ejemplos de Código

cURL
Python

curl -X POST https://sandbox-api.lummy.com/invoices \
  -H "Content-Type: application/json" \
  -H "x-user-id: your-user-id" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}" \
  -H "x-idempotency: $(uuidgen)" \
  -d '{
    "tipoDeComprobante": "P",
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "Receptor de Prueba",
      "regimenFiscal": "601",
      "domicilioFiscal": "12345"
    },
    "conceptos": [
      {
        "claveProdServ": "84111506",
        "cantidad": 1,
        "claveUnidad": "ACT",
        "descripcion": "Pago",
        "valorUnitario": 0,
        "objetoImp": "01"
      }
    ],
    "moneda": "XXX",
    "exportacion": "01",
    "lugarExpedicion": "06500",
    "fecha": "2025-01-15T12:00:00",
    "complementoPago": {
      "pagos": [
        {
          "fechaPago": "2025-01-15T12:00:00",
          "formaDePagoP": "03",
          "monedaP": "MXN",
          "monto": 100,
          "documentosRelacionados": [
            {
              "idDocumento": "f3a3b1e0-0b7a-4b1a-9b0a-0a0b0c0d0e0f",
              "monedaDR": "MXN",
              "numParcialidad": 1,
              "impSaldoAnt": 100,
              "impPagado": 100,
              "objetoImpDR": "01"
            }
          ],
          "impuestosP": {}
        }
      ]
    }
  }'

import os
import requests
import uuid

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

json_data = {
    'tipoDeComprobante': 'P',
    'receptor': {
        'rfc': 'XAXX010101000',
        'nombre': 'Receptor de Prueba',
        'regimenFiscal': '601',
        'domicilioFiscal': '12345',
    },
    'conceptos': [
        {
            'claveProdServ': '84111506',
            'cantidad': 1,
            'claveUnidad': 'ACT',
            'descripcion': 'Pago',
            'valorUnitario': 0,
            'objetoImp': '01',
        },
    ],
    'moneda': 'XXX',
    'exportacion': '01',
    'lugarExpedicion': '06500',
    'fecha': '2025-01-15T12:00:00',
    'complementoPago': {
        'pagos': [
            {
                'fechaPago': '2025-01-15T12:00:00',
                'formaDePagoP': '03',
                'monedaP': 'MXN',
                'monto': 100,
                'documentosRelacionados': [
                    {
                        'idDocumento': 'f3a3b1e0-0b7a-4b1a-9b0a-0a0b0c0d0e0f',
                        'monedaDR': 'MXN',
                        'numParcialidad': 1,
                        'impSaldoAnt': 100,
                        'impPagado': 100,
                        'objetoImpDR': '01',
                    },
                ],
                'impuestosP': {},
            },
        ],
    },
}

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

print(response.json())

Respuesta Exitosa

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

{
  "id": "f3a3b1e0-0b7a-4b1a-9b0a-0a0b0c0d0e0f",
  "status": "STAMPED",
  "cfdi": "<?xml version=..."
}

Respuestas de Error

Código HTTP	Descripción
400	Datos de entrada inválidos o saldo de timbres insuficiente.
409	La clave de idempotencia ya ha sido usada.
500	Fallo al procesar el timbrado. El saldo no fue afectado.

Cabeceras​

Estructura del Request​

Objeto Principal: CrearComprobanteDto​

Objeto: ReceptorDto​

Objeto: ConceptoDto​

Objeto Principal: ComplementoPagoDto​

Objeto: PagoDto​

Objeto: DocumentoRelacionadoDto​

Objeto: PagoImpuestosDto​

Objeto: PagoTrasladoDto​

Objeto: PagoRetencionDto​

Ejemplos de Código​

Respuesta Exitosa​

Respuestas de Error​