CFDIX API · v1

Guía de la API para desarrolladores.

Integra solicitudes de facturación de forma asíncrona. Envía datos estructurados, inicia desde una imagen privada o aporta lo que faltaba después. Cada solicitud conserva su rastreo y sus límites.

Ver la API Descargar OpenAPI

01 / INTEGRA

Tres caminos, un expediente trazable

Elige el origen de la información que ya tienes. Los tres caminos responden rápido y continúan fuera de la petición HTTP.

Datos estructurados

Si tu sistema ya leyó el ticket y cuenta con los datos requeridos, crea directamente la solicitud.

POST /api/v1/invoice-requests

Incluye una Idempotency-Key única para esa intención.

Imagen del ticket

Carga una imagen privada y después crea la solicitud con su ticket_image_id. La carga no ejecuta OCR dentro de esa petición.

POST /api/v1/ticket-images POST /api/v1/invoice-requests

Aporta o corrige

Completa una solicitud iniciada con imagen sin reemplazar su historial. La aportación queda registrada de forma append-only.

POST /api/v1/invoice-requests/{requestId}/data-contributions

02 / CONSULTA

Protege cada intento contra duplicados

Autentica con una API key de la aplicación y conserva la llave fuera de tu código fuente. Nunca la pegues en esta página, en una URL ni en el navegador de un usuario final.

Authorization: Bearer ${CFDIX_API_KEY}
Idempotency-Key: compra-2026-09-10-001
X-Correlation-ID: integracion-001

Después de crear

Guarda el ULID y el X-Correlation-ID.
Consulta GET /api/v1/invoice-requests/{requestId}.
Respeta el estado y el indicador retryable.
Descarga XML/PDF sólo mediante el endpoint autenticado de artefactos.

03 / SIN SORPRESAS

Límites explícitos de CFDIX

CFDIX no es un PAC y no timbra CFDI.
Una respuesta aceptada no confirma la emisión, el XML ni el PDF.
CAPTCHA, OTP, login y controles anti-bot se detectan y escalan; no se evaden.
No reintentes a ciegas una respuesta ambigua ni reenvíes una acción externa sin verificar su estado.

04 / ESTADOS

Estados canónicos de la solicitud

El contrato OpenAPI define estos valores para status. Programa sobre ellos; no infieras resultado a partir de un mensaje del portal.

RECEIVED
VALIDATING
NEEDS_INFORMATION
QUEUED
PROCESSING
WAITING_EXTERNAL
REQUIRES_HUMAN
SUCCEEDED
FAILED_RETRYABLE
FAILED_FINAL
REJECTED
CANCELED
EXPIRED

05 / REFERENCIA

Referencia derivada del contrato

Esta lista se construye desde el OpenAPI versionado del repositorio. Descárgalo para generar o validar tu cliente.

POST/api/v1/ticket-images

uploadTicketImage

Cargar una imagen privada de ticket

Registra evidencia privada temporal e idempotente. No crea un ticket controlado ni ejecuta OCR dentro de la petición HTTP.

Scopes: invoice_requests:create

Idempotency-Key header · requerido: Clave única por tenant y aplicación. La misma clave con payload diferente produce conflicto.
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Replay idempotente.
201 Imagen privada almacenada.
400 Solicitud mal formada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
409 Conflicto de idempotencia o transición de estado.
422 Datos estructurados semánticamente inválidos.
429 Límite temporal excedido.

POST/api/v1/invoice-requests

createInvoiceRequest

Aceptar una solicitud de facturación

Crea de forma idempotente una solicitud para procesamiento asíncrono. La respuesta no implica emisión ni timbrado.

Scopes: invoice_requests:create

Idempotency-Key header · requerido: Clave única por tenant y aplicación. La misma clave con payload diferente produce conflicto.
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Replay idempotente: se devuelve la solicitud existente.
202 Solicitud aceptada.
400 Solicitud mal formada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
409 Conflicto de idempotencia o transición de estado.
422 Datos estructurados semánticamente inválidos.
429 Límite temporal excedido.
500 Error interno seguro, sin stack, SQL ni rutas.

GET/api/v1/invoice-requests

listInvoiceRequests

Listar solicitudes de la aplicación

Scopes: invoice_requests:read

X-Correlation-ID header: Identificador de trazabilidad del cliente.
cursor query
page_size query
status query

200 Página de solicitudes.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
429 Límite temporal excedido.

POST/api/v1/invoice-requests/{requestId}/data-contributions

contributeInvoiceRequestData

Aportar o corregir datos de una solicitud iniciada con imagen

Registra una aportación append-only e idempotente. Cuando el agregado queda completo crea snapshots inmutables y encola la validación.

Scopes: invoice_requests:create

requestId path · requerido
Idempotency-Key header · requerido: Clave única por tenant y aplicación. La misma clave con payload diferente produce conflicto.
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Aportación parcial o replay idempotente.
202 Datos completos; validación asíncrona encolada.
400 Solicitud mal formada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.
409 Conflicto de idempotencia o transición de estado.
422 Datos estructurados semánticamente inválidos.
429 Límite temporal excedido.

GET/api/v1/invoice-requests/{requestId}

getInvoiceRequest

Consultar una solicitud

Scopes: invoice_requests:read

requestId path · requerido
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Solicitud encontrada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.
429 Límite temporal excedido.

POST/api/v1/invoice-requests/{requestId}/cancel

cancelInvoiceRequest

Cancelar una solicitud elegible

Scopes: invoice_requests:cancel

requestId path · requerido
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Solicitud cancelada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.
409 Conflicto de idempotencia o transición de estado.
429 Límite temporal excedido.

POST/api/v1/invoice-requests/{requestId}/retry

retryInvoiceRequest

Solicitar un reintento seguro

Scopes: invoice_requests:retry

requestId path · requerido
X-Correlation-ID header: Identificador de trazabilidad del cliente.

202 Reintento aceptado.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.
409 Conflicto de idempotencia o transición de estado.
429 Límite temporal excedido.

GET/api/v1/invoice-requests/{requestId}/artifacts

listInvoiceRequestArtifacts

Listar artefactos de una solicitud

Scopes: artifacts:read

requestId path · requerido
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Artefactos autorizados.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.

GET/api/v1/artifacts/{artifactId}/download

downloadArtifact

Descargar un artefacto autorizado

Scopes: artifacts:read

artifactId path · requerido
X-Correlation-ID header: Identificador de trazabilidad del cliente.

200 Contenido binario original.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.
410 El artefacto expiró o fue retirado.

GET/api/v1/fiscal-profiles

listFiscalProfiles

Listar perfiles fiscales del tenant autenticado

Scopes: fiscal_profiles:read

X-Correlation-ID header: Identificador de trazabilidad del cliente.
cursor query
page_size query

200 Página de perfiles.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.

POST/api/v1/fiscal-profiles

createFiscalProfile

Crear un perfil fiscal

Scopes: fiscal_profiles:write

X-Correlation-ID header: Identificador de trazabilidad del cliente.

201 Perfil fiscal creado.
400 Solicitud mal formada.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
409 Conflicto de idempotencia o transición de estado.
422 Datos estructurados semánticamente inválidos.

GET/api/v1/fiscal-profiles/{profile_id}

getFiscalProfile

Consultar un perfil fiscal

Scopes: fiscal_profiles:read

X-Correlation-ID header: Identificador de trazabilidad del cliente.
profile_id path · requerido

200 Perfil fiscal encontrado.
401 Credencial ausente, inválida o revocada.
403 Scope o acceso al recurso insuficiente.
404 Recurso inexistente dentro del tenant y aplicación autenticados.