APIs Gubernamentales de LATAM: Guía Técnica de Integración

Si has intentado integrar una API gubernamental en Latinoamérica, sabes que la documentación oficial es un ejercicio de fe. Endpoints que cambian sin aviso, autenticación basada en certificados digitales emitidos en formatos arcanos, límites de rate no documentados, y sandboxes que no se parecen en nada a producción.

Esta guía recopila lo que hemos aprendido integrando APIs gubernamentales en México, Panamá, Colombia y Perú durante los últimos cuatro años. No es documentación oficial — es documentación que funciona.

Madurez de APIs Gubernamentales por País

No todas las APIs gubernamentales son iguales. Antes de planificar tu integración, necesitas saber qué esperar:

| País | Entidad | Madurez API | Documentación | Sandbox | Estabilidad | |---|---|---|---|---|---| | México | SAT | Alta | Buena (pero dispersa) | Sí (funcional) | Media-Alta | | Colombia | DIAN | Media-Alta | Aceptable | Sí (limitado) | Media | | Perú | SUNAT | Media | Deficiente | Parcial | Baja-Media | | Panamá | DGI | Baja-Media | Mínima | No oficial | Baja | | Chile | SII | Alta | Buena | Sí (funcional) | Alta | | Argentina | AFIP | Media | Aceptable | Sí (inestable) | Baja |

La regla general: cuanto más grande la economía y más avanzada la facturación electrónica del país, mejor la API. Chile y México lideran. Centroamérica va rezagada pero avanzando rápido.

México: SAT (Servicio de Administración Tributaria)

El SAT tiene el ecosistema de APIs más maduro de LATAM, principalmente porque la facturación electrónica (CFDI) es obligatoria desde 2014 y mueve más de 8 mil millones de facturas anuales.

Autenticación

El SAT usa dos métodos de autenticación:

1. FIEL (Firma Electrónica Avanzada) / e.firma:

• Basada en certificados X.509
• Archivos necesarios: .cer (certificado público), .key (llave privada), y password
• El .key viene en formato DER codificado con algoritmo propietario del SAT
• Para usar en tu aplicación, necesitas convertir a PEM:

# Convertir .key de DER a PEM
openssl pkcs8 -inform DER -in tu_archivo.key -out llave_privada.pem -passin pass:TU_PASSWORD

# Convertir .cer de DER a PEM
openssl x509 -inform DER -in tu_archivo.cer -out certificado.pem

2. Contraseña CIEC (para consultas básicas):

• RFC + contraseña
• Solo funciona para consultas, no para firmar documentos
• Útil para verificación de datos pero no para emisión de CFDI

Endpoints Principales

Verificación de RFC:

• URL: https://portalcfdi.facturaelectronica.sat.gob.mx/
• No es una API REST formal. Es un servicio SOAP envuelto en HTTPS.
• Valida que un RFC exista y esté activo

Descarga masiva de CFDI:

• API REST relativamente moderna
• Base URL: https://cfdidescargamasivasolicitud.clouda.sat.gob.mx/
• Flujo: Solicitud → Token → Verificación → Descarga
• Límite: 200,000 CFDIs por solicitud
• Tiempo de procesamiento: 1-72 horas (dependiendo del volumen)

Cancelación de CFDI:

• Servicio SOAP
• WSDL: https://consultaqr.facturaelectronica.sat.gob.mx/ConsultaCFDIService.svc
• Requiere firma FIEL para cada cancelación
• A partir de 2022, requiere aceptación del receptor para facturas > MXN 1,000

Errores Comunes y Soluciones

| Error | Causa | Solución | |---|---|---| | 301 - XML mal formado | Encoding incorrecto | Asegurar UTF-8 sin BOM | | 302 - Sello inválido | Certificado expirado o llave incorrecta | Verificar vigencia del CSD y que el password sea correcto | | 402 - RFC receptor no existe | RFC incorrecto o contribuyente no activo | Validar RFC antes de emitir. Usar servicio de validación de lista 69-B | | Timeout en descarga masiva | Solicitud muy grande | Dividir por rango de fechas (máximo 1 mes por solicitud) | | Token expirado | Tokens del SAT duran 5 minutos | Implementar renovación automática, no cachear tokens |

