Saltar al contenido principal

Emitir una Factura (Todo-en-Uno)

Crea y timbra una factura CFDI 4.0 en una sola llamada. Lummy valida los datos, calcula impuestos, sella el CFDI con tu CSD y lo timbra automaticamente con el PAC.

¿Que obtienes?

Un CFDI 4.0 timbrado con UUID fiscal, archivos XML y PDF almacenados en S3, listo para entregar a tu cliente.

¿Tienes tu propio HSM o FIEL corporativa?

Si necesitas firmar los CFDI con tu propia infraestructura, usa el flujo de dos pasos:

  1. POST /invoices/prepare - Obtiene XML sin sellar y cadena original
  2. POST /invoices/stamp - Envia el XML ya sellado para timbrado

Este flujo alternativo no almacena datos en base de datos ni logs, ideal para empresas con requisitos estrictos de privacidad.

Endpoint​

POST https://api.lummy.io/v1/invoices
EntornoURL
Producciónhttps://api.lummy.io/v1/invoices
Sandboxhttps://sandbox.lummy.io/v1/invoices

Autenticación y Headers​

Headers HTTP Requeridos
{
"Content-Type": string,requerido
↳Formato del body de la petición. Debe ser application/json para indicar que el contenido se envía en formato JSON.
"Authorization": string,opcional
↳Token de autenticación Bearer JWT en formato Bearer <token>. Requerido si no se usa x-api-key. Obtén el token mediante el endpoint de login. El token tiene una vigencia limitada y debe renovarse al expirar.
"x-organization-id": string,requerido
↳UUID de la organización emisora de la factura. Este ID identifica tu empresa en Lummy y determina qué CSD se usará para sellar el CFDI. Lo obtienes al crear tu organización o consultando el listado de organizaciones.
"x-api-key": string,opcional
↳API Key para autenticación alternativa al Bearer token. Requerido si no se usa Authorization. Las API Keys no expiran pero deben mantenerse seguras. Puedes generar múltiples API Keys por organización para diferentes integraciones.
"x-idempotency": stringrequerido
↳UUID único (v4) para garantizar idempotencia en la creación de facturas. Si reenvías una petición con el mismo UUID, recibirás la factura original sin crear una duplicada. IMPORTANTE: Genera un UUID nuevo por cada factura diferente. Si una factura falló y quieres reintentarla, usa un UUID diferente.
}

*Debes usar uno de los dos métodos de autenticación: Authorization (Bearer JWT) o x-api-key.

Idempotencia

El header x-idempotency garantiza que no se dupliquen facturas. Si reenvías el mismo request con el mismo UUID, recibirás la factura original sin crear una nueva. Genera un UUID único por cada factura nueva.

Rate Limiting

Este endpoint tiene un límite de 30 solicitudes por minuto por organización. Si excedes este límite, recibirás un error 429 Too Many Requests.

Estructura del Request​

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

Objeto Principal: CrearComprobanteDto​

