# Referencia de la API de CFDI Express

> API REST para timbrar CFDI 4.0 ante el SAT desde cualquier sistema que hable HTTPS: facturas PUE, PPD y globales, notas de crédito, complementos de pago REP (Pagos 2.0) y cancelaciones con acuse. Convenciones estilo Stripe: llaves `sk_test_`/`sk_live_`, errores problem+json, idempotencia y paginación por cursor. $1 MXN por timbre, saldo prepagado, sandbox gratis.

- URL base: https://api.cfdi.express (todos los endpoints de v1 llevan el prefijo /v1)
- Esta referencia: https://cfdi.express/docs/api
- OpenAPI: https://api.cfdi.express/openapi.json
- Docs interactivas: https://api.cfdi.express/docs
- Llaves y saldo: https://dash.cfdi.express
- Servidor MCP para agentes de IA: https://api.cfdi.express/mcp (pruebas: https://api.cfdi.express/mcp/test) — https://cfdi.express/docs/api/mcp

## Autenticación

Cada request lleva la llave secreta como bearer token: `Authorization: Bearer sk_live_…`.
La llave define el modo: `sk_test_` timbra contra el sandbox del PAC sin costo y `sk_live_` emite CFDIs con validez fiscal. Cada modo tiene su propio saldo, emisores y documentos; todos los recursos traen el campo `livemode`.

## Idempotencia

Los endpoints que timbran o cancelan requieren el header `Idempotency-Key` con un valor estable por operación lógica. Un replay devuelve la respuesta original con `Idempotency-Replayed: true`; dos peticiones concurrentes con la misma llave dan `409 request_in_flight`; la misma llave con otro cuerpo da `422 idempotency_key_reuse`.

## Paginación

Listas con cursor: `limit` (máximo 100) y `starting_after` con el id del último elemento mientras `has_more` sea `true`.

## Errores

Formato `application/problem+json` (RFC 7807) con un `code` estable: `validation_error` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `insufficient_credits` y `monthly_limit_reached` (402), `request_in_flight` (409), `idempotency_key_reuse` y `sat_rejected` (422), `rate_limited` (429), `pac_unavailable` y `billing_unavailable` (503), `internal_error` (500). Las validaciones incluyen `errors[]` con el path del campo; la validación de CSD incluye `subcode`.

## Límites

- 300 requests por minuto por cuenta (configurable), con `429` y `Retry-After`.
- Cuerpo máximo de 1 MB y hasta 500 conceptos por factura.
- Las URLs de XML, PDF, ZIP, acuses y logos son firmadas y expiran a los 15 minutos.

## Endpoints

### Meta

Endpoints públicos de salud del servicio. No requieren llave y sirven para monitoreo.

- `GET /health` — Sonda de vida del servicio. Responde 200 mientras el proceso esté arriba, sin tocar base de datos ni Redis. → https://cfdi.express/docs/api/health (markdown: https://cfdi.express/docs/api/health/llms.txt)
- `GET /ready` — Verifica que las dependencias del servicio (Postgres y Redis) estén alcanzables. Responde 503 si alguna falla. → https://cfdi.express/docs/api/ready (markdown: https://cfdi.express/docs/api/ready/llms.txt)

### Saldo y facturación

Consulta tu saldo prepagado, recarga con tarjeta vía Stripe y audita cada centavo con el ledger de transacciones.

- `GET /v1/balance` — Devuelve el saldo prepagado de la cuenta, el precio por timbre vigente y cuántos timbres te quedan. → https://cfdi.express/docs/api/saldo (markdown: https://cfdi.express/docs/api/saldo/llms.txt)
- `POST /v1/billing/checkout_sessions` — Crea una sesión de Stripe Checkout para recargar saldo con tarjeta. Redirige al usuario a la URL que regresa. → https://cfdi.express/docs/api/recargar-saldo (markdown: https://cfdi.express/docs/api/recargar-saldo/llms.txt)
- `POST /v1/billing/portal_sessions` — Crea una sesión del Billing Portal de Stripe para que el usuario administre métodos de pago y descargue recibos. → https://cfdi.express/docs/api/portal-de-facturacion (markdown: https://cfdi.express/docs/api/portal-de-facturacion/llms.txt)
- `GET /v1/billing/usage` — Timbres consumidos y centavos gastados por mes, del más reciente al más antiguo. → https://cfdi.express/docs/api/uso-mensual (markdown: https://cfdi.express/docs/api/uso-mensual/llms.txt)
- `GET /v1/billing/transactions` — El ledger completo de tu saldo: cada recarga, consumo, reembolso y ajuste con el saldo resultante. → https://cfdi.express/docs/api/transacciones (markdown: https://cfdi.express/docs/api/transacciones/llms.txt)