Librerías Recomendadas

• Node.js: cfdi-sat (npm), maneja firma y timbrado
• Python: python-cfdi para generación, satws como cliente del SAT
• PHP: CfdiUtils de phpcfdi (la más madura del ecosistema)

Colombia: DIAN (Dirección de Impuestos y Aduanas Nacionales)

Colombia implementó facturación electrónica obligatoria en 2019 y ha ido sofisticando su API desde entonces.

Autenticación

Certificado digital:

• La DIAN usa certificados digitales emitidos por entidades certificadoras autorizadas (Certicámara, Andes SCD, GSE)
• Formato: PKCS#12 (.p12 o .pfx)
• Costo del certificado: COP 150,000-300,000 (~USD 35-70) anual

Token de acceso:

• OAuth 2.0 (client_credentials)
• Base URL auth: https://facturaelectronica.dian.gov.co/operaciones/auth/token
• Token TTL: 60 minutos (pero recomendamos renovar cada 45)

Endpoints Principales

Envío de factura electrónica:

• URL: https://vpfe.dian.gov.co/WcfDianCustomerServices.svc
• Protocolo: SOAP con adjunto MIME (UBL 2.1 XML firmado)
• El XML debe cumplir con el estándar UBL 2.1 adaptado por la DIAN
• Respuesta: CUFE (Código Único de Facturación Electrónica) si es exitosa

Consulta de estado:

• URL: https://vpfe.dian.gov.co/WcfDianCustomerServices.svc?wsdl
• Método: GetStatusEvent
• Parámetro: CUFE de la factura

Validación de NIT:

• No existe API pública directa
• Alternativa: RUES (Registro Único Empresarial) tiene consulta web scrappeable
• Mejor alternativa: usar proveedores como Truora o Infotrack que ya tienen la integración

Particularidades

• Ambiente de pruebas (habilitación): La DIAN requiere un proceso de "habilitación" donde debes enviar un set de facturas de prueba y recibir aprobación antes de poder emitir en producción. Esto toma 2-4 semanas.
• Nómina electrónica: Desde 2021, las empresas deben reportar nómina electrónicamente. API separada con endpoints específicos.
• Documento soporte: Para compras a no obligados a facturar. Tiene su propio flujo y validaciones.
• Eventos DIAN: Acuse de recibo, aceptación, rechazo. Son documentos XML independientes que se envían como respuesta a una factura recibida.

Panamá: DGI (Dirección General de Ingresos)

Panamá es un caso especial. La facturación electrónica se implementó con el sistema SFEP (Sistema de Facturación Electrónica de Panamá) pero la API es limitada y la documentación escasa.

Autenticación

• Certificado digital: Emitido por la DGI directamente o por autoridades certificadoras autorizadas
• Token de acceso: Sistema propietario basado en username/password + certificado
• No hay OAuth estándar. El flujo es:
  1. Login con credenciales al portal de la DGI
  2. Obtener token de sesión
  3. Usar token en header para llamadas subsecuentes
  4. Token expira en 30 minutos sin actividad

Endpoints Principales

Emisión de factura electrónica (FE):

• El SFEP opera principalmente a través de PAC (Proveedores Autorizados Certificados)
• Si eres PAC: integración directa con web service de la DGI
• Si no eres PAC: debes usar uno como intermediario (similar al modelo mexicano)
• PACs autorizados en Panamá: pocos, incluyendo proveedores locales y algunos internacionales como Gosocket

Consulta de RUC:

• URL pública (web, no API): https://dgi.mef.gob.pa/
• No hay API REST oficial para validación de RUC
• Solución práctica: web scraping con manejo de CAPTCHA, o usar un proveedor tercero

Realidad del terreno

La integración con la DGI de Panamá requiere más trabajo manual que en otros países:

• Contacto directo con la DGI para obtener credenciales de ambiente de pruebas
• Testing manual con funcionarios de la DGI (sí, literalmente les envías facturas y te dicen si pasaron)
• Documentación que se comparte por email, no en un portal público
• Cambios que se anuncian con días de anticipación, no meses

