Cómo integrar una API de facturación SAT en tu sistema

Integrar una API de timbrado CFDI debería tomar horas, no semanas. Esta guía cubre los conceptos técnicos que necesitas para conectar tu ERP, nómina o sistema de facturación a la API de IpsoFactura: autenticación, campos requeridos y manejo de errores.

Autenticación: API key en el header

La API usa autenticación por API key en el header HTTP. No hay OAuth, no hay tokens que renovar, no hay flujos de autorización complejos. Incluyes tu key en cada request:

x-api: tu_api_key_aqui
Content-Type: application/json

Recibes keys separadas para producción y sandbox durante el onboarding, y puedes rotarlas o revocarlas en cualquier momento sin afectar las otras.

Endpoint principal: POST /cfdi/timbrar

El endpoint de timbrado recibe los datos del comprobante en JSON — IpsoFactura arma el XML, lo sella con el CSD de tu empresa y lo timbra. El timbrado a partir de XML pre-sellado está en desarrollo (próximamente).

POST https://api.ipsofactura.com/cfdi/timbrar

{
  "rfc_emisor": "PAL200101AB1",
  "tipo_comprobante": "I",
  "forma_pago": "03",
  "metodo_pago": "PUE",
  "moneda": "MXN",
  "subtotal": 10000.00,
  "total": 11600.00,
  "receptor": {
    "rfc": "CLI210315XY2",
    "nombre": "CLIENTE EJEMPLO",
    "domicilio_fiscal": "06600",
    "regimen_fiscal": "601",
    "uso_cfdi": "G03"
  },
  "conceptos": [
    {
      "clave_prod_serv": "81111806",
      "clave_unidad": "E48",
      "cantidad": 1,
      "descripcion": "Procesamiento electrónico de información",
      "valor_unitario": 10000.00,
      "importe": 10000.00,
      "objeto_imp": "02",
      "impuestos": {
        "traslados": [
          { "base": 10000.00, "impuesto": "002", "tipo_factor": "Tasa", "tasa_o_cuota": "0.160000", "importe": 1600.00 }
        ]
      }
    }
  ],
  "impuestos": {
    "total_impuestos_trasladados": 1600.00,
    "traslados": [
      { "base": 10000.00, "impuesto": "002", "tipo_factor": "Tasa", "tasa_o_cuota": "0.160000", "importe": 1600.00 }
    ]
  }
}

Los datos del emisor (nombre fiscal, régimen, código postal) no van en cada request: se registran una sola vez con POST /empresas y basta el rfc_emisor para referenciarlos.

Respuesta exitosa

HTTP 201 Created

{
  "id": "9a4f07ff-3abc-435f-b7a6-88c2bc65b4c1",
  "uuid": "6128396f-c09b-4ec6-8699-43da5a244971",
  "serie": null,
  "folio": "1",
  "fecha_timbrado": "2026-06-10T14:23:45",
  "numero_certificado_sat": "00001000000500000000",
  "sello_cfdi": "...",
  "sello_sat": "...",
  "cadena_original_sat": "||1.1|6128396f-...||"
}

El uuid es el folio fiscal del SAT — guárdalo en tu base de datos. El XML timbrado y el PDF se descargan con GET /cfdi/{id}/xml y GET /cfdi/{id}/pdf usando el id de la respuesta.

Tiempo de respuesta

En condiciones normales, el timbrado tarda entre 200ms y 800ms. Si el PAC primario no responde en 1s, IpsoFactura conmuta al siguiente automáticamente. Desde tu perspectiva, el request siempre devuelve un resultado en menos de 3s.

Campos obligatorios en CFDI 4.0

Estos son los campos que el SAT valida y que generan más rechazos cuando no coinciden:

receptor.domicilioFiscalReceptor: código postal fiscal del receptor, no el de la dirección de entrega. Obligatorio en 4.0.
receptor.nombre: debe coincidir exactamente con el nombre que el SAT tiene registrado para ese RFC (tal como aparece en su constancia de situación fiscal, sin el sufijo de régimen de capital).
receptor.regimenFiscalReceptor: el régimen fiscal del receptor según su constancia de situación fiscal.
emisor.regimenFiscal: el régimen fiscal del emisor. Debe corresponder al tipo de persona (601 para personas morales en régimen general).
conceptos[].claveProdServ: clave del catálogo SAT del producto o servicio. 81111806 corresponde a servicios de procesamiento de datos.

Manejo de errores

Los errores devuelven siempre un JSON con code (código estable en SCREAMING_SNAKE_CASE) y message. El failover entre PACs es transparente: cuando el SAT rechaza el CFDI recibes un solo error, con el código de rechazo (tipo CFDIxxxxx) dentro de message:

HTTP 400 Bad Request

{
  "code": "VALIDATION_ERROR",
  "message": "CFDI40161 - El UsoCFDI 'D01' no es aplicable para el RegimenFiscal '601' del receptor."
}

Los errores de validación previa son más baratos — IpsoFactura los detecta antes de consumir un timbre.

Errores más comunes

INVALID_RFC_FORMAT — RFC con formato incorrecto
VALIDATION_ERROR — el CFDI no pasó las validaciones del SAT; el código CFDIxxxxx exacto viene en message
CALCULATION_MISMATCH — los importes no cuadran (impuestos vs. conceptos vs. total)
CERTIFICATE_EXPIRED — el certificado de sello digital del emisor está vencido
DUPLICATE_INVOICE — ya existe un CFDI timbrado con la misma serie y folio (protección contra doble timbre)

El catálogo completo de códigos está en la documentación de errores.

Confirmación del timbrado

El timbrado es síncrono: la respuesta del POST /cfdi/timbrar ya trae el UUID y el timbre fiscal — no necesitas polling ni callbacks para confirmar. Los webhooks (notificaciones push al timbrar, cancelar o detectar errores) están en desarrollo y se anunciarán en la documentación cuando estén disponibles.

Sandbox

El ambiente de sandbox genera CFDIs simulados —con UUID y timbre de estructura completa— usando los CSD de prueba que publica el SAT. Los timbres de sandbox no tienen costo y no son válidos fiscalmente — son solo para pruebas de integración.

# Sandbox
POST https://sandbox.api.ipsofactura.com/cfdi/timbrar

# Producción
POST https://api.ipsofactura.com/cfdi/timbrar

La única diferencia entre sandbox y producción es el host. El payload y la respuesta son idénticos. Esto facilita mover la integración de un ambiente al otro sin cambios en el código.