### Emisores (merchants)

Cada emisor es un RFC con su propio CSD, serie y logo. Una cuenta puede tener varios emisores activos al mismo tiempo.

- `POST /v1/merchants` — Registra un RFC emisor con su régimen fiscal, código postal de expedición y serie. Es el primer paso antes de timbrar. → https://cfdi.express/docs/api/crear-emisor (markdown: https://cfdi.express/docs/api/crear-emisor/llms.txt)
- `GET /v1/merchants` — Lista los emisores de la cuenta en el modo de tu llave, con paginación por cursor. → https://cfdi.express/docs/api/listar-emisores (markdown: https://cfdi.express/docs/api/listar-emisores/llms.txt)
- `GET /v1/merchants/{id}` — Devuelve un emisor con los metadatos de su CSD (número de serie, vigencia y si ya está registrado con el PAC). → https://cfdi.express/docs/api/obtener-emisor (markdown: https://cfdi.express/docs/api/obtener-emisor/llms.txt)
- `PATCH /v1/merchants/{id}` — Actualiza razón social, régimen fiscal, código postal, serie o las claves SAT por default. El RFC no se puede cambiar. → https://cfdi.express/docs/api/actualizar-emisor (markdown: https://cfdi.express/docs/api/actualizar-emisor/llms.txt)
- `DELETE /v1/merchants/{id}` — Baja lógica del emisor. Deja de poder timbrar, pero sus CFDIs históricos siguen consultables. → https://cfdi.express/docs/api/eliminar-emisor (markdown: https://cfdi.express/docs/api/eliminar-emisor/llms.txt)
- `POST /v1/merchants/{id}/csd` — Sube el CSD del emisor (.cer y .key en base64 más la contraseña). Se valida, se encripta y se registra con el PAC. → https://cfdi.express/docs/api/subir-csd (markdown: https://cfdi.express/docs/api/subir-csd/llms.txt)
- `PUT /v1/merchants/{id}/csd` — Sustituye el CSD del emisor por uno nuevo, típicamente al renovarlo antes de que venza. Mismas validaciones que al subirlo. → https://cfdi.express/docs/api/reemplazar-csd (markdown: https://cfdi.express/docs/api/reemplazar-csd/llms.txt)
- `GET /v1/merchants/{id}/csd` — Metadatos del certificado activo: número de serie, RFC, vigencia y si está registrado con el PAC. Nunca devuelve la llave privada. → https://cfdi.express/docs/api/obtener-csd (markdown: https://cfdi.express/docs/api/obtener-csd/llms.txt)
- `PUT /v1/merchants/{id}/logo` — Sube la imagen que aparece en el encabezado de los PDFs del emisor. PNG, JPEG o WebP en base64, máximo 500 KB. → https://cfdi.express/docs/api/subir-logo (markdown: https://cfdi.express/docs/api/subir-logo/llms.txt)
- `DELETE /v1/merchants/{id}/logo` — Quita el logo del emisor. Los PDFs que se generen después muestran sólo la razón social. → https://cfdi.express/docs/api/eliminar-logo (markdown: https://cfdi.express/docs/api/eliminar-logo/llms.txt)

### Facturas

Timbrado de CFDI 4.0 de ingreso: nominativas PUE y PPD, y facturas globales al público en general.

- `POST /v1/invoices` — Timbra un CFDI 4.0 de ingreso: nominativo PUE o PPD, o global al público en general. El motor de impuestos calcula IVA e IEPS por ti. → https://cfdi.express/docs/api/timbrar-factura (markdown: https://cfdi.express/docs/api/timbrar-factura/llms.txt)
- `GET /v1/invoices` — Lista facturas con filtros por emisor, tipo, estatus, método de pago, UUID y rango de fechas. Paginación por cursor. → https://cfdi.express/docs/api/listar-facturas (markdown: https://cfdi.express/docs/api/listar-facturas/llms.txt)
- `GET /v1/invoices/{id}` — Devuelve la factura con su estatus, UUID, datos de cancelación y las URLs firmadas del XML, el PDF y el ZIP. → https://cfdi.express/docs/api/obtener-factura (markdown: https://cfdi.express/docs/api/obtener-factura/llms.txt)
- `POST /v1/invoices/{id}/cancel` — Cancela ante el SAT un CFDI timbrado, con motivo 01–04, y guarda el acuse de cancelación. → https://cfdi.express/docs/api/cancelar-factura (markdown: https://cfdi.express/docs/api/cancelar-factura/llms.txt)

