API de factura electrónica en Costa Rica: guía técnica para desarrolladores

Integrar un sistema con la facturación electrónica en Costa Rica no consiste únicamente en enviar una venta a un servicio web. Una implementación confiable debe coordinar datos comerciales, numeración, generación de XML, firma digital, comunicación con los servicios disponibles, almacenamiento de evidencias y manejo de errores. Para un comercio pequeño o mediano, el objetivo técnico debería ser claro: emitir comprobantes de forma consistente, conocer su estado, poder responder ante una consulta y evitar duplicados cuando ocurren fallos de red o reintentos. Antes de escribir código, conviene diseñar el flujo completo y validar los requisitos vigentes con la documentación oficial aplicable. Conceptos que no se deben confundir En una integración suelen mezclarse tres identificadores distintos. Separarlos desde el modelo de datos evita errores y simplifica el soporte. El número interno es el identificador propio de la aplicación. Puede corresponder a una orden, una venta, una transacción de caja o un registro de base de datos. Es útil para relacionar procesos internos, pero no sustituye la identificación del comprobante electrónico. El consecutivo identifica el comprobante dentro de la estructura de numeración utilizada por el emisor. Su composición y reglas deben revisarse según la documentación técnica vigente. El sistema debe generarlo de forma controlada, especialmente si existen varias cajas, sucursales, integraciones de comercio electrónico o procesos que emiten simultáneamente. La clave del comprobante es un identificador que integra información definida por la especificación correspondiente. No debe tratarse como un valor decorativo ni generarse sin validaciones. La aplicación necesita conservar la clave junto con el XML emitido, la respuesta recibida y los eventos relevantes del proceso. Arquitectura recomendada antes de integrar Una arquitectura práctica separa el proceso comercial del proceso de emisión. Cuando una venta se confirma, el sistema puede crear una solicitud de emisión con un estado inicial, por ejemplo, pendiente de generar. Un componente especializado transforma esos datos al formato requerido, firma el documento y gestiona el envío. Esta separación permite que el punto de venta continúe operando cuando una dependencia externa presenta una demora temporal. También facilita reintentos controlados, auditoría y recuperación de comprobantes pendientes. Los componentes habituales son: - Módulo comercial: crea la venta, cliente, líneas, impuestos y medios de pago. - Servicio de numeración: asigna y resguarda consecutivos sin colisiones. - Generador de XML: transforma datos validados al esquema aplicable. - Servicio de firma: aplica la firma digital con controles de seguridad. - Cliente de integración: autentica, envía documentos, consulta estados y recibe respuestas. - Repositorio documental: almacena XML, respuestas, metadatos y bitácora. - Monitor de procesos: identifica pendientes, rechazos, tiempos de espera y reintentos. Ciclo de vida de un comprobante El flujo puede representarse así: Venta confirmada → Validación de datos comerciales y fiscales → Reserva de consecutivo → Generación de clave y XML → Firma digital del XML → Envío mediante la integración disponible → Recepción de acuse o resultado inicial → Consulta o procesamiento de estado cuando corresponda → Almacenamiento de XML, respuesta y bitácora → Estado final: aceptado, rechazado, pendiente o requiere revisión El diagrama es una guía operativa. Los nombres exactos de estados, mensajes y endpoints deben alinearse con la versión técnica vigente y con el ambiente de pruebas o producción que corresponda. Ejemplo conceptual de payload interno Antes de generar XML, una API interna podría trabajar con una estructura similar a esta: { "idInterno": "venta-10452", "tipoComprobante": "01", "consecutivo": "00100001010000010452", "fechaEmision": "2025-01-15T10:30:00-06:00", "receptor": { "tipoIdentificacion": "01", "numeroIdentificacion": "000000000" }, "lineas": [ { "numeroLinea": 1, "cantidad": 1, "detalle": "Producto de ejemplo", "precioUnitario": 1000.00 } ] } Este ejemplo es ilustrativo y no representa un payload oficial ni valores completos para producción. El XML final debe construirse según los campos, catálogos, reglas y versiones técnicas que estén vigentes al momento de desarrollar. Firma, autenticación y seguridad La firma digital es una parte crítica del flujo. Las llaves, certificados, credenciales y contraseñas no deben incluirse en código fuente, archivos compartidos sin control ni registros de aplicación. Es preferible utilizar mecanismos de gestión de secretos, controles de acceso por rol y rotación de credenciales cuando la operación lo requiera. El servicio de firma debe registrar eventos técnicos sin exponer información sensible. Por ejemplo, una bitácora puede guardar el identificador interno, la clave, la hora, el resultado y un código de error; no necesita guardar contraseñas, tokens completos ni material criptográfico. También conviene validar los datos antes de firmar. Errores en identificación, totales, impuestos, fechas, catálogos o estructura del documento pueden producir rechazos que luego requieren revisión manual. Reintentos e idempotencia Un error de conexión no significa necesariamente que el comprobante no haya sido recibido. Si el sistema reenvía sin control, puede generar intentos duplicados o estados difíciles de interpretar. La idempotencia ayuda a resolver este problema. Cada emisión debe asociarse con una operación única, normalmente relacionada con el número interno y la clave. Antes de reenviar, el sistema debería revisar si existe evidencia de un envío previo, consultar el estado disponible y decidir si corresponde esperar, consultar, reintentar o escalar a revisión. Los reintentos deben tener límites y pausas progresivas. Un proceso que reintenta de manera inmediata e indefinida puede saturar servicios, ocultar un error de configuración y dificultar el diagnóstico. Los fallos permanentes, como datos inválidos o credenciales vencidas, requieren corrección antes de un nuevo intento. Almacenamiento y trazabilidad La trazabilidad no se resuelve guardando solamente el PDF o una representación visual. Para cada comprobante, el sistema debería conservar al menos el XML generado, el XML firmado si aplica, las respuestas obtenidas, la clave, el consecutivo, fechas, estados, identificadores de solicitud y una bitácora de eventos. Una bitácora útil responde preguntas concretas: quién originó la venta, cuándo se generó el documento, cuántas veces se intentó enviar, qué respuesta se recibió y qué acción corrigió un rechazo. Las políticas de retención, respaldos y acceso deben ser definidas por el comercio con revisión de sus responsables técnicos y asesores correspondientes. Errores frecuentes en una integración Entre los problemas más comunes están asumir que el envío equivale a aceptación final, reutilizar consecutivos, modificar un XML después de firmarlo, no contemplar documentos pendientes, registrar secretos en logs y depender de un único proceso sin monitoreo. También es frecuente implementar contra una versión técnica desactualizada o trasladar reglas de un ambiente de pruebas a producción sin validación. La documentación y los cambios publicados por las entidades correspondientes deben revisarse antes de liberar una integración. ¿Desarrollo propio o plataforma conectada? Construir una integración interna puede ser conveniente cuando la empresa cuenta con equipo técnico, controles de seguridad, capacidad de monitoreo y tiempo para mantener el proyecto ante cambios. Una plataforma ya conectada puede reducir trabajo operativo, especialmente cuando el comercio necesita concentrarse en ventas, inventario y atención al cliente. La decisión debe valorar integración con el sistema actual, volumen operativo, soporte, control sobre los datos, continuidad del negocio y capacidad para investigar incidencias. Si desea conocer cómo miPOS gestiona estos procesos o requiere orientación sobre compatibilidad para un proyecto, puede solicitar una demostración o consultar con el equipo de JARS Costa Rica.