CrearComprobanteDto
{
"sucursalId": string,opcional
↳UUID de la sucursal emisora del comprobante. Si se omite, se utiliza la sucursal matriz (casa matriz) de la organización. La sucursal determina qué CSD (Certificado de Sello Digital) se usará para sellar el CFDI y qué datos fiscales del emisor aparecerán en la factura.
"clienteId": string,opcional
↳UUID de un cliente previamente registrado en Lummy. Si provees este campo, NO es necesario enviar el objeto receptor, ya que los datos del cliente se obtendrán automáticamente de la base de datos. Útil para emitir facturas recurrentes al mismo receptor sin reenviar sus datos fiscales cada vez.
"receptor": object,opcional
↳Objeto ReceptorDto con los datos fiscales del receptor de la factura. REQUERIDO si no proporcionas clienteId. Contiene RFC, nombre, régimen fiscal, domicilio fiscal y datos de contacto. Si envías ambos (clienteId y receptor), se ignora el objeto receptor y se usan los datos del cliente registrado.
"tipoDeComprobante": string,requerido
↳Clave del tipo de comprobante según catálogo SAT c_TipoDeComprobante. Valores: I (Ingreso - factura de venta), E (Egreso - nota de crédito), T (Traslado - carta porte), P (Pago - complemento de pago). Para facturas normales de venta usa I. Las notas de crédito requieren adicionalmente el nodo cfdiRelacionados.
"usoCFDI": string,opcional
↳Clave del uso que el receptor dará al CFDI según catálogo SAT c_UsoCFDI. REQUERIDO si tipoDeComprobante es I (Ingreso) o E (Egreso). Ejemplos: G01 (Adquisición de mercancías), G03 (Gastos en general), S01 (Sin efectos fiscales), P01 (Por definir). Este campo determina cómo el receptor podrá deducir o acreditar el comprobante fiscalmente.
"metodoPago": string,opcional
↳Clave del método de pago según catálogo SAT c_MetodoPago. REQUERIDO si tipoDeComprobante es I o E. Valores: PUE (Pago en Una Exhibición - pago inmediato al momento de la venta), PPD (Pago en Parcialidades o Diferido - pago a crédito que requiere emitir complementos de pago posteriormente).
"formaPago": string,opcional
↳Clave de la forma de pago según catálogo SAT c_FormaPago. REQUERIDO si tipoDeComprobante es I o E. Ejemplos: 01 (Efectivo), 02 (Cheque nominativo), 03 (Transferencia electrónica de fondos), 04 (Tarjeta de crédito), 28 (Tarjeta de débito), 99 (Por definir). Si metodoPago es PPD, usa 99 y la forma de pago real se especificará en cada complemento de pago.
"condicionesDePago": string,opcional
↳Texto libre para especificar las condiciones comerciales aplicables al pago del comprobante. Ejemplos: Contado, Crédito a 30 días, 50% anticipo 50% contraentrega, Net 30. Este campo es informativo y no afecta la validación del SAT. Máximo 1000 caracteres.
"serie": string,opcional
↳Serie del folio del comprobante. Cadena alfanumérica que agrupa folios bajo una categoría (ejemplos: A, B, FACT, VTA). Útil para separar diferentes tipos de operaciones, sucursales o puntos de venta. Si no se especifica, el folio será secuencial sin serie. Máximo 25 caracteres.
"folio": string,opcional
↳Número de folio del comprobante. Si no se especifica, Lummy asignará automáticamente el siguiente folio consecutivo disponible para la serie indicada (o sin serie). Si lo especificas manualmente, asegúrate de que sea único para la combinación organización+serie para evitar errores de duplicado. Máximo 40 caracteres.
"fecha": string,requerido
↳Fecha y hora de expedición del comprobante en formato ISO 8601 sin zona horaria (YYYY-MM-DDTHH:mm:ss). Ejemplo: 2025-01-20T14:30:00. IMPORTANTE: Envía la hora local del lugar de expedición, el sistema ajustará automáticamente la zona horaria según el código postal de lugarExpedicion. La fecha no puede ser futura ni anterior a 72 horas de la hora actual. Debe estar dentro de la vigencia del CSD.
"moneda": string,requerido
↳Clave de la moneda del comprobante según catálogo SAT c_Moneda. Ejemplos: MXN (Peso Mexicano), USD (Dólar estadounidense), EUR (Euro), XXX (Sin moneda - para operaciones que no tienen valor monetario como traslados). Si usas una moneda diferente a MXN, debes incluir el campo tipoCambio obligatoriamente.
"tipoCambio": number,opcional
↳Tipo de cambio de la moneda extranjera a MXN (pesos mexicanos). REQUERIDO si moneda es diferente de MXN y XXX. Debe ser el tipo de cambio oficial publicado por el Banco de México para la fecha del comprobante, salvo que exista un acuerdo con el receptor para usar otro tipo de cambio. Ejemplo: 17.5 indica que 1 USD = 17.5 MXN. Acepta hasta 6 decimales.
"confirmacion": string,opcional
↳Clave de confirmación del SAT (5 caracteres alfanuméricos). REQUERIDO cuando el total del comprobante o el tipo de cambio están fuera de los límites establecidos por el SAT en el Diario Oficial de la Federación (DOF). El SAT te proporcionará esta clave cuando solicites autorización para emitir un comprobante con valores extremos. Ejemplo: A1B2C.
"exportacion": string,requerido
↳Clave que indica si el comprobante ampara una operación de exportación según catálogo SAT c_Exportacion. Valores: 01 (No aplica exportación - operaciones nacionales), 02 (Exportación definitiva - mercancía que sale del país sin retorno), 03 (Exportación temporal - salida temporal con retorno futuro), 04 (Exportación de servicios). Para ventas locales dentro de México siempre usa 01.
"lugarExpedicion": string,requerido
↳Código postal del lugar de expedición del comprobante según catálogo SAT c_CodigoPostal. Debe ser un código postal válido mexicano de 5 dígitos. Normalmente es el código postal del domicilio fiscal de la sucursal emisora. Este valor determina la zona horaria que se usará para el sellado del CFDI. Ejemplo: 06500 (Cuauhtémoc, CDMX).
"conceptos": array,opcional
↳Arreglo de objetos ConceptoDto que representan los bienes o servicios facturados. REQUERIDO si tipoDeComprobante NO es P (Pago). Cada concepto incluye descripción, cantidad, precio unitario, impuestos y claves del SAT. Debe haber al menos un concepto. Para complementos de pago (tipoDeComprobante P), este campo debe omitirse o enviarse vacío.
"cfdiRelacionados": object,opcional
↳Objeto CfdiRelacionadosDto para vincular este comprobante con otros CFDI previamente emitidos. REQUERIDO para notas de crédito (tipoDeComprobante E con tipoRelacion 01) o sustituciones de CFDI (tipoRelacion 04). Permite establecer la relación entre documentos y cumplir con las validaciones del SAT.
"informacionGlobal": object,opcional
↳Objeto InformacionGlobalDto con datos de facturación global. REQUERIDO cuando el RFC del receptor es XAXX010101000 (público en general) y deseas agrupar múltiples operaciones del público en general en una sola factura. Especifica periodicidad (diaria, semanal, mensual), mes(es) y año que ampara la factura. Permite cumplir con la obligación de emitir CFDI al público en general.
"complementoPago": object,opcional
↳Objeto ComplementoPagoDto con el Complemento de Recepción de Pagos (REP 2.0). REQUERIDO si tipoDeComprobante es P (Pago). Se usa cuando se recibe un pago de una factura que fue emitida con metodoPago PPD (pago diferido). Vincula el pago con las facturas originales y documenta la forma de pago real. Consulta la documentación del complemento de pagos para más detalles.
"complementoCartaPorte": object,opcional
↳Objeto ComplementoCartaPorteDto con el Complemento Carta Porte 3.0. REQUERIDO si tipoDeComprobante es T (Traslado) o cuando se factura un servicio de transporte de mercancías. Documenta el traslado de bienes por territorio nacional especificando origen, destino, mercancías, vehículos y operadores. Consulta la documentación de Carta Porte para más detalles.
"addenda": string,opcional
↳Nodo XML completo de la addenda requerida por el cliente receptor. Las addendas son extensiones privadas que grandes corporaciones (Walmart, Liverpool, CFE, etc.) requieren agregar al CFDI con información adicional específica de su sistema. Debe ser un XML bien formado. Si incluyes addenda, DEBES especificar los namespaces correspondientes en el campo espaciosDeNombres.
"espaciosDeNombres": array,opcional
↳Arreglo de objetos EspacioDeNombreDto que definen los namespaces XML (xmlns) necesarios para la addenda. REQUERIDO si incluyes el campo addenda. Cada namespace incluye prefijo, URI y ubicación del esquema XSD. Permite que el XML del CFDI incluya correctamente las declaraciones xmlns requeridas por la addenda del receptor.
"complementos": arrayopcional
↳Arreglo de objetos ComplementoGenericoDto para incluir complementos fiscales adicionales del SAT. Ejemplos: Comercio Exterior 2.0, IEDU (instituciones educativas), INE (donativos), Leyendas Fiscales, etc. Cada complemento debe enviarse como XML completo con sus namespaces. Consulta la documentación del SAT para cada complemento específico.
}

Ejemplos de Código​

A continuación, ejemplos funcionales en diferentes lenguajes para integrar el endpoint en tu sistema:

curl -X POST https://sandbox.lummy.io/invoices \
  -H "Content-Type: application/json" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}" \
  -H "x-idempotency: $(uuidgen)" \
  -d '{
    "tipoDeComprobante": "I",
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "PUBLICO EN GENERAL",
      "regimenFiscal": "616",
      "domicilioFiscal": "06500",
      "email": "cliente@ejemplo.com"
    },
    "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
            }
          ]
        }
      }
    ]
  }'
Variables de entorno

Define LUMMY_ORG_ID y LUMMY_API_KEY en tu shell:

export LUMMY_ORG_ID="your-organization-uuid"
export LUMMY_API_KEY="your-api-key"

Response​

Respuesta Exitosa (HTTP 201 Created)​

Todas las respuestas siguen el formato estándar StandardResponse:

