API REST de facturación electrónica del SRI en Ecuador: guía para desarrolladores

Una API REST pensada para integrarse rápido

Si eres desarrollador o tienes un sistema propio, sabes que integrar la facturación electrónica del SRI puede volverse complejo: firmas digitales, esquemas XML, secuenciales, ambientes y consultas de autorización. La API REST de AZUR abstrae toda esa complejidad. Tú envías un JSON con la venta y AZUR se encarga de generar, firmar y enviar el comprobante al SRI.

Esta guía resume los conceptos que necesitas para integrarla en tu aplicación, sea en PHP, Python, JavaScript, .NET o cualquier lenguaje que hable HTTP.

Autenticación con API key

La API se autentica con un api_key que va en el cuerpo de la petición. Ese api_key identifica en AZUR tu empresa, RUC, establecimiento, punto de emisión y ambiente. No manejas credenciales complejas ni certificados: el api_key encapsula todo eso.

Emitir una factura

Para emitir una factura, envías una petición POST con estos bloques principales:

• emisor: fecha de emisión y manejo de secuencia (AZUR genera el secuencial por ti).
• comprador: tipo de identificación (RUC, cédula o consumidor final), identificación, razón social, correo.
• items: código, descripción, precio sin IVA, cantidad, descuento, tipo de producto y tarifa de IVA.
• pagos: opcional; forma de pago y total.
• informacion_adicional: por ejemplo, el número de pedido.

La respuesta incluye creado: true, la claveacceso de 49 dígitos, el número legible de la factura y, si está habilitado, el enlace al PDF.

Emitir una nota de crédito

La nota de crédito usa el mismo formato, pero con el código de documento correspondiente y un objeto documento_modificado que referencia la factura original: su número, su fecha y el motivo. Los ítems son los que se acreditan o devuelven. Por eso, tu sistema debe guardar el número y la fecha de cada factura al emitirla, para poder generar la nota de crédito cuando haya una devolución.

Reglas clave que debes conocer

• tipo_identificacion: RUC (13 dígitos), cédula (10 dígitos) o consumidor final.
• Consumidor final: cuando el cliente no da identificación válida, se usa la identificación de consumidor final.
• tipo_iva: código de tarifa; IVA 15% para gravados o 0% según el catálogo.
• precio_unitario: siempre sin IVA.
• Secuencial: déjalo en manos de AZUR para evitar duplicados.

Manejo asíncrono del SRI

La emisión te devuelve la clave de acceso al instante, pero la autorización del SRI es asíncrona. Tu sistema debe mostrar el estado "en proceso" y luego consultar el estado real con el endpoint de consulta, enviando el api_key y la clave de acceso. Implementa un polling o un botón "actualizar estado".

Buenas prácticas de integración

• Idempotencia: asocia cada emisión a un identificador de pedido para no duplicar.
• Logs: registra cada petición y respuesta para auditar y depurar.
• Errores claros: maneja mensajes como "Api_key no existe" o "No dispone de comprobantes".
• Ambientes: desarrolla en pruebas y pasa a producción con confianza.

Ejemplo de flujo en tu código

Un patrón sencillo y robusto es: al confirmar la venta, construyes el payload y llamas al endpoint de emisión; guardas de inmediato la clave de acceso en tu base de datos con estado "en proceso"; luego, un proceso en segundo plano consulta periódicamente el estado hasta que el SRI responda "autorizado" o devuelva un error, y actualizas el registro. Este diseño desacopla la venta de la autorización asíncrona y evita que tu usuario espere frente a la pantalla.

Preguntas frecuentes

¿En qué formato responde la API?

JSON, con un indicador de éxito, la clave de acceso y el número de comprobante, o un objeto de error.

¿Puedo emitir otros comprobantes?

La integración está enfocada en factura y nota de crédito, que cubren el ciclo de venta y devolución.

¿La factura tiene validez legal?

Sí. AZUR es plataforma autorizada por el SRI; los comprobantes por API son plenamente válidos.

¿Puedo revenderlo con mi marca?

Sí. La API soporta marca blanca, ideal para software factories y contadores.

Empieza a construir

La API REST de AZUR te ahorra semanas de trabajo con firmas y XML. Crea tu cuenta gratis, obtén tu api_key y prueba la emisión en ambiente de pruebas para llevar la facturación electrónica del SRI a tu propio sistema.