1. Configuración en SOATI
Se crea un usuario de API, se genera una API key única, se asocia a una empresa/RFC y se define si la respuesta será XML o XML + PDF.
API de timbrado CFDI
SOATI E-Factura
Conecta tu ERP con SOATI para timbrar XML CFDI por PAC
La API de timbrado CFDI permite que sistemas externos envíen XML de facturas, se autentiquen con usuario y API key, consuman timbres disponibles y reciban la respuesta del PAC en formato XML o XML + PDF.
POST /efactura/v1/cfdi/timbrado
X-Api-User: usuario_api
X-Api-Key: soati_live_********
Idempotency-Key: ERP-FAC-2026-000001
{
"rfc_emisor": "AAA010101AAA",
"response_format": "xml_pdf",
"xml_base64": "PD94bWwgdmVyc2lvbj0..."
}Arquitectura
Flujo completo: cliente, API, PAC y respuesta
El servicio se diseña como una capa REST sobre SOATI E-Factura. El ERP no necesita conocer infraestructura interna: solo prepara el XML, autentica la solicitud y procesa la respuesta.
2. Envío desde el ERP
El sistema externo envía el XML CFDI por HTTPS con headers de autenticación, referencia externa e idempotencia para reintentos seguros.
3. Validación fiscal y operativa
SOATI valida autorización del RFC, estructura XML, saldo de timbres, límites de consumo, duplicados y condiciones de seguridad antes de llamar al PAC.
4. Timbrado y respuesta
El XML se envía al PAC. Si el timbrado es correcto, se registra el consumo de timbres y se devuelve XML timbrado o XML + PDF.
Seguridad
Diseñada para integraciones empresariales
La API se plantea con controles alineados a buenas prácticas OWASP, operación por TLS 1.2 o superior y trazabilidad útil para procesos de auditoría internos.
Autenticación por API key
Cada integrador opera con usuario de API y llave única. Las llaves deben poder regenerarse, revocarse y auditarse sin exponer secretos.
TLS 1.2 o superior
La integración se diseña para operar solo por HTTPS, con validación de certificados y sin credenciales en parámetros de URL.
Control de timbres
Antes de timbrar se valida el saldo disponible con la misma lógica de TIMBRES que usa SOATI E-Factura en operación diaria.
Auditoría y trazabilidad
Cada solicitud conserva request_id, referencia externa, IP, fecha, estatus, UUID, respuesta PAC y timbres consumidos.
Rate limiting
Los límites por minuto y por día ayudan a proteger el servicio de errores de integración, reintentos agresivos o uso no autorizado.
Idempotencia
El ERP puede reintentar una solicitud con la misma clave de idempotencia sin duplicar timbrado ni consumo de timbres.
Endpoints
Superficie técnica propuesta
Los endpoints se mantienen simples para facilitar integración desde cualquier ERP o lenguaje. La URL final y las credenciales se entregan durante la activación del servicio.
| Método | Ruta | Uso |
|---|---|---|
| POST | /efactura/v1/cfdi/timbrado | Recibe XML CFDI y devuelve XML timbrado o XML + PDF. |
| GET | /efactura/v1/cfdi/timbrado/{request_id} | Consulta el estado de una solicitud previa. |
| GET | /efactura/v1/timbres/estado | Consulta timbres disponibles locales y estado PAC cuando aplique. |
| GET | /efactura/v1/health | Verifica disponibilidad controlada del servicio. |
Timbres
Control de saldo antes de llamar al PAC
La integración debe respetar la operación actual de SOATI E-Factura: el saldo se consulta contra la tabla TIMBRES por grupo, se rechaza la solicitud si no hay saldo y el consumo se registra solo si el PAC devuelve timbrado correcto.
SELECT ISNULL(SUM(COSTO), 0) AS TIMBRES
FROM dbo.TIMBRES WITH (NOLOCK)
WHERE GRUPO = @Grupo;Compatibilidad
Para ERPs y sistemas externos
La especificación se basa en estándares abiertos: HTTPS, JSON, XML, OpenAPI, códigos HTTP e idempotencia para reintentos seguros.
ERP administrativo
El ERP conserva su captura y manda XML CFDI a SOATI para timbrado, auditoría y control de timbres.
Sistema .NET o desktop
Un servicio local o job envía XML firmados, guarda request_id y recupera XML/PDF timbrados para su expediente.
E-commerce o portal web
La tienda genera el comprobante, usa una clave de idempotencia por pedido y recibe el XML timbrado para entregar al cliente.
Respuesta
XML timbrado o XML + PDF
El integrador puede recibir solo el XML timbrado para almacenarlo en su ERP, o solicitar XML + PDF cuando necesite entregar representación impresa al cliente final.
- Respuesta JSON con XML/PDF en base64.
- Respuesta XML directa usando
Accept: application/xml. - UUID, request_id, respuesta PAC y timbres consumidos.
- Consulta posterior por request_id para reintentos o conciliación.
{
"status": "timbrado",
"request_id": "7f2a9c52-9d51-46b5-bcb4-646c88a7ad90",
"uuid": "11111111-2222-3333-4444-555555555555",
"xml_base64": "PD94bWwgdmVyc2lvbj0...",
"pdf_base64": "JVBERi0xLjQKJc...",
"timbres": {
"consumidos": 1,
"saldo_despues": 124
}
}Implementación
Pasos para iniciar una integración
- Solicita la activación del servicio API para tu empresa/RFC.
- Define si la respuesta default será XML o XML + PDF.
- Genera un usuario de API y conserva la API key en un almacén seguro.
- Prepara XML CFDI válidos desde tu ERP y asigna una clave de idempotencia por documento.
- Realiza pruebas con un volumen controlado y registra request_id, UUID y mensajes PAC.
- Activa monitoreo de errores, rate limit y conciliación de timbres.
Preguntas frecuentes
Dudas comunes sobre la API de timbrado CFDI
¿La API genera el XML desde conceptos?
La primera integración está pensada para recibir XML CFDI ya formado y sellado por el sistema externo. La generación de XML desde conceptos, clientes e impuestos es un alcance distinto.
¿Puede devolver PDF además del XML?
Sí. El usuario de API puede configurarse para respuesta XML o XML + PDF, según el flujo operativo contratado.
¿Cómo se controla el consumo de timbres?
La API debe validar saldo antes de timbrar y registrar el consumo en la tabla TIMBRES después del timbrado correcto, igual que el flujo interno de SOATI E-Factura.
¿Funciona con cualquier lenguaje?
Sí. Al usar HTTPS, JSON, XML y OpenAPI, la integración puede consumirse desde JavaScript, Python, .NET, PHP, Java, SAP, ERPs propios u otros sistemas.
Integra tu ERP con SOATI E-Factura
Cuéntanos qué ERP o sistema quieres conectar, cuántos CFDI emites al día y si necesitas respuesta XML o XML + PDF.
También puedes escribir a contacto [arroba] soati.mx o llamar al (55) 5556-1730.
