Descargar CFDIs IMSS | Private services

1. Listar comprobantes fiscales

Endpoint POST /private/comprobantes-fiscales

Descripción Devuelve la lista de comprobantes fiscales (CFDIs) de un registro patronal para un periodo específico (mes/año). Para consultar múltiples meses, iterar sobre cada periodo individualmente.

Parámetros (body JSON)

Parámetro	Tipo	Requerido	Descripción
`registro_patronal`	string	Sí	Registro Patronal con dígito verificador
`anio`	integer	Sí	Año del periodo (2000–2100)
`mes`	integer	Sí	Mes del periodo (1–12)

Ejemplo (curl)

curl --location --request POST 'https://apimarket.mx/private/comprobantes-fiscales' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "registro_patronal": "XXXXXXXXXX",
    "anio": 2026,
    "mes": 1
  }'

Respuesta exitosa (200 OK)

{
    "ok": true,
    "params": {
        "registro_patronal": "XXXXXXXXXX",
        "periodo": "202601",
        "anio": 2026,
        "mes": 1
    },
    "meta": {
        "count": 2,
        "warnings": [],
        "fetched_at": "2026-01-15T10:30:00Z"
    },
    "comprobantes": [
        {
            "registro_patronal": "XXXXXXXXXX",
            "folio_sua": "12345678",
            "fecha_pago": "15/01/2026",
            "importe_texto": "$12,345.67",
            "importe_spell": "DOCE MIL TRESCIENTOS CUARENTA Y CINCO PESOS 67/100 M.N.",
            "importe": 12345.67
        }
    ]
}

Respuesta con error

{
    "ok": false,
    "error": {
        "code": "IMSS_SESSION_EXPIRED",
        "message": "La sesión IMSS expiró o es inválida"
    }
}

Errores

Código	Clave	Descripción
401	IMSS_SESSION_REQUIRED	No hay sesión activa con el IMSS
401	IMSS_SESSION_EXPIRED	La sesión IMSS expiró o es inválida
422	Validation error	Parámetros inválidos
502	IMSS_TRANSPORT_ERROR	Error de conexión con el portal del IMSS
502	IMSS_HTTP_ERROR	Respuesta HTTP no exitosa del IMSS

2. Descargar comprobante fiscal (PDF y XML)

Endpoint POST /private/comprobantes-fiscales/descargar

Descripción Descarga el PDF y XML de un comprobante fiscal específico identificado por su folio_sua (obtenido del paso anterior). Hay dos modos de obtener los archivos:

Por URL firmada (default): retorna URLs temporales válidas por 1 hora.
Inline en base64: enviando include_content: true, los archivos se incluyen codificados en base64 directamente en la respuesta.

Parámetros (body JSON)

Parámetro	Tipo	Requerido	Descripción
`registro_patronal`	string	Sí	Registro Patronal con dígito verificador
`anio`	integer	Sí	Año del periodo (2000–2100)
`mes`	integer	Sí	Mes del periodo (1–12)
`folio_sua`	string	Sí	Folio SUA del comprobante (solo dígitos, 1–25 chars)
`importe`	string	No	Importe del comprobante (máx 40 chars)
`include_content`	boolean	No	Si es `true`, incluye el contenido en base64

Opción A: Descargar por URL firmada (default)

curl --location --request POST 'https://apimarket.mx/private/comprobantes-fiscales/descargar' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "registro_patronal": "XXXXXXXXXX",
    "anio": 2026,
    "mes": 1,
    "folio_sua": "12345678"
  }'

Respuesta: files.pdf.base64 y files.xml.base64 serán null. Usar las URLs de files.pdf.url y files.xml.url para descargar (ver paso 3).

Opción B: Descargar inline en base64

curl --location --request POST 'https://apimarket.mx/private/comprobantes-fiscales/descargar' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "registro_patronal": "XXXXXXXXXX",
    "anio": 2026,
    "mes": 1,
    "folio_sua": "12345678",
    "importe": "12345.67",
    "include_content": true
  }'

Respuesta: files.pdf.base64 y files.xml.base64 contendrán el archivo codificado. Decodificar con base64 para obtener los bytes del archivo.

Respuesta exitosa (200 OK)

