API de facturación electrónica: qué es y cómo integrarla
Si tu sistema (ERP, punto de venta, plataforma propia) necesita timbrar facturas sin pasar por un portal web, necesitas una API de facturación. Te explicamos qué tipos existen y cómo integrar la de TimbraMX paso a paso.
¿Qué es una API de facturación electrónica?
Es un servicio REST que automatiza el timbrado: la validación y registro de un CFDI ante el SAT a través de un PAC (Proveedor Autorizado de Certificación), para que tenga validez fiscal. En vez de capturar cada factura a mano en un portal, tu propio sistema (ERP, punto de venta, e-commerce) le manda la petición directamente y recibe el folio fiscal (UUID) en segundos.
API de timbrado vs. API de generación
No todas las APIs de facturación hacen lo mismo - esta diferencia es la que más confunde al elegir proveedor:
| API de generación | API de timbrado (TimbraMX) | |
|---|---|---|
| Qué le mandas | Datos en JSON (cliente, conceptos, montos). | El XML del CFDI ya armado y sellado con tu CSD. |
| Quién arma el XML | El proveedor, a partir de tu JSON. | Tú (o tu librería/SDK de CFDI). |
| Control sobre el XML | Limitado a lo que el proveedor soporte. | Total - cualquier nodo, complemento o addenda que tú puedas generar. |
Si tu sistema ya sabe construir y sellar un CFDI (o usas una librería que lo hace), una API de timbrado como la de TimbraMX es más simple y directa. Si no, necesitas una API de generación que arme el XML por ti.
Autenticación
Se usa el header X-Api-Key. Generas tu llave desde tu cuenta, en Mi empresa > API - solo el dueño de la cuenta puede generarla o regenerarla, no un sub-usuario.
El endpoint para timbrar
Timbra un CFDI que ya generaste y sellaste con tu CSD (el timbrado en sí lo hace TimbraMX):
POST /api/v1/facturas
Content-Type: application/json
X-Api-Key: tu_api_key
{ "xml": "<XML del CFDI ya sellado, en base64>" }
Respuesta y manejo de errores
- •201: timbrado exitoso - regresa el id interno, estado y el XML ya timbrado (con su UUID).
- •400: el XML enviado no es válido o falta.
- •402: no tienes timbres disponibles en tu saldo.
- •502: el PAC rechazó el CFDI - la respuesta incluye el código y detalle real del error para que sepas qué corregir.
Consultar tus facturas
Además de timbrar, puedes listar y consultar lo que ya timbraste vía API:
GET /api/v1/facturas?pagina=1&limite=20 GET /api/v1/facturas/:id
Ambos endpoints solo regresan facturas que pertenecen a tu propia cuenta, identificada por tu API Key.
Límites y costo
La API acepta hasta 60 peticiones por minuto. Cada timbrado exitoso consume un timbre de tu saldo - el mismo costo que timbrar desde el portal, sin cargo adicional por usar la API.
¿Listo para integrar tu sistema?
Crea tu cuenta gratis y genera tu API Key desde Mi empresa.
Crear mi cuenta gratis