# TimbraMX API

> API REST para timbrar, consultar y cancelar CFDI 4.0 en México. Autenticación por API key (header `X-Api-Key`). Cada cuenta tiene una key de sandbox (pruebas, sin costo, sin valor fiscal) y una de producción (requiere certificación previa). El ambiente lo decide la key usada, no la URL - una sola base para ambas.

## Recursos para agentes de IA

- [OpenAPI (contrato para máquina)](https://timbra-mx.com/docs/api/openapi.yaml): especificación completa de endpoints, schemas, ejemplos y errores.
- [llms-full.txt (documentación completa)](https://timbra-mx.com/docs/api/llms-full.txt): guía extendida en texto plano, pensada para dar contexto a un LLM.
- [Colección Postman](https://timbra-mx.com/docs/api/timbramx-api.postman_collection.json): peticiones listas para importar y probar.

## Páginas de referencia

- [API de facturación (marketing)](https://timbra-mx.com/paginas/api-rest.html): visión general, beneficios y precios por volumen.
- [Documentación de integración](https://timbra-mx.com/api-facturacion-integracion.html): endpoints, ejemplos de código (curl, Node.js, Python, PHP, C#, Java) y FAQ.

## Endpoints - Facturas

- `POST /api/v1/facturas/validar` - validar un CFDI (solo modo relay) sin timbrarlo ni gastar ningún intento con el PAC.
- `POST /api/v1/facturas` - timbrar un CFDI (modo relay: XML ya sellado en base64; o modo sellar: TimbraMX arma y sella con el CSD ya subido). Soporta header `Idempotency-Key`.
- `GET /api/v1/facturas` - listar tus facturas (paginado, filtradas por el ambiente de tu API key; filtros opcionales `estado`, `uuid`, `rfc`, `desde`/`hasta`).
- `GET /api/v1/facturas/{id}` - consultar una factura por id.
- `GET /api/v1/facturas/{id}/xml` - descargar el XML timbrado crudo (archivo, no JSON).
- `GET /api/v1/facturas/{id}/pdf` - descargar el PDF (archivo binario, no JSON).
- `GET /api/v1/facturas/{id}/acuse` - acuse de cancelación en base64 (solo si ya fue cancelada).
- `GET /api/v1/facturas/{id}/estatus-sat` - consultar en vivo ante el SAT si el CFDI sigue vigente o ya fue cancelado.
- `GET /api/v1/facturas/saldo` - consultar tus timbres disponibles.
- `POST /api/v1/facturas/{id}/cancelar` - cancelar un CFDI ya timbrado ante el SAT.
- `GET /api/v1/facturas/{id}/estatus-cancelacion` - confirmar una cancelación pendiente (sin volver a solicitarla).
- `POST /api/v1/facturas/{id}/nota-credito` - generar una nota de crédito (CFDI tipo E) que acredita, total o parcialmente, esa factura ya timbrada.

## Endpoints - Complementos de pago (CFDI tipo P)

- `POST /api/v1/complementos-pago` - timbrar un complemento de pago para una o varias facturas PPD ya timbradas (identificadas por su UUID fiscal). Soporta `Idempotency-Key`.
- `GET /api/v1/complementos-pago` - listar tus complementos de pago (paginado; filtros opcionales `estado`, `uuid`, `rfc`, `desde`/`hasta`).
- `GET /api/v1/complementos-pago/{id}` - consultar un complemento por id.
- `GET /api/v1/complementos-pago/{id}/xml` / `/pdf` - descargar el XML o PDF.
- `POST /api/v1/complementos-pago/{id}/cancelar` - cancelar el CFDI tipo P.
- `GET /api/v1/complementos-pago/{id}/estatus-cancelacion` - confirmar una cancelación pendiente.

## Endpoints - Nómina (CFDI tipo N)

- `POST /api/v1/nomina` - armar, sellar y timbrar un CFDI de Nómina 1.2 en un solo paso (siempre timbra, no guarda borrador). Soporta `Idempotency-Key`.
- `GET /api/v1/nomina` - listar tus recibos de nómina (paginado; filtros opcionales `estado`, `uuid`, `rfc`, `desde`/`hasta`).
- `GET /api/v1/nomina/{id}` - consultar un recibo por id.
- `GET /api/v1/nomina/{id}/xml` / `/pdf` - descargar el XML o PDF.
- `POST /api/v1/nomina/{id}/cancelar` - cancelar el CFDI de Nómina.
- `GET /api/v1/nomina/{id}/estatus-cancelacion` - confirmar una cancelación pendiente.

## Endpoints - Retenciones e Información de Pagos

Alcance v1: solo 3 de los 12 tipos del catálogo (`dividendos`, `enajenacion_acciones`, `pagos_extranjero`); los otros 9 solo están disponibles desde el portal.

- `POST /api/v1/retenciones` - timbrar una retención en un solo paso. Soporta `Idempotency-Key`.
- `GET /api/v1/retenciones` - listar tus retenciones (paginado; filtros opcionales `tipo`, `estado`, `uuid`, `rfc`, `desde`/`hasta`).
- `GET /api/v1/retenciones/{id}` - consultar una retención por id.
- `GET /api/v1/retenciones/{id}/xml` / `/pdf` - descargar el XML o PDF.
- `POST /api/v1/retenciones/{id}/cancelar` - cancelar la retención.
- `GET /api/v1/retenciones/{id}/estatus-cancelacion` - consultar el estatus de una cancelación en curso ante el PAC.

## Referencia oficial del SAT

- [Anexo 20 del SAT (PDF)](https://timbra-mx.com/docs/anexo20-sat.pdf) - estándar oficial del CFDI (nodos, atributos y catálogos completos). Esta documentación cubre cómo usar la API de TimbraMX, no sustituye esta especificación técnica.

## Límites

60 peticiones por minuto por cuenta (independiente entre sandbox y producción, sin importar cuántas IP uses). Sandbox nunca consume timbres ni tiene valor fiscal. Producción consume 1 timbre por timbrado exitoso, igual que timbrar desde el portal.

## Lo que falta saber antes de integrar (ver llms-full.txt para el detalle)

- **Contrato de campos completo** (tipo, obligatoriedad, longitud, catálogos) para cada endpoint de creación - ver llms-full.txt.
- **Estados**: `borrador → timbrando → timbrada | error`, y `timbrada → cancelando → cancelada | cancelacion_pendiente`. Confirmar una `cancelacion_pendiente` por API ya está disponible en los 4 recursos (`GET /{id}/estatus-cancelacion`).
- **Reintentos**: 400/401/402/403/404 no se reintentan; 409 y 429 sí tras esperar; 502 y timeouts de red sí, con el MISMO `Idempotency-Key`.
- **Sin webhooks en v1** - usa polling (`GET /:id`) para detectar cambios de estado.
- **Sin filtros por RFC/UUID/fecha** en los listados (solo `pagina`/`limite`, y `tipo` en Retenciones) - guarda tú el `id` que regresa cada POST si necesitas buscar por UUID después.
- **Sandbox sí timbra de verdad** contra el ambiente de pruebas del PAC (UUID y XML reales, sin valor fiscal) - no es una simulación local.

## Cómo empezar

1. Crea tu cuenta en https://app.timbra-mx.com/portal-login.html
2. Genera tu API key de sandbox desde el portal (vista "API").
3. Prueba tus peticiones contra `https://app.timbra-mx.com/api/v1/facturas` con el header `X-Api-Key`.
4. Cuando tu integración funcione bien en sandbox, solicita la certificación para generar tu API key de producción.