{
    "ok": true,
    "params": {
        "registro_patronal": "XXXXXXXXXX",
        "periodo": "202601",
        "anio": 2026,
        "mes": 1,
        "folio_sua": "12345678"
    },
    "meta": {
        "expires_at": "2026-01-15T11:30:00Z",
        "cache_store": "redis",
        "fetched_at": "2026-01-15T10:30:00Z",
        "warnings": []
    },
    "files": {
        "pdf": {
            "url": "https://apimarket.mx/private/imss/comprobantes-fiscales/archivo/<token>/pdf?signature=...",
            "content_type": "application/pdf",
            "filename": "XXXXXXXXXX_202601_12345678.pdf",
            "size_bytes": 45230,
            "base64": null
        },
        "xml": {
            "url": "https://apimarket.mx/private/imss/comprobantes-fiscales/archivo/<token>/xml?signature=...",
            "content_type": "application/xml",
            "filename": "XXXXXXXXXX_202601_12345678.xml",
            "size_bytes": 12480,
            "base64": null
        }
    }
}

Con include_content: true, los campos base64 contendrán el archivo codificado en lugar de null.

Errores

Código	Clave	Descripción
401	IMSS_SESSION_REQUIRED	No hay sesión activa con el IMSS
401	IMSS_SESSION_EXPIRED	La sesión IMSS expiró o es inválida
422	IMSS_INCONSISTENT_DATA	Datos inconsistentes (folio, periodo o RP no coinciden)
422	Validation error	Parámetros inválidos
502	IMSS_TRANSPORT_ERROR	Error de conexión con el portal del IMSS
502	IMSS_UPSTREAM_ERROR	Error del servidor IMSS al procesar la solicitud
502	IMSS_HTTP_ERROR	Respuesta HTTP no exitosa del IMSS
502	IMSS_FILETYPE_ERROR	No se pudo identificar el PDF/XML en la respuesta

3. Descargar archivo (URL firmada)

Endpoint GET /private/imss/comprobantes-fiscales/archivo/{token}/{tipo}

Descripción Descarga el archivo binario (PDF o XML) usando la URL firmada obtenida en el paso 2. Las URLs son válidas por 1 hora. Este paso no es necesario si se usó include_content: true en el paso anterior.

Parámetros (URL)

Parámetro	Tipo	Descripción
`token`	string	Token UUID devuelto por el endpoint `descargar`
`tipo`	string	Tipo de archivo: `pdf` o `xml`

No requiere autenticación. La URL incluye parámetros de firma (signature, expires) generados automáticamente. Usar directamente la URL completa del campo files.pdf.url o files.xml.url.

Ejemplo (curl)

# Usar la URL completa devuelta por /comprobantes-fiscales/descargar
curl --location 'https://apimarket.mx/private/imss/comprobantes-fiscales/archivo/<token>/pdf?signature=...' \
  --output comprobante.pdf

Respuesta exitosa (200 OK)

Content-Type: application/pdf o application/xml
Content-Disposition: attachment; filename="<nombre_archivo>"
Cache-Control: private, max-age=3600
Body: contenido binario del archivo

Errores

Código	Descripción
400	Tipo inválido (no es `pdf` ni `xml`)
410	Token expirado o recurso ya no disponible en caché

Flujo completo

Opción A: Descarga por URL firmada (recomendado para archivos grandes)

1. POST /private/comprobantes-fiscales        → lista de comprobantes con folio_sua
2. POST /private/comprobantes-fiscales/descargar  → URLs firmadas para PDF y XML
3. GET  <files.pdf.url>                       → descarga el PDF
   GET  <files.xml.url>                       → descarga el XML

Opción B: Descarga inline en base64 (recomendado para automatización)

1. POST /private/comprobantes-fiscales                          → lista de comprobantes con folio_sua
2. POST /private/comprobantes-fiscales/descargar
     con include_content: true                                  → PDF y XML en base64
3. Decodificar files.pdf.base64 y files.xml.base64 localmente

Ejemplo: descarga masiva de múltiples periodos

Para descargar todos los CFDIs de un rango de meses (ej. julio 2025 a febrero 2026):

Iterar sobre cada periodo (anio/mes).
Para cada periodo, llamar a listar para obtener los comprobantes disponibles.
Para cada comprobante, llamar a descargar con include_content: true y el folio_sua.
Decodificar el base64 y guardar los archivos con un nombre descriptivo, ej: {RFC}_{RP}_{YYYYMM}_{folioSua}.pdf / .xml