API SRI para facturación electrónica

Factuplan API es una capa sobre los webservices SOAP del SRI Ecuador que simplifica la integración a una API REST moderna con JSON. Internamente: 1) Recibe tu request JSON con datos de la operación; 2) Valida datos localmente (dígito verificador RUC, tarifas IVA, tope consumidor final, etc.); 3) Genera el XML según la Ficha Técnica del SRI v2.32; 4) Firma el XML con XAdES-BES usando tu certificado P12 cargado en el workspace; 5) Envía al webservice SOAP del SRI (recepción + autorización); 6) Parsea la respuesta y la devuelve en JSON estructurado con el código de error del SRI si aplica; 7) Genera el RIDE PDF y envía email al cliente si lo configuras. Todo el proceso es de 2-5 segundos típicos.

Integrar directo con el SRI requiere: 1) Cliente SOAP en tu stack (XML, WSDL, namespaces); 2) Generación manual de XMLs respetando schemas XSD del SRI y la Ficha Técnica v2.32; 3) Firma XAdES-BES con librerías de criptografía (extraer P12, firmar con SHA-256, agregar timestamp, validar canónicamente); 4) Cálculo manual de la clave de acceso de 49 dígitos con módulo 11; 5) Manejo de errores SOAP con códigos del SRI mal documentados; 6) Reintentos cuando el SRI cae; 7) Generación del RIDE PDF y envío de email. Es desarrollo de 2-6 meses con un team experto. Factuplan API te entrega todo eso en una API REST estándar que llamas desde cualquier lenguaje en minutos.

Son las 3 formas de operar definidas por el SRI: Modo A (recomendado, default en Factuplan): el sistema de facturación electrónica genera el XML, lo firma con tu P12, lo autoriza ante el SRI y genera el RIDE PDF — flujo end-to-end automatizado. Modo B: tú generas el XML por tu cuenta (útil si tu ERP ya tiene un generador de XMLs SRI) y se lo envías a Factuplan, que lo firma y autoriza. Modo C: tú generas Y firmas el XML con tu propia integración criptográfica, y Factuplan solo gestiona la transmisión al SRI. Los 3 modos usan la misma API key y se eligen por endpoint o parámetro según convenga a tu arquitectura. La mayoría de integraciones usan Modo A porque es más simple.

El SRI define un mecanismo de contingencia: emites el comprobante con tipo de emisión 2 (en lugar de 1 = normal) en la clave de acceso, entregas el RIDE preliminar al cliente, y cuando el SRI vuelve, reenvías el XML para autorización formal. Factuplan API maneja esto automáticamente: si detecta que el SRI no responde, activa modo contingencia, devuelve el comprobante en estado PENDING con la clave de acceso de 49 dígitos generada, y cuando el SRI vuelve a estar disponible, reenvía la cola pendiente. Tu app puede operar normalmente sin bloquear ventas durante caídas del SRI. Recibes el evento invoice.authorized vía webhook cuando el SRI finalmente autoriza.

Tres formas: 1) Asincrónica via webhooks: configuras tu endpoint en Dashboard → Developer → Webhooks y recibes invoice.authorized o invoice.rejected con la respuesta completa del SRI cuando esté lista. Es lo recomendado para producción. 2) Sincrónica via GET /v1/developer/invoices/:id que retorna el estado actual y, si fue rechazado, el sriCode y sriMessage. 3) Manual con la herramienta /herramientas/verificar-factura-sri usando la clave de acceso de 49 dígitos. El estado AUT confirma que el SRI registró el comprobante exitosamente; PPR es transitorio (esperando autorización); REJECTED/RETURNED requieren corregir y reenviar con secuencial nuevo.

Factuplan API valida localmente antes de enviar al SRI para evitar errores comunes: dígito verificador del RUC del cliente (rechazo evitado), tarifa IVA fuera de catálogo, secuencial duplicado (detectado contra tu histórico), tope de consumidor final excedido, formato de clave de acceso incorrecto. Para errores del SRI que llegan en la respuesta (firma vencida, certificado emitido para otro RUC, datos del establecimiento desactualizados, etc.), la API devuelve un FactuplanSRIError con sriCode del catálogo SRI y sugerencia de corrección. No te rechaza silenciosamente — siempre sabes exactamente qué pasó y cómo arreglarlo.

Sí. La API soporta los 6 tipos de comprobantes electrónicos definidos por el SRI: facturas (código 01), liquidaciones de compra de bienes y servicios (03), notas de crédito (04), notas de débito (05), guías de remisión (06) y comprobantes de retención (07). Cada tipo tiene su endpoint REST dedicado (/v1/developer/invoices, /credit-notes, /debit-notes, /waybills, /withholdings, /purchase-liquidations) con el payload específico que define la Ficha Técnica del SRI. Todos pasan por el mismo flujo de firma y autorización, con la misma autorización oficial del SRI y la misma clave de acceso de 49 dígitos.

Sí. Con una API key de pruebas (prefijo ak_test_*) la API genera comprobantes ficticios que NO se envían al SRI real — la firma se simula y la 'autorización' se simula con clave de acceso ficticia. Los comprobantes de sandbox se eliminan automáticamente cada hora para mantener el ambiente limpio. Esto permite que developers prueben la integración completa sin necesidad de obtener firma electrónica P12 ni RUC activo. Cuando estés listo para producción, cambias la API key por ak_live_*, cargas tu firma real en el dashboard y los comprobantes empiezan a enviarse al SRI real con autorización oficial.