API de facturación electrónica: cuándo conviene integrar y qué cuidar

Una API permite que tu propio software (una tienda en línea, un POS, un ERP o una app) envíe los datos de la venta al servicio de facturación y reciba de vuelta el comprobante autorizado, sin que nadie tenga que copiar la información a mano.

Cuándo tiene sentido

• Vendes por internet y quieres que la factura salga sola al confirmarse el pago.
• Tu POS o ERP no factura electrónicamente y no quieres cambiarlo.
• Emites cientos de comprobantes al mes y la doble digitación ya genera errores.
• Facturas desde varios canales (local, web, vendedores) y quieres ver todo en un solo reporte.

Si emites pocos comprobantes y todos desde el mismo lugar, probablemente no lo necesitas: un sistema web por plan será más simple.

La autorización es asíncrona

Este es el punto que más problemas causa. El SRI no responde «autorizado» en el mismo instante en que recibe el comprobante: primero lo recibe y luego lo autoriza, y en días de mucha carga puede tardar. La integración no debe asumir que la respuesta llega en la misma petición.

Lo recomendable es que tu sistema registre la venta, envíe el comprobante y guarde su estado («pendiente», «autorizado», «rechazado»). Después, consulta el estado o recibe una notificación (webhook) cuando cambie.

Reintentos sin duplicados

Si se corta la conexión en medio del envío, no sabes si el comprobante llegó. Si reintentas generando un secuencial nuevo, puedes terminar con dos facturas autorizadas por la misma venta.

La solución es la idempotencia: cada venta de tu sistema tiene un identificador propio que viaja con la petición, y el servicio de facturación devuelve el mismo comprobante si recibe ese identificador dos veces. Además, guarda la clave de acceso apenas se genere, porque es con ella que consultas el estado en el SRI.

Qué datos debe mandar tu sistema

Como mínimo: identificación y nombre del cliente, correo para el envío, detalle con código, descripción, cantidad, precio y tarifa de IVA de cada línea, descuentos, forma de pago y el punto de emisión que corresponde. Conviene validar cédulas y RUC antes de enviar, para no descubrir el error en el rechazo del SRI.

Qué debe devolver el servicio

• La clave de acceso y el número de comprobante.
• El estado y, si hubo rechazo, el mensaje del SRI tal cual.
• El XML autorizado y el RIDE en PDF, o enlaces para descargarlos.
• La fecha y el número de autorización.

Seguridad

Las credenciales de la API van en el servidor, nunca en el código de una página web o de una app que se instala en el celular. Usa HTTPS, una credencial distinta por sistema o canal, y cámbialas si alguien que tenía acceso deja la empresa. La firma electrónica del emisor debe quedarse del lado del servicio de facturación, no viajar en cada petición.

Prueba antes de salir a producción

Haz todas las pruebas en el ambiente de pruebas del SRI: una factura normal, una con descuento, una nota de crédito, un cliente con pasaporte, un corte de conexión a mitad del envío. Cuando todo eso funcione, cambia a producción.

Integraciones con COUNTELSEG

Además del sistema de facturación, en COUNTELSEG desarrollamos integraciones a medida para conectar tiendas en línea, puntos de venta y sistemas propios. Si nos cuentas qué software usas y cuántos comprobantes emites, te decimos qué alcance tendría la integración.