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 el formato de los datos (tipo y longitud de la identificación, tarifas de IVA, que los pagos sumen el total, 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) Deja la respuesta del SRI disponible en JSON (estado del comprobante y webhooks), con los mensajes y códigos del SRI si los hay; 7) Genera el RIDE PDF y envía el email al cliente (por defecto; con sendEmail: false no se envía). Todo el proceso toma típicamente unos segundos.

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 el XML, Factuplan solo lo firma con tu P12 (POST /v1/developer/sign) y el envío al SRI lo haces tú. Los 3 modos usan la misma API key y se eligen por endpoint 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 no emite en contingencia (siempre usa tipo de emisión 1), pero tampoco bloquea tu venta: el POST responde de inmediato con la clave de acceso de 49 dígitos y el envío al SRI ocurre en segundo plano, con reintentos. Si el SRI sigue sin responder, el comprobante queda en ERROR (recibes invoice.error) y Factuplan lo reintenta automáticamente cuando el SRI vuelve. 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 cuando el SRI responde (invoice.rejected trae los mensajes del SRI en reason). Es lo recomendado para producción. 2) Sincrónica via GET /v1/developer/receipts/:id/status que retorna el estado actual (status) y, si fue rechazado, los mensajes del SRI en messages. 3) Manual con la herramienta /herramientas/verificar-factura-sri usando la clave de acceso de 49 dígitos. AUTHORIZED confirma que el SRI registró el comprobante y COMPLETED es el estado final (PDF listo y correo enviado, si aplica); RECEIVED_SRI es transitorio (esperando autorización); REJECTED requiere corregir los datos y emitir de nuevo; ERROR significa que el comprobante no terminó de emitirse y se puede reintentar.

Factuplan API valida antes de enviar al SRI para evitar errores comunes: formato de la identificación del cliente, tarifa IVA fuera de catálogo y pagos que no suman el total; además genera por ti el secuencial y la clave de acceso. Los errores del SRI (firma vencida, certificado emitido para otro RUC, datos del establecimiento desactualizados, etc.) no llegan como excepción: el comprobante queda en REJECTED y los mensajes del SRI, con su código, vienen en messages de GET /v1/developer/receipts/:id/status y en el webhook invoice.rejected. 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). Cinco tienen endpoint JSON dedicado (/v1/developer/invoices, /credit-notes, /debit-notes, /withholdings, /purchase-settlements); la guía de remisión se emite enviando tu propio XML a /v1/developer/sign-and-authorize (Modo B) o desde el panel. 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_*) los comprobantes que emites por los endpoints JSON (Modo A) son ficticios y NO se envían al SRI real — la recepción y la autorización se simulan, y el número de autorización es TEST- seguido de la clave de acceso. Si además emites con el contribuyente de pruebas que trae tu cuenta nueva (RUC 9999999990001), tampoco necesitas firma electrónica: el XML no se firma. 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. El Modo B (sign-and-authorize) es distinto: incluso con ak_test_* firma con tu certificado y envía el XML al ambiente de pruebas del SRI. 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.