### Notas de crédito

CFDI de egreso para devoluciones, reembolsos y descuentos posteriores a la factura.

- `POST /v1/credit_notes` — Timbra un CFDI 4.0 de egreso para una devolución, un reembolso o un descuento posterior a la factura. → https://cfdi.express/docs/api/crear-nota-de-credito (markdown: https://cfdi.express/docs/api/crear-nota-de-credito/llms.txt)

### Complementos de pago (REP)

Pagos 2.0 contra facturas PPD, con parcialidades y saldos calculados en el servidor.

- `POST /v1/invoices/{id}/payments` — Registra un pago recibido contra una factura PPD y timbra su complemento de pago (Pagos 2.0). → https://cfdi.express/docs/api/timbrar-complemento-de-pago (markdown: https://cfdi.express/docs/api/timbrar-complemento-de-pago/llms.txt)
- `GET /v1/payments/{id}` — Devuelve el complemento de pago con su UUID, los saldos del momento del pago y las URLs firmadas de sus archivos. → https://cfdi.express/docs/api/obtener-complemento-de-pago (markdown: https://cfdi.express/docs/api/obtener-complemento-de-pago/llms.txt)
- `GET /v1/payments` — Lista los complementos de pago de la cuenta con filtros por factura, emisor, estatus, UUID y fechas. → https://cfdi.express/docs/api/listar-complementos-de-pago (markdown: https://cfdi.express/docs/api/listar-complementos-de-pago/llms.txt)
- `POST /v1/payments/{id}/cancel` — Cancela ante el SAT un complemento de pago timbrado y restaura el saldo pendiente de la factura. → https://cfdi.express/docs/api/cancelar-complemento-de-pago (markdown: https://cfdi.express/docs/api/cancelar-complemento-de-pago/llms.txt)

### Catálogos SAT

Claves de producto/servicio, unidades, usos de CFDI, regímenes fiscales y formas de pago servidos desde nuestra base local.

- `GET /v1/catalogs/products` — Búsqueda por palabra clave sobre las más de 52 000 claves del catálogo c_ClaveProdServ, incluidos los sinónimos del SAT. → https://cfdi.express/docs/api/catalogo-productos (markdown: https://cfdi.express/docs/api/catalogo-productos/llms.txt)
- `GET /v1/catalogs/units` — Búsqueda por palabra clave sobre el catálogo c_ClaveUnidad. Devuelve clave, nombre y símbolo. → https://cfdi.express/docs/api/catalogo-unidades (markdown: https://cfdi.express/docs/api/catalogo-unidades/llms.txt)
- `GET /v1/catalogs/usos-cfdi` — Catálogo completo c_UsoCFDI, con banderas de si aplica a persona física, moral o ambas. → https://cfdi.express/docs/api/catalogo-usos-cfdi (markdown: https://cfdi.express/docs/api/catalogo-usos-cfdi/llms.txt)
- `GET /v1/catalogs/regimenes` — Catálogo completo c_RegimenFiscal con las banderas de persona física y moral. → https://cfdi.express/docs/api/catalogo-regimenes (markdown: https://cfdi.express/docs/api/catalogo-regimenes/llms.txt)
- `GET /v1/catalogs/formas-pago` — Catálogo completo c_FormaPago con clave y descripción. → https://cfdi.express/docs/api/catalogo-formas-pago (markdown: https://cfdi.express/docs/api/catalogo-formas-pago/llms.txt)

## Agentes de IA (MCP)

El servidor MCP en https://api.cfdi.express/mcp (y https://api.cfdi.express/mcp/test para pruebas) expone 14 herramientas —create_invoice, create_credit_note, get_invoice, list_invoices, cancel_invoice, create_payment, get_payment, list_payments, cancel_payment, list_merchants, search_product_codes, search_unit_codes, get_catalog y get_balance— con autenticación por API key u OAuth 2.1. Guía: https://cfdi.express/docs/api/mcp (markdown: https://cfdi.express/docs/api/mcp/llms.txt).