Si necesitas integrar con la DGI, recomendamos fuertemente trabajar con un PAC local que ya tenga la relación establecida. Para este tipo de integraciones complejas, la experiencia previa marca toda la diferencia.

Perú: SUNAT (Superintendencia Nacional de Aduanas y de Administración Tributaria)

Perú tiene un ecosistema de facturación electrónica funcional pero con APIs que pueden ser frustrantes de integrar.

Autenticación

Certificado digital:

• Certificado X.509 emitido por entidades autorizadas por INDECOPI
• Formatos aceptados: .pfx, .p12
• Costo: USD 40-100 anual dependiendo del proveedor

Clave SOL:

• RUC + usuario SOL + clave SOL
• Necesaria para el portal web y para algunos servicios

Token para API REST:

• SUNAT migró algunos servicios a REST con OAuth 2.0
• Client ID y Client Secret se obtienen del portal de desarrolladores
• Base URL: https://api-seguridad.sunat.gob.pe/v1/clientesextranet/{clientId}/oauth2/token

Endpoints Principales

Facturación electrónica (SEE):

• SUNAT ofrece tres sistemas de emisión:
  1. SEE-SOL: Portal web de la SUNAT (gratuito, manual)
  2. SEE-Del Contribuyente: Tu sistema se conecta directamente vía web service SOAP
  3. SEE-OSE: A través de un Operador de Servicios Electrónicos autorizado

Para SEE-Del Contribuyente:

• WSDL: https://e-factura.sunat.gob.pe/ol-ti-itcpfegem/billService?wsdl
• El XML debe cumplir estándar UBL 2.0 (no 2.1 como Colombia)
• Respuesta: CDR (Constancia de Recepción) con estado de aceptación

Consulta de RUC:

• API REST: https://api.sunat.gob.pe/v1/contribuyente/contribuyentes/{ruc}
• Requiere token OAuth
• Devuelve: razón social, dirección fiscal, estado, condición

Consulta de tipo de cambio:

• URL: https://api.sunat.gob.pe/v1/tipo-cambio
• Útil para facturación en moneda extranjera (obligatorio usar TC oficial de SUNAT)

Errores Comunes

| Error | Causa | Solución | |---|---|---| | 2800 - El comprobante fue registrado previamente | Número de factura duplicado | Verificar correlativo antes de enviar | | 3105 - Tipo de documento de identidad no válido | Tipo de doc receptor incorrecto | Mapear correctamente: 1=DNI, 6=RUC, 4=CE | | Timeout | SUNAT caído (frecuente en cierre de mes) | Implementar cola de reintentos con backoff exponencial | | SOAP Fault: Security | Certificado no reconocido | Verificar que el certificado esté registrado en el portal de la SUNAT |

Patrones de Arquitectura Multi-País

Si tu plataforma opera en múltiples países de LATAM (o planea hacerlo), necesitas una arquitectura que abstraiga las diferencias entre APIs gubernamentales.

Patrón recomendado: Adapter + Queue

[Tu aplicación] → [Tax Engine (Adapter Layer)]
                          ↓
                    [Message Queue]
                    ↙    ↓    ↘
            [Adapter   [Adapter   [Adapter
             México]    Colombia]  Perú]
                ↓          ↓         ↓
            [SAT API]  [DIAN API] [SUNAT API]

Tax Engine: Un servicio intermedio que recibe documentos fiscales en un formato normalizado (tu formato interno) y los traduce al formato específico de cada país.

Message Queue: Desacopla la emisión de la respuesta. Crítico porque las APIs gubernamentales pueden tardar segundos o minutos en responder, y pueden caerse sin previo aviso.

Adapters por país: Cada adapter conoce:

• El formato XML/JSON específico del país
• El método de autenticación
• Los endpoints y sus particularidades
• Las reglas de reintento específicas
• El mapeo de errores

Estrategia de reintentos

Las APIs gubernamentales se caen. Es un hecho. Tu sistema debe manejarlo:

