Facturación electrónica multi-país con una sola API: guía técnica para ISVs en LATAM

Un ISV que opera en cuatro países de LATAM tiene dos opciones: integrar un proveedor de API distinto por país, con endpoints, payloads y reglas de validación diferentes en cada uno, o encontrar un proveedor que abstraiga esas diferencias detrás de una API unificada. La primera opción multiplica la deuda técnica por cuatro. La segunda suena mejor en el pitch de ventas de cualquier proveedor, pero en la práctica pocas APIs multi-país abstraen realmente la complejidad normativa.

Esta guía describe qué significa realmente una API multi-país, qué diferencias normativas entre Colombia, República Dominicana, Panamá y Costa Rica no pueden abstraerse completamente, y cómo evaluar si un proveedor realmente reduce la carga del ISV o solo cambia el lugar donde esa complejidad aparece.

Qué significa realmente una API multi-país

Una API multi-país puede implementarse de dos formas. La primera es una API unificada donde el ISV especifica el país como parámetro y el proveedor gestiona internamente la construcción del XML, la firma, los códigos de impuesto y la transmisión a la autoridad fiscal correspondiente. El ISV envía los mismos campos base con variaciones mínimas por país. La segunda es un conjunto de APIs distintas por país que el proveedor agrupa bajo un mismo dominio o SDK pero que tienen payloads y reglas diferentes — en la práctica, el ISV está haciendo cuatro integraciones distintas.

Cómo verificar si la API realmente abstrae las diferencias

// Prueba de abstracción real: mismo payload base para Colombia y RD
POST /v1/invoices
{
  "country": "CO",
  "issuer": { "taxId": "900123456-7", "name": "Empresa CO" },
  "receiver": { "taxId": "800000001-2", "name": "Cliente CO" },
  "items": [{ "description": "Servicio", "amount": 1000, "taxRate": 19 }]
}
// vs.
{
  "country": "DO",
  "issuer": { "taxId": "101000000", "name": "Empresa RD" },  // RNC en RD
  "receiver": { "taxId": "101000001", "name": "Cliente RD" },
  "items": [{ "description": "Servicio", "amount": 1000, "taxRate": 18 }]
}
// Si el schema es el mismo y solo cambia country y taxId: abstracción real
// Si el endpoint, el schema o los campos cambian por país: no es abstracción real

Diferencias normativas que siempre requieren adaptación por país

Incluso con una API bien abstracta, hay diferencias normativas que el ISV debe conocer porque afectan la lógica de negocio de su aplicación, no solo los parámetros de la API. La primera es el modelo de validación: Colombia es síncrono (sabe si la factura fue aceptada en segundos), República Dominicana es asíncrono (puede tardar horas). Eso cambia cómo el ISV muestra el estado al usuario final.

Comparativa de diferencias normativas por país

Diferencia           | Colombia    | Rep. Dom.   | Panamá      | Costa Rica
---------------------|-------------|-------------|-------------|------------
Validación           | Síncrona    | Asíncrona  | Síncrona    | Síncrona / mixta
Identificador único  | CUFE        | NCF         | CAFE        | Clave 50 dig.
Id fiscal emisor     | NIT         | RNC         | RUC         | Cédula/NIT CR
Id fiscal receptor   | NIT (B2B)   | RNC (e-31)  | RUC (B2B)   | Cédula (opc.)
Tipos de doc.        | 6+ tipos    | 9 tipos     | 6 tipos     | 4 tipos
Firma digital        | XAdES-BES   | SHA-256     | XML-DSig    | XML-DSig MICITT
Tarifa IVA std       | 19%         | 18%         | 7%          | 13%
Certificación PAC    | Prov. Tec.  | PSFE        | PAC cert.   | Emisor Direct.

Tipos de documentos: la diferencia que más impacta al ISV

Cada país define sus propios tipos de documentos electrónicos y las reglas de cuándo usar cada uno. Colombia tiene facturas de contingencia, RADIAN, Documento Soporte y nómina electrónica. República Dominicana tiene 9 tipos de e-CF, cada uno con reglas de validación distintas. Panamá tiene tipos específicos para exportación, importación y zona franca. Costa Rica distingue entre Factura Electrónica y Tiquete Electrónico según si el receptor es contribuyente o consumidor final.

Esto significa que la lógica de selección del tipo de documento — ¿cuándo emito una Factura de Venta vs. un Tiquete? ¿cuándo uso e-31 vs. e-32 en RD? — no puede ser abstracta. El ISV debe implementar esa lógica en su aplicación o el proveedor debe documentarla claramente para cada país.