{
  "requestId": "abc123-def456",
  "data": {
    "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",
    "xmlUrl": "https://lummy-invoices.s3.amazonaws.com/cfdi/cfa52b8b-93f2-4e6b-8c73-64ad88deb17c.xml",
    "status": "stamped"
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
Respuesta Exitosa - Factura Timbrada
{
"requestId": string,requerido
↳Identificador único de la solicitud HTTP para trazabilidad y debugging. Incluye este ID al contactar soporte técnico para diagnóstico rápido de problemas. Formato UUID v4.
"data.invoiceId": string,requerido
↳UUID único de la factura en la base de datos de Lummy. Este ID interno se usa para consultar, actualizar o cancelar la factura mediante otros endpoints de la API. Es diferente del cfdiUuid (folio fiscal del SAT).
"data.cfdiUuid": string,requerido
↳UUID fiscal asignado por el SAT al timbrar el CFDI. También conocido como Folio Fiscal. Este es el identificador oficial del comprobante ante el SAT y debe aparecer impreso en todas las representaciones del CFDI. El receptor usa este UUID para verificar la factura en el portal del SAT. Es único a nivel nacional.
"data.verificationUrl": string,requerido
↳URL completa al portal de verificación del SAT prellenada con el UUID fiscal de esta factura. El receptor puede visitar esta URL para verificar la autenticidad del comprobante directamente en los sistemas del SAT. Formato: https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id={UUID}
"data.xmlUrl": string,requerido
↳URL pública firmada de S3 para descargar el archivo XML timbrado del CFDI. Este XML contiene el sello digital del SAT y es el comprobante fiscal oficial. La URL es de acceso público y tiene una vigencia de 7 días. El XML incluye todos los datos de la factura, impuestos, cadena original y sellos digitales.
"data.status": string,requerido
↳Estado del proceso de timbrado de la factura. Valores: stamped (timbrado exitoso - UUID asignado por el SAT), pending_stamping (en cola de reintentos por error temporal del PAC). Si el estado es pending_stamping, consulta retryInfo para conocer cuándo se reintentará.
"timestamp": string,requerido
↳Fecha y hora en que se generó esta respuesta HTTP en formato ISO 8601 con zona horaria UTC. Ejemplo: 2025-01-20T10:00:00.000Z. Útil para auditoría y sincronización de sistemas.
"path": string,requerido
↳Ruta del endpoint API que procesó esta solicitud. Ejemplo: /invoices. Útil para debugging y logging centralizado.
"method": stringrequerido
↳Método HTTP usado en la solicitud. Para este endpoint siempre será POST. Se incluye en todas las respuestas estándar para trazabilidad completa.
}
Importante

El cfdiUuid es el Folio Fiscal oficial. Este UUID debe aparecer en todas las representaciones impresas del CFDI y es el identificador único que tu cliente usará para verificar la factura en el SAT.

Generación de PDF

El archivo PDF se genera de forma asíncrona después del timbrado y se envía automáticamente por correo electrónico al receptor. Puedes obtener la URL del PDF consultando el detalle de la factura con GET /invoices/{invoiceId}.

Respuesta Pendiente de Timbrado (HTTP 201 Created)​

Si el PAC no responde o hay un error temporal, la factura se guarda y se reintenta automáticamente:

{
  "requestId": "abc123-def456",
  "data": {
    "invoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "cfdiUuid": "",
    "verificationUrl": "",
    "xmlUrl": "",
    "status": "pending_stamping",
    "retryInfo": {
      "nextRetryAt": "2025-01-20T10:05:00.000Z",
      "attempt": 1,
      "maxAttempts": 5
    }
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
Respuesta Pendiente - Campos Adicionales
{
"data.status": string,requerido
↳Estado pending_stamping indica que la factura fue validada y guardada correctamente, pero el timbrado con el PAC falló temporalmente (timeout, servicio no disponible, error transitorio). El sistema reintentará automáticamente el timbrado. No necesitas hacer nada, pero puedes consultar el estado con GET /invoices/{invoiceId}.
"data.retryInfo.nextRetryAt": string,requerido
↳Fecha y hora programada para el próximo intento automático de timbrado en formato ISO 8601 UTC. El sistema usa backoff exponencial, por lo que cada reintento espera más tiempo que el anterior (30s, 2m, 5m, 15m, 1h). Ejemplo: 2025-01-20T10:05:00.000Z.
"data.retryInfo.attempt": number,requerido
↳Número del intento actual de timbrado. Empieza en 1 en el primer intento fallido. Se incrementa con cada reintento hasta alcanzar maxAttempts. Si todos los reintentos fallan, la factura quedará en estado failed y deberás investigar la causa del error con el PAC.
"data.retryInfo.maxAttempts": numberrequerido
↳Número máximo de reintentos automáticos que realizará el sistema. Actualmente configurado en 5 intentos. Si después de 5 intentos el PAC sigue sin responder o rechazando el timbrado, la factura se marcará como failed y se te notificará por webhook (si está configurado).
}
Reintentos Automáticos

El sistema reintenta automáticamente el timbrado con backoff exponencial. No necesitas hacer nada adicional. Puedes consultar el estado de la factura con GET /invoices/{invoiceId}.

Respuestas de Error​

Todas las respuestas de error siguen el formato estándar StandardResponse:

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Descripción del error",
    "code": "ERROR_CODE",
    "status": 400
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
Respuesta de Error - Formato Estándar
{
"requestId": string,requerido
↳Identificador único de la solicitud HTTP fallida para trazabilidad. Incluye este ID al reportar problemas a soporte técnico para diagnóstico rápido. Formato UUID v4. Permite correlacionar errores en logs distribuidos.
"error.message": string,requerido
↳Mensaje descriptivo del error en español legible para humanos. Explica qué salió mal y, cuando es posible, sugiere cómo corregirlo. Ejemplos: RFC inválido: debe tener 12 o 13 caracteres, No se encontró CSD activo para la sucursal. Útil para mostrar al usuario final o para debugging.
"error.code": string,requerido
↳Código de error constante para manejo programático en tu aplicación. Permite implementar lógica específica según el tipo de error sin depender del mensaje. Ejemplos: ValidationError, BranchNotFoundError, PacRejectionError, UnauthorizedException. Estos códigos son estables y no cambian entre versiones.
"error.status": number,requerido
↳Código de estado HTTP del error. Indica la categoría del error: 400 (datos inválidos), 401 (sin autenticación), 403 (sin permisos), 404 (recurso no encontrado), 409 (conflicto de idempotencia o folio duplicado), 422 (rechazo del PAC/SAT), 429 (rate limit excedido), 500 (error interno del servidor).
"timestamp": string,requerido
↳Fecha y hora exacta en que ocurrió el error en formato ISO 8601 con zona horaria UTC. Ejemplo: 2025-01-20T10:00:00.000Z. Útil para auditoría, debugging temporal y correlación con logs del servidor.
"path": string,requerido
↳Ruta del endpoint API donde ocurrió el error. Ejemplo: /invoices. Ayuda a identificar qué operación falló en sistemas que usan múltiples endpoints de Lummy.
"method": stringrequerido
↳Método HTTP de la solicitud fallida (GET, POST, PUT, DELETE, PATCH). Para este endpoint siempre será POST. Se incluye para trazabilidad completa del error.
}

400 Bad Request - Datos Inválidos​

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

Causas comunes:

  • RFC con formato incorrecto
  • Claves de catálogo SAT inválidas (ej. claveProdServ, usoCFDI)
  • Fechas fuera del rango permitido por el SAT
  • Campos requeridos faltantes
  • Header x-idempotency faltante

401 Unauthorized - Autenticación Inválida​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Token de autenticación inválido o expirado",
    "code": "UnauthorizedException",
    "status": 401
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Solución: Verifica que tu API Key o JWT sea válido y no haya expirado.

403 Forbidden - Sin Permisos​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "User is not allowed to stamp invoices",
    "code": "ForbiddenException",
    "status": 403
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Causas comunes:

  • El usuario no tiene el scope invoices:create
  • La suscripción está inactiva o expirada
  • El saldo de timbres es insuficiente
  • El actor no pertenece a la organización especificada

404 Not Found - Recurso No Encontrado​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "No se encontró CSD activo para la sucursal",
    "code": "BranchNotFoundError",
    "status": 404
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Causas comunes:

  • La sucursal no existe o no pertenece a la organización
  • No hay un CSD vigente cargado para la sucursal
  • El cliente especificado (clienteId) no existe

409 Conflict - Conflicto de Idempotencia​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Invoice with idempotencyKey abc-123 failed previously. Please use a different idempotencyKey to retry.",
    "code": "ConflictException",
    "status": 409
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Causas comunes:

  • La clave de idempotencia ya fue usada para una factura que falló
  • El folio especificado ya existe para la organización (conflicto de concurrencia)

Solución: Genera un nuevo UUID para x-idempotency si quieres reintentar.

422 Unprocessable Entity - Rechazo del PAC/SAT​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "CFDI40139 - El RFC del receptor no existe en la lista de RFC inscritos no cancelados del SAT",
    "code": "PacRejectionError",
    "status": 422
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Causas comunes:

  • RFC del receptor no registrado en el SAT
  • Certificado de sello digital (CSD) vencido o revocado
  • Errores de validación de reglas del SAT (CFDI40xxx)
  • RFC del emisor en lista 69-B del SAT

429 Too Many Requests - Rate Limit Excedido​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "ThrottlerException: Too Many Requests",
    "code": "ThrottlerException",
    "status": 429
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Solución: Espera un minuto antes de reintentar. El límite es de 30 solicitudes por minuto.

500 Internal Server Error - Error Interno​

{
  "requestId": "abc123-def456",
  "error": {
    "message": "An unexpected internal server error occurred.",
    "code": "INTERNAL_SERVER_ERROR",
    "status": 500
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}

Nota: Si el timbrado falla después de guardar la factura, el sistema la marcará como pending_stamping y reintentará automáticamente. El saldo de timbres no se consume hasta que el timbrado sea exitoso.

Campos Obligatorios Explicados​

exportacion​

  • Valores: 01 (No aplica), 02 (Definitiva), 03 (Temporal)
  • Para ventas nacionales, siempre usa '01'

objetoImp​

  • 01: No objeto de impuesto
  • 02: Sí objeto de impuesto (requiere nodo impuestos)
  • 03: Sí objeto de impuesto y NO obligado al desglose

claveProdServ​

Clave del catálogo SAT de productos y servicios:

  • 81111500: Servicios de ingeniería de software
  • 84111506: Servicios de consultoría en tecnología
  • Buscar más claves aquí

claveUnidad​

Unidad de medida del SAT:

  • E48: Unidad de servicio
  • H87: Pieza
  • KGM: Kilogramo

Notas Importantes​

Cálculo Automático de Totales​

No necesitas enviar los campos Subtotal, Total, ni Importe de conceptos. Nuestro sistema los calcula automáticamente según las reglas del SAT para garantizar precisión.

Zona Horaria​

El campo fecha debe enviarse en hora local del lugar de expedición. El sistema ajustará automáticamente la zona horaria según el código postal de lugarExpedicion.

Transaccionalidad​

Si el timbrado falla después de validar los datos, NO se consume un timbre de tu saldo. El sistema usa transacciones atómicas para garantizar consistencia.

Siguientes Pasos​

Soporte​

¿Necesitas ayuda? Contáctanos:

Objeto: ReceptorDto​

ReceptorDto
{
"rfc": string,requerido
↳RFC (Registro Federal de Contribuyentes) del receptor de la factura. Debe tener 12 caracteres para personas morales o 13 para personas físicas. Formato: 3-4 letras + 6 dígitos (fecha) + 3 caracteres (homoclave). Ejemplos: XAXX010101000 (público en general), ABC123456XYZ (persona moral), ABCD123456XYZ (persona física). El RFC debe estar registrado y activo en el SAT. Si el RFC es genérico (XAXX010101000), debes incluir el nodo informacionGlobal.
"nombre": string,requerido
↳Nombre completo o Razón Social del receptor tal como aparece en su constancia de situación fiscal del SAT. Para personas físicas: Apellido Paterno + Apellido Materno + Nombre(s). Para personas morales: Razón social completa. Máximo 254 caracteres. No uses abreviaturas no oficiales. Evita caracteres especiales no permitidos por el SAT (emojis, símbolos raros). Ejemplos: PUBLICO EN GENERAL, SERVICIOS TECNOLOGICOS SA DE CV.
"regimenFiscal": string,requerido
↳Clave del régimen fiscal del receptor según catálogo SAT c_RegimenFiscal. Determina las obligaciones fiscales del receptor. Ejemplos comunes: 601 (General de Ley Personas Morales), 603 (Personas Morales con Fines no Lucrativos), 605 (Sueldos y Salarios e Ingresos Asimilados a Salarios), 606 (Arrendamiento), 608 (Demás ingresos), 610 (Residentes en el Extranjero sin Establecimiento Permanente en México), 611 (Ingresos por Dividendos - socios y accionistas), 612 (Personas Físicas con Actividades Empresariales y Profesionales), 614 (Ingresos por intereses), 616 (Sin obligaciones fiscales - para público en general), 621 (Incorporación Fiscal - RIF), 625 (Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas), 626 (Régimen Simplificado de Confianza RESICO). Usa 616 para facturas al público en general (RFC XAXX010101000).
"domicilioFiscal": string,requerido
↳Código postal del domicilio fiscal del receptor registrado en el SAT según catálogo c_CodigoPostal. Debe ser un código postal mexicano válido de 5 dígitos. Este dato debe coincidir con el registrado en la constancia de situación fiscal del receptor para evitar rechazos del SAT. Ejemplo: 06500 (Cuauhtémoc, CDMX), 64000 (Monterrey, NL). Para público en general puedes usar cualquier CP válido.
"email": string,requerido
↳Correo electrónico válido del receptor para el envío automático de la factura (XML y PDF). Formato: usuario@dominio.com. Lummy enviará automáticamente un correo con los archivos adjuntos y el link de descarga después del timbrado. Puedes especificar múltiples correos separados por comas: cliente@empresa.com,contabilidad@empresa.com. Máximo 100 caracteres por correo. IMPORTANTE: El receptor DEBE recibir su factura por correo según las reglas del SAT.
"telefono": stringopcional
↳Número de teléfono de contacto del receptor. Formato libre, pero se recomienda incluir código de país y área. Ejemplos: +52 55 1234 5678, (81) 8765-4321, 5551234567. Este campo es opcional y solo informativo. Máximo 20 caracteres. Útil para contacto en caso de problemas con la entrega de la factura o aclaraciones.
}

Objeto: ConceptoDto​

ConceptoDto
{
"descripcion": string,requerido
↳Descripción detallada del bien o servicio facturado. Debe ser clara, específica y suficientemente descriptiva para que el receptor y el SAT entiendan qué se está facturando. Evita descripciones genéricas como Servicio o Producto. Preferible: Desarrollo de sistema web de facturación electrónica con módulos de catálogos, clientes y reportes. Máximo 1000 caracteres. Puedes incluir especificaciones técnicas, modelos, marcas o características relevantes.
"valorUnitario": number,requerido
↳Precio unitario del concepto antes de impuestos y descuentos. Debe ser un número positivo con máximo 6 decimales. Ejemplos: 1500.00, 99.99, 0.50. Para servicios profesionales, es el precio por hora, día o proyecto. Para productos, es el precio por pieza, kilogramo, litro, etc. según la claveUnidad. Si el concepto no tiene valor monetario (regalos, muestras gratuitas), usa 0.00 y objetoImp = 01.
"cantidad": number,requerido
↳Cantidad de unidades del bien o servicio. Debe ser un número positivo con máximo 6 decimales. Ejemplos: 1 (un servicio), 10.5 (diez kilos y medio), 0.25 (un cuarto de unidad), 1000 (mil piezas). La cantidad multiplicada por valorUnitario determina el importe del concepto antes de descuentos e impuestos. Para servicios intangibles como consultoría o desarrollo, normalmente se usa 1.
"claveProdServ": string,requerido
↳Clave del producto o servicio según catálogo SAT c_ClaveProdServ. Son códigos de 8 dígitos que clasifican todos los bienes y servicios existentes. Ejemplos comunes: 81111500 (Servicios de desarrollo de software a la medida), 84111506 (Servicios de consultoría en tecnologías de la información), 43231500 (Computadoras portátiles), 46171600 (Medicamentos orales), 50202200 (Servicios de auditoría), 90101501 (Servicios de educación superior). Busca la clave correcta en http://pys.sat.gob.mx/PyS/catPyS.aspx. IMPORTANTE: El uso de claves incorrectas puede resultar en rechazo del SAT o auditorías fiscales.
"claveUnidad": string,requerido
↳Clave de la unidad de medida según catálogo SAT c_ClaveUnidad. Define en qué unidad se mide la cantidad. Ejemplos comunes: E48 (Unidad de servicio - para servicios intangibles), H87 (Pieza), KGM (Kilogramo), LTR (Litro), MTR (Metro), XBX (Caja), DAY (Día), HUR (Hora), ACT (Actividad), XNA (No aplica). Para servicios profesionales, consultoría, desarrollo de software, capacitación, usa E48. Para productos físicos, usa la unidad que corresponda al bien (H87 para computadoras, KGM para alimentos por peso, etc.).
"objetoImp": string,requerido
↳Clave que indica si el concepto es objeto de impuestos según catálogo SAT c_ObjetoImp. Valores: 01 (No objeto de impuesto - exento, no hay traslados ni retenciones), 02 (Sí objeto de impuesto - se deben especificar impuestos en el nodo impuestos), 03 (Sí objeto del impuesto y no obligado al desglose - casos especiales donde se causa impuesto pero no se desglosa), 04 (Sí objeto del impuesto y no causa impuesto - cuando hay tasa 0% de IVA). Para la mayoría de ventas de bienes y servicios gravados usa 02 e incluye traslados de IVA al 16%. Para exportaciones o venta de alimentos básicos con tasa 0% usa 04.
"descuento": number,opcional
↳Monto del descuento aplicado al concepto en la misma moneda del comprobante. Debe ser un número positivo menor que (cantidad × valorUnitario). Máximo 6 decimales. El descuento se aplica ANTES de calcular impuestos. Ejemplo: si valorUnitario = 1000, cantidad = 2, descuento = 200, entonces base para IVA = 2000 - 200 = 1800. Si aplicas descuento en porcentaje, debes calcularlo y enviar el monto absoluto. El descuento total del comprobante no puede exceder el subtotal.
"impuestos": object,opcional
↳Objeto ConceptoImpuestosDto que contiene los impuestos trasladados (IVA, IEPS) y retenidos (ISR, IVA retenido) que aplican a este concepto. REQUERIDO si objetoImp es 02 (Sí objeto de impuesto). El objeto puede contener un arreglo traslados con impuestos que se cargan al cliente (IVA 16%, IEPS) y/o un arreglo retenciones con impuestos que se retienen (ISR 10%, IVA retenido 4%). Cada impuesto incluye base, impuesto, tipoFactor y tasaOCuota. Los montos de impuestos se calculan automáticamente por Lummy.
"aCuentaTerceros": object,opcional
↳Objeto ACuentaTercerosDto para especificar información cuando el pago se realiza a cuenta de un tercero. Se usa en operaciones donde facturas por cuenta de otra persona o empresa. Incluye RFC, nombre, régimen fiscal y domicilio fiscal del tercero que debe aparecer en el CFDI. Este nodo es poco común y solo se usa en casos específicos de intermediación comercial.
"cuentaPredial": string,opcional
↳Número de cuenta predial asociado al concepto cuando se facturan servicios relacionados con bienes inmuebles. Formato: Cadena de caracteres sin espacios. Longitud de 1 a 150 caracteres. Se usa principalmente para arrendamiento de inmuebles, servicios de construcción sobre un predio específico, o venta de bienes raíces. Ejemplo: 1234567890. Si facturas arrendamiento, este campo puede ser requerido por el receptor para deducibilidad.
"informacionAduanera": array,opcional
↳Arreglo de objetos InformacionAduaneraDto para documentar pedimentos de importación cuando vendes mercancía de procedencia extranjera. REQUERIDO por el SAT cuando comercializas productos importados para permitir trazabilidad aduanera. Cada pedimento incluye el número en formato: AA BB CCCC DDDDDDD (ejemplo: 21 47 3840 8000936). Puedes incluir múltiples pedimentos si el concepto se compone de mercancías de diferentes importaciones.
"partes": array,opcional
↳Arreglo de objetos ParteDto para desglosar componentes o partes que integran el concepto principal. Útil cuando vendes un producto compuesto (ej: computadora completa) y necesitas especificar sus partes (procesador, RAM, disco duro, etc.). Cada parte incluye su propia claveProdServ, descripción, cantidad, claveUnidad y opcionalmente valorUnitario. Las partes NO afectan los cálculos de totales, son solo informativas.
"complementoConcepto": stringopcional
↳XML completo de un complemento específico del concepto. Algunos giros especiales requieren complementos a nivel concepto. Ejemplos: Complemento de Vehículo Usado (para compraventa de autos usados), Complemento de Terceros (detalle de cuentas por cobrar de terceros), Complemento IEDU (para colegiaturas y servicios educativos). Debe ser un XML bien formado con su namespace correspondiente. Consulta la documentación del SAT para el complemento específico que necesites.
}

Objeto: ConceptoImpuestosDto​

ConceptoImpuestosDto
{
"traslados": array,opcional
↳Arreglo de objetos ConceptoTrasladoDto con los impuestos que se trasladan (cobran) al cliente en este concepto. El impuesto más común es IVA al 16% (impuesto 002, tipoFactor Tasa, tasaOCuota 0.16). También puede incluir IEPS (impuesto 003) para productos con impuestos especiales como alcohol, tabaco o gasolinas. Cada traslado calcula: importe = base × tasaOCuota. La base es normalmente (cantidad × valorUnitario - descuento). Lummy calcula automáticamente los montos. Al menos traslados o retenciones debe estar presente si objetoImp es 02.
"retenciones": arrayopcional
↳Arreglo de objetos ConceptoRetencionDto con los impuestos que se retienen al receptor en este concepto. Se usa cuando eres retenedor y debes retener ISR o IVA al prestador de servicios. Ejemplos comunes: ISR 10% en honorarios profesionales (impuesto 001, tipoFactor Tasa, tasaOCuota 0.10), IVA 10.666667% en arrendamiento (impuesto 002, tipoFactor Tasa, tasaOCuota 0.106667). Las retenciones REDUCEN el monto a pagar al receptor. Cada retención calcula: importe = base × tasaOCuota. Lummy calcula automáticamente los montos.
}

Objeto: ConceptoTrasladoDto​

ConceptoTrasladoDto
{
"base": number,requerido
↳Base imponible sobre la cual se calcula el impuesto trasladado. Normalmente es (cantidad × valorUnitario - descuento) redondeado a 2 decimales. Para IVA: si vendes 10 productos a $100 cada uno con $50 de descuento, la base es 1000 - 50 = 950.00. El SAT valida que la base sea coherente con el concepto. Debe ser un número positivo con máximo 6 decimales. El importe del impuesto se calcula como: base × tasaOCuota.
"impuesto": string,requerido
↳Clave del impuesto trasladado según catálogo SAT c_Impuesto. Valores: 001 (ISR - Impuesto Sobre la Renta, muy raro en traslados), 002 (IVA - Impuesto al Valor Agregado, el más común), 003 (IEPS - Impuesto Especial sobre Producción y Servicios, para alcohol, tabaco, refrescos, gasolinas). Para la mayoría de ventas de bienes y servicios usa 002 (IVA). Si vendes productos con IEPS, incluye dos traslados: uno de IEPS y otro de IVA (el IVA se calcula sobre precio + IEPS).
"tipoFactor": string,requerido
↳Tipo de factor que se aplica a la base del impuesto según catálogo SAT c_TipoFactor. Valores: Tasa (el valor más común, porcentaje como 0.16 = 16%), Cuota (cantidad fija por unidad, ej: $0.50 por litro en IEPS de gasolinas), Exento (el concepto está exento del impuesto, tasaOCuota debe ser 0.00). Para IVA al 16% usa Tasa. Para IVA tasa 0% usa Tasa con tasaOCuota 0.00. Para productos exentos de IVA usa Exento.
"tasaOCuota": numberrequerido
↳Tasa o cuota del impuesto. Si tipoFactor es Tasa: es el porcentaje expresado en decimales. Ejemplos: 0.16 para IVA 16%, 0.08 para IVA frontera 8%, 0.00 para tasa 0%. Máximo 6 decimales. Si tipoFactor es Cuota: es el monto fijo en pesos por unidad. Ejemplo: 0.50 significa $0.50 por cada unidad de la claveUnidad. Si tipoFactor es Exento: debe ser 0.00. IMPORTANTE: Las tasas de IVA vigentes son 16% general, 8% frontera norte, 0% exportación y alimentos básicos.
}

Objeto: ConceptoRetencionDto​

ConceptoRetencionDto
{
"base": number,requerido
↳Base imponible sobre la cual se calcula el impuesto retenido. Normalmente es (cantidad × valorUnitario - descuento) redondeado a 2 decimales, igual que en traslados. Ejemplo: si pagas honorarios de $10,000 y retienes ISR 10%, la base es 10000.00. El importe retenido será base × tasaOCuota = 10000 × 0.10 = 1000.00. Debe ser un número positivo con máximo 6 decimales. El SAT valida coherencia entre base y concepto.
"impuesto": string,requerido
↳Clave del impuesto retenido según catálogo SAT c_Impuesto. Valores: 001 (ISR - Impuesto Sobre la Renta, común en honorarios profesionales, arrendamiento, servicios profesionales), 002 (IVA - Impuesto al Valor Agregado retenido, común en arrendamiento de locales comerciales, fletes de autotransporte, servicios de limpieza y vigilancia), 003 (IEPS - muy raro en retenciones). Casos comunes: ISR 10% en honorarios (impuesto 001), IVA retenido 10.666667% en arrendamiento (impuesto 002).
"tipoFactor": string,requerido
↳Tipo de factor que se aplica a la base del impuesto retenido según catálogo SAT c_TipoFactor. Valores: Tasa (el más común, porcentaje como 0.10 = 10%), Cuota (monto fijo, muy raro en retenciones). Para retenciones casi siempre usarás Tasa. Ejemplo: ISR en honorarios profesionales usa Tasa con tasaOCuota 0.10 (10%). IVA retenido en arrendamiento usa Tasa con tasaOCuota 0.106667 (10.666667% que es 2/3 del IVA).
"tasaOCuota": numberrequerido
↳Tasa o cuota del impuesto retenido expresada en decimales. Ejemplos comunes: 0.10 para ISR 10% en honorarios, 0.106667 para IVA retenido 10.666667% en arrendamiento, 0.04 para IVA retenido 4% en servicios de limpieza. Máximo 6 decimales. IMPORTANTE: Las tasas de retención varían según el tipo de ingreso. Honorarios profesionales: ISR 10%. Arrendamiento: ISR 10% e IVA 10.666667%. Fletes: IVA 4%. Verifica la tasa correcta en la Ley del ISR e IVA vigente.
}

Objeto: CfdiRelacionadosDto​

Nodo para especificar CFDI relacionados (ej. notas de crédito, sustituciones).

CfdiRelacionadosDto
{
"tipoRelacion": string,requerido
↳Clave del tipo de relación entre este CFDI y los CFDI relacionados según catálogo SAT c_TipoRelacion. Valores principales: 01 (Nota de crédito de los documentos relacionados - cuando devuelves dinero o cancelas parcial/totalmente una factura previa), 02 (Nota de débito de los documentos relacionados - cuando cobras un cargo adicional por servicios extras no incluidos en factura original), 03 (Devolución de mercancía sobre facturas o traslados previos), 04 (Sustitución de los CFDI previos - cuando corriges un CFDI y emites uno nuevo que lo reemplaza), 05 (Traslados de mercancías facturados previamente), 06 (Factura generada por los traslados previos), 07 (CFDI por aplicación de anticipo). El tipo de relación más común es 01 para notas de crédito.
"uuids": arrayrequerido
↳Arreglo de UUIDs (folios fiscales) de los CFDI que se relacionan con este nuevo comprobante. Cada UUID es un string en formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Ejemplo: [fdb057e9-890b-487e-953b-05b1c59b4e3c, a1b2c3d4-e5f6-7890-abcd-ef1234567890]. Puedes relacionar múltiples CFDI cuando, por ejemplo, emites una nota de crédito que cancela parcialmente varias facturas. Los UUIDs deben corresponder a CFDI timbrados y vigentes (no cancelados). El SAT valida que los UUIDs existan en su base de datos.
}

Ejemplo:

{
  "tipoRelacion": "04",
  "uuids": ["fdb057e9-890b-487e-953b-05b1c59b4e3c"]
}

Tipos de Relación Comunes:

  • 01: Nota de crédito de los documentos relacionados
  • 02: Nota de débito de los documentos relacionados
  • 03: Devolución de mercancía
  • 04: Sustitución de los CFDI previos

Objeto: InformacionGlobalDto​

Nodo requerido para facturas globales (RFC XAXX010101000 - público en general).

InformacionGlobalDto
{
"periodicidad": string,requerido
↳Clave de la periodicidad con la que se emite la factura global según catálogo SAT c_Periodicidad. Valores: 01 (Diaria - agrupar operaciones del público en general de un día), 02 (Semanal - agrupar operaciones de una semana), 03 (Quincenal - primera o segunda quincena del mes), 04 (Mensual - todas las operaciones del mes), 05 (Bimestral - cada dos meses). Ejemplo: si tienes una tienda de retail y al final del día emites una factura global con todas las ventas a público en general del día, usa 01 (Diaria). Si facturas al fin de mes todas las ventas del mes, usa 04 (Mensual). La periodicidad determina con qué frecuencia debes emitir facturas globales para cumplir con el SAT.
"meses": string,requerido
↳Clave del mes o meses que ampara la factura global según catálogo SAT c_Meses. Valores: 01 (Enero), 02 (Febrero), ... 12 (Diciembre), 13 (Enero-Febrero para bimestral), 14 (Marzo-Abril), ... Use 01-12 para periodicidad diaria, semanal, quincenal o mensual. Use 13-18 para periodicidad bimestral. Ejemplo: factura global mensual de enero 2025 usa meses 01. Factura global bimestral enero-febrero usa meses 13. Si tu periodicidad es diaria o semanal, especifica el mes en que cae ese día o semana.
"anio": numberrequerido
↳Año de 4 dígitos que ampara la factura global. Debe ser el año en que ocurrieron las operaciones del público en general que se están facturando. Ejemplo: 2025, 2026. El año debe ser coherente con el campo fecha del comprobante. IMPORTANTE: Las facturas globales deben emitirse dentro de las 72 horas siguientes al cierre del periodo (día, semana, quincena, mes, bimestre). No puedes emitir facturas globales de periodos muy antiguos.
}

Ejemplo:

{
  "periodicidad": "01",
  "meses": "01",
  "anio": 2025
}

Periodicidad:

  • 01: Diaria
  • 02: Semanal
  • 03: Quincenal
  • 04: Mensual
  • 05: Bimestral

Objeto: ACuentaTercerosDto​

Nodo para operaciones a cuenta de terceros.

ACuentaTercerosDto
{
"nombre": string,requerido
↳Nombre completo o Razón Social del tercero a cuenta de quien se realiza la operación, tal como aparece en su constancia de situación fiscal del SAT. Este tercero es diferente del emisor y del receptor. Se usa en operaciones de intermediación donde facturas servicios o bienes que benefician a un tercero. Ejemplo: una constructora subcontrata servicios de plomería para una obra de un desarrollador inmobiliario, el plomero factura a la constructora (receptor) pero a cuenta del desarrollador (tercero). Máximo 254 caracteres.
"rfc": string,requerido
↳RFC (Registro Federal de Contribuyentes) del tercero. Debe tener 12 caracteres para personas morales o 13 para personas físicas. Formato: 3-4 letras + 6 dígitos + 3 caracteres homoclave. El RFC debe estar registrado y activo en el SAT. Ejemplo: TCE010101ABC (persona moral), TCER010101XYZ (persona física). Este RFC debe ser diferente del RFC del emisor y del receptor, si no es una operación válida a cuenta de terceros.
"regimenFiscal": string,requerido
↳Clave del régimen fiscal del tercero según catálogo SAT c_RegimenFiscal. Debe corresponder al régimen registrado en la constancia de situación fiscal del tercero. Ejemplos: 601 (General de Ley Personas Morales), 612 (Personas Físicas con Actividades Empresariales y Profesionales), 626 (Régimen Simplificado de Confianza). Consulta la lista completa de regímenes en el campo regimenFiscal de ReceptorDto. El régimen determina las obligaciones fiscales del tercero.
"domicilioFiscal": stringrequerido
↳Código postal del domicilio fiscal del tercero registrado en el SAT según catálogo c_CodigoPostal. Debe ser un código postal mexicano válido de 5 dígitos que coincida con el registrado en la constancia de situación fiscal del tercero. Ejemplo: 01000 (Álvaro Obregón, CDMX). El SAT valida que el código postal exista en su catálogo oficial de códigos postales.
}

Objeto: InformacionAduaneraDto​

Nodo para información de pedimentos de importación.

InformacionAduaneraDto
{
"numeroPedimento": stringrequerido
↳Número de pedimento aduanal en el formato oficial del SAT: AA BB CCCC DDDDDDD donde AA = últimos 2 dígitos del año de aceptación del pedimento, BB = código de la aduana de despacho (2 dígitos), CCCC = número de la patente aduanal (4 dígitos), DDDDDDD = número progresivo de la operación (7 dígitos). Ejemplo: 21 47 3840 8000936 indica pedimento del año 2021, aduana 47, patente 3840, operación 8000936. Los espacios son obligatorios en las posiciones indicadas. IMPORTANTE: Este campo es OBLIGATORIO cuando vendes mercancía de procedencia extranjera para permitir la trazabilidad aduanera que requiere el SAT. Puedes consultar tus pedimentos en el sistema de la aduana o con tu agente aduanal.
}

Formato del pedimento: AA BB CCCC DDDDDDD (ejemplo: 21 47 3840 8000936)

Objeto: ParteDto​

Nodo para especificar partes o componentes de un concepto.

ParteDto
{
"claveProdServ": string,requerido
↳Clave del producto o servicio de la parte según catálogo SAT c_ClaveProdServ (8 dígitos). Similar al concepto principal, cada parte debe clasificarse con su clave específica del SAT. Ejemplo: si el concepto es una computadora completa (43211500), las partes pueden ser: 43211503 (procesador), 43201501 (memoria RAM), 43201402 (disco duro SSD). Busca las claves en http://pys.sat.gob.mx/PyS/catPyS.aspx. Las partes permiten desglosar componentes sin afectar totales.
"descripcion": string,requerido
↳Descripción detallada de la parte o componente. Debe ser específica y técnica para identificar claramente qué componente es. Ejemplos: Procesador Intel Core i7-12700K 3.6GHz 12 núcleos, Memoria RAM DDR4 16GB 3200MHz Crucial, Disco SSD NVMe 1TB Samsung 980 Pro. Máximo 1000 caracteres. La descripción complementa la claveProdServ y ayuda al receptor a entender exactamente qué componentes integran el producto principal.
"cantidad": number,requerido
↳Cantidad de unidades de esta parte. Debe ser un número positivo con máximo 6 decimales. Ejemplo: 1 (un procesador), 2 (dos módulos de RAM), 4 (cuatro tornillos), 0.5 (medio litro de lubricante). La cantidad indica cuántas unidades de la parte se incluyen en el concepto principal. Si vendes 5 computadoras con 2 módulos de RAM cada una, la parte RAM tendrá cantidad 2 (por computadora), no 10.
"claveUnidad": string,requerido
↳Clave de la unidad de medida de la parte según catálogo SAT c_ClaveUnidad. Define en qué unidad se mide la cantidad de la parte. Ejemplos: H87 (Pieza - para componentes electrónicos, tornillos, refacciones), KGM (Kilogramo - para materiales a granel), LTR (Litro - para líquidos), MTR (Metro - para cables, tubos), XNA (No aplica - cuando la parte no tiene unidad específica). Para partes de computadoras, electrónica, maquinaria usa H87.
"valorUnitario": number,opcional
↳Valor unitario opcional de la parte en la misma moneda del comprobante. Número positivo con máximo 6 decimales. Este campo es informativo y NO afecta los cálculos de totales del comprobante (el total se calcula solo con los conceptos principales, no con las partes). Útil para documentar el valor individual de cada componente cuando necesitas trazabilidad de costos. Ejemplo: si la computadora cuesta $20,000 y el procesador es valorUnitario 5000, solo documenta que el procesador representa $5,000 del total.
"informacionAduanera": arrayopcional
↳Arreglo de objetos InformacionAduaneraDto para documentar pedimentos de importación específicos de esta parte. Útil cuando el concepto principal es nacional pero algunas partes son importadas. Ejemplo: una computadora ensamblada en México (concepto) pero el procesador fue importado (parte con pedimento). Cada pedimento documenta la importación legal de esa parte y permite trazabilidad aduanera completa. Incluye el número de pedimento en formato oficial del SAT.
}

Objeto: EspacioDeNombreDto​

Nodo para definir namespaces XML requeridos por addendas.

EspacioDeNombreDto
{
"prefijo": string,requerido
↳Prefijo o alias del namespace XML que se usará en los elementos de la addenda. Debe ser un identificador XML válido (letras, números, guiones bajos, sin espacios). Ejemplos: miAddenda, walmart, liverpool, cfe, cmx. Este prefijo se usará en las etiquetas XML de la addenda como <prefijo:elemento>. Debe coincidir con el prefijo usado en el XML de la addenda. Longitud recomendada: 2-20 caracteres. Si la addenda usa múltiples namespaces, debes declarar cada uno con su EspacioDeNombreDto correspondiente.
"uri": string,requerido
↳URI (Uniform Resource Identifier) único que identifica el namespace de la addenda. Normalmente es una URL proporcionada por la empresa que requiere la addenda, aunque no necesariamente apunta a un recurso real en internet. Formato: http://www.empresa.com/addenda/version. Ejemplos: http://www.walmart.com.mx/addenda/v1, http://www.cfe.gob.mx/addenda/v2.0, http://liverpool.com.mx/proveedores/addenda. El URI debe ser exactamente el especificado en la documentación de la addenda del cliente, ya que el SAT valida que coincida con el XSD.
"ubicacionEsquema": stringrequerido
↳URL completa donde se encuentra el archivo XSD (XML Schema Definition) que define la estructura y reglas de validación de la addenda. Debe ser una URL accesible públicamente en internet donde el validador del SAT pueda descargar el esquema para verificar que el XML de la addenda cumple con las reglas. Formato: http://www.empresa.com/schemas/addenda-v1.xsd. Ejemplos: http://www.sat.gob.mx/sitio_internet/cfd/catalogos/Addenda.xsd. IMPORTANTE: Si la URL no es accesible o el XSD no valida correctamente el XML de la addenda, el PAC rechazará el timbrado.
}

Ejemplo:

{
  "prefijo": "miAddenda",
  "uri": "http://www.miempresa.com/addenda/v1",
  "ubicacionEsquema": "http://www.miempresa.com/addenda/v1/addenda.xsd"
}

Objeto: ComplementoGenericoDto​

Nodo para complementos fiscales adicionales (Comercio Exterior, etc.).

ComplementoGenericoDto
{
"xml": stringrequerido
↳XML completo del complemento fiscal como cadena de texto (string). El XML debe estar bien formado, incluir todos los namespaces necesarios (xmlns) y cumplir con el XSD oficial del SAT para ese complemento específico. Complementos disponibles: Comercio Exterior 2.0 (cce20:ComercioExterior - para exportaciones definitivas con claves de comercio exterior), IEDU (iedu:instEducativas - para instituciones educativas privadas que facturan colegiaturas), INE (ine:INE - para donativos deducibles a partidos políticos), Leyendas Fiscales (leyendasFisc:LeyendasFiscales - textos legales requeridos en ciertos giros), Notarios Públicos (notariospublicos:NotariosPublicos), entre otros. Ejemplo: <cce20:ComercioExterior Version="2.0" MotivoTraslado="05" TipoOperacion="2" ClaveDePedimento="A1".../>. IMPORTANTE: Consulta la documentación oficial del SAT para el complemento específico que necesites, cada uno tiene campos y validaciones particulares. El XML debe incluir el namespace completo con su versión.
}

Ejemplo:

{
  "xml": "<cce20:ComercioExterior Version=\"2.0\" ... />"
}