Intento 1: inmediato
Intento 2: esperar 30 segundos
Intento 3: esperar 2 minutos
Intento 4: esperar 10 minutos
Intento 5: esperar 1 hora
Intento 6: alertar al equipo de operaciones

Reglas adicionales:

• Nunca reintentar errores de validación (XML mal formado, RFC incorrecto). Estos requieren corrección manual.
• Siempre reintentar errores de conectividad y timeouts.
• Para errores 500 del servidor gubernamental, esperar al menos 5 minutos antes de reintentar.
• En cierre fiscal (fin de mes, fin de año), las APIs gubernamentales se saturan. Planifica ventanas de envío fuera de horarios pico (6-8am funciona mejor que 2-4pm).

Idempotencia

Asegura que enviar el mismo documento dos veces no genere duplicados. Cada API maneja esto diferente:

• SAT México: El UUID del CFDI es único. Si envías el mismo XML, recibes el mismo UUID.
• DIAN Colombia: El CUFE se calcula deterministicamente. Un duplicado es rechazado.
• SUNAT Perú: El correlativo (serie-número) debe ser único. Si envías un duplicado, recibes error 2800.

Monitoreo y Compliance Logging

Las regulaciones de LATAM requieren trazabilidad completa de toda operación fiscal. Esto no es opcional.

Qué registrar

• Cada llamada a API gubernamental: timestamp, request (sin datos sensibles), response completa, tiempo de respuesta, IP de origen
• Cada documento fiscal emitido: XML original, XML firmado, respuesta del gobierno, CUFE/UUID/CDR
• Cada error: con contexto suficiente para diagnosticar sin reproducir
• Cada cancelación: motivo, quién la solicitó, respuesta del gobierno

Retención de datos

| País | Tiempo de retención obligatorio | |---|---| | México | 5 años (SAT puede auditar hasta 5 años atrás) | | Colombia | 5 años | | Panamá | 5 años | | Perú | 5 años (4 años de prescripción + 1 año adicional) |

Stack de monitoreo recomendado

• Logs: ELK Stack (Elasticsearch + Logstash + Kibana) o CloudWatch Logs si estás en AWS
• Alertas: PagerDuty o Opsgenie para errores críticos (API gubernamental caída, certificado por vencer)
• Dashboard: Grafana con métricas de: tasa de éxito por país, tiempo de respuesta promedio, volumen de documentos, errores por tipo
• Almacenamiento de documentos: S3 con versionado y cifrado AES-256. Lifecycle policy para mover a Glacier después de 1 año.

Para una implementación completa de monitoreo de compliance, consulta nuestros servicios de compliance para LATAM.

Checklist de Integración

Antes de ir a producción con cualquier API gubernamental en LATAM, verifica:

• [ ] Certificados digitales obtenidos y probados en sandbox
• [ ] Ambiente de pruebas/sandbox aprobado por la entidad
• [ ] Manejo de errores implementado para todos los códigos conocidos
• [ ] Sistema de reintentos con backoff exponencial
• [ ] Idempotencia verificada (no generas duplicados)
• [ ] Logging completo de todas las transacciones
• [ ] Alertas configuradas para: certificado por vencer, API caída, tasa de error > 5%
• [ ] Retención de datos según regulación local
• [ ] Pruebas de carga (las APIs gubernamentales tienen rate limits no documentados — descúbrelos antes de lanzar)
• [ ] Plan de contingencia cuando la API gubernamental está caída (cola de documentos pendientes, notificación al usuario)

¿Listo para integrar APIs gubernamentales en tu plataforma?

En Soluciona Labs ayudamos a empresas en LATAM a integrar APIs gubernamentales de forma robusta y escalable. Tenemos experiencia directa con SAT, DIAN, SUNAT y DGI — sabemos dónde están las trampas y cómo evitarlas. Escríbenos y te ayudamos a definir tu arquitectura de integración.

---

Artículos relacionados

• Facturación Electrónica en Panamá: Guía Completa
• Cómo Modernizar Sistemas Legacy sin Reescribirlos
• Integrar WhatsApp Business API con tu CRM