Modelo de integración recomendado para ISVs multi-país

El modelo que reduce la deuda técnica a largo plazo: una capa de abstracción interna en el ISV que normaliza los datos del comprobante hacia un schema común, más un proveedor de API que expone un endpoint unificado y gestiona las diferencias por país internamente. El ISV no debe conocer el formato del CUFE, el NCF, el CAFE o la clave numérica — eso es responsabilidad del proveedor.

Lo que sí debe conocer el ISV: el tipo de documento correcto por país y operación, el modelo de validación (síncrono vs. asíncrono) para gestionar correctamente el estado en la UI, y las tasas de impuesto vigentes para cada país. Eso no puede delgarse al proveedor porque es lógica de negocio de la aplicación.

Cómo evaluar un proveedor multi-país antes de integrar

Las preguntas clave para cualquier proveedor que se presenta como multi-país: ¿el endpoint es el mismo para todos los países o hay uno por país? ¿El schema del request cambia por país o solo cambia el parámetro country? ¿Hay sandbox separado por país o un sandbox unificado que conecta con la autoridad fiscal de cada país? ¿La documentación incluye una guía de migración de un país a otro? ¿El proveedor ha implementado todos los cambios normativos del último año en los cuatro países?

Preguntas frecuentes

¿Cuál es la diferencia entre un proveedor multi-país y un agrupador de APIs locales?

Un proveedor multi-país real tiene una plataforma propia que gestiona internamente las diferencias normativas de cada país: construye el XML según el estándar local, firma con el certificado correspondiente y transmite a la autoridad fiscal del país. Un agrupador conecta internamente con APIs de proveedores locales distintos en cada país y expone una capa de façade al ISV. La diferencia impacta en la consistencia del error handling, los SLAs de actualización normativa y la coherencia de la documentación.

¿Cómo puedo gestionar el estado asíncrono de RD cuando el resto de los países son síncronos?

El enfoque recomendado es diseñar siempre con el modelo asíncrono como base, incluso para los países síncronos. En la práctica: emitir el documento, recibir un ID interno del proveedor, y usar un webhook para recibir el estado final en lugar de mostrarlo como confirmado inmediatamente en la UI. Para países síncronos como Colombia, el webhook llegará en segundos; para RD, puede tardar más. Ese modelo es consistente entre países y elimina el caso especial en el código.

¿Qué diferencia hay entre integrar facturación multi-país desde el inicio y expandirse gradualmente?

Integrar desde el inicio obliga a tomar decisiones de arquitectura que soporten la variabilidad normativa de cuatro países desde el día uno: schema genérico, tipos de documento configurables, impuestos por país, estados asíncronos. Expandirse gradualmente permite empezar con un país y adaptar la arquitectura a medida que se añaden mercados, pero si el schema inicial fue diseñado solo para un país, la expansión puede requerir refactoring significativo. La decisión depende del roadmap del ISV — si la expansión regional es cierta en menos de 12 meses, vale la pena diseñar multi-país desde el inicio.

¿Es posible usar un proveedor multi-país aunque solo opere en un país hoy?

Sí, y puede tener sentido si la expansión regional es parte del roadmap. La ventaja es que la integración ya tiene el schema multi-país; agregar un nuevo país es cuestión de configurar las credenciales del emisor en ese país y activar el country en el proveedor. El riesgo es que el proveedor puede tener mejor cobertura en el país principal y documentación más débil en los países secundarios. Verificar en el sandbox de cada país target antes de comprometerse con la estrategia.

Antes de implementar la abstracción multi-país, revisa los requisitos técnicos de cada autoridad fiscal en los checklists específicos: Colombia, República Dominicana, Panamá y Costa Rica. Para el marco de evaluación de proveedores que soporte todos los países, consulta los 5 criterios técnicos para LATAM.

Para ISVs que requieran una sola integración con cobertura real en Colombia, República Dominicana, Panamá y Costa Rica, Alanube opera en los cuatro mercados con la arquitectura de abstracción descrita en esta guía.

En el mercado LATAM, algunos proveedores tienen presencia en múltiples países: Gosocket opera en varios países de la región, Edicom tiene cobertura en Colombia, Panamá y República Dominicana, y Alanube cubre Colombia, República Dominicana, Panamá y Costa Rica. Evaluar si cada proveedor ofrece abstracción real o simplemente agrega integraciones independientes es el criterio técnico decisivo.