Crear Documentos SRI

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

La API de creación de documentos SRI permite generar todos los tipos de documentos electrónicos requeridos por el Servicio de Rentas Internas (SRI) de Ecuador. Cada tipo de documento tiene sus propias características y validaciones específicas.

Tipos de Documentos Disponibles

La API soporta la creación de los siguientes documentos electrónicos:

Facturas - Documentos de venta (Código SRI: 01)
Notas de Crédito - Anulaciones y devoluciones (Código SRI: 04)
Notas de Débito - Cargos adicionales (Código SRI: 05)
Comprobantes de Retención - Retenciones de impuestos (Código SRI: 07)
Guías de Remisión - Transporte de mercancías (Código SRI: 06)
Liquidaciones de Compra - Compras a no obligados (Código SRI: 03)

Endpoint Principal

Endpoint: POST /api/v1/documents/create

Descripción: Endpoint unificado para crear cualquier tipo de documento electrónico del SRI.

Headers Requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros Principales

Parámetro	Tipo	Requerido	Descripción
`sri_code_document`	string	Sí	Código del tipo de documento SRI
`send_to_emit`	boolean	No	Si se debe emitir automáticamente al SRI
`customer`	object	Condicional	Información del cliente (facturas, notas)
`supplier`	object	Condicional	Información del proveedor (liquidaciones)
`carrier`	object	Condicional	Información del transportista (guías)
`document`	object	Sí	Información general del documento
`items`	array	Sí	Array de productos/servicios
`payments`	array	No	Formas de pago
`aditional_fields`	array	No	Campos adicionales

Códigos de Documento SRI

Código	Tipo de Documento	Descripción
`01`	Factura	Documento principal de venta
`03`	Liquidación de Compra	Compras a personas no obligadas
`04`	Nota de Crédito	Anulaciones, devoluciones, descuentos
`05`	Nota de Débito	Intereses, multas, cargos adicionales
`06`	Guía de Remisión	Transporte de mercancías
`07`	Comprobante de Retención	Retenciones en la fuente

Tipos de Identificación

Código	Tipo	Descripción
`CEDULA`	05	Cédula de ciudadanía
`RUC`	04	Registro Único de Contribuyentes
`PASAPORTE`	06	Pasaporte
`CONSUMIDOR_FINAL`	07	Consumidor final
`IDENTIFICACION_EXTERIOR`	08	Identificación del exterior

Códigos de Impuestos

IVA (Impuesto al Valor Agregado)

Código	Porcentaje	Descripción
`0`	0%	No objeto de impuesto
`2`	12%	Tarifa 12%
`3`	14%	Tarifa 14%
`4`	15%	Tarifa 15%
`6`	0%	No gravado
`7`	0%	Exento

ICE (Impuesto a los Consumos Especiales)

Código	Descripción
`3072`	Cigarrillos
`3073`	Cerveza
`3074`	Bebidas gaseosas
`3075`	Alcohol y productos alcohólicos
`3077`	Productos del tabaco
`3078`	Perfumes y aguas de tocador

Retenciones

Código	Tipo	Descripción
`1`	Renta	Retención en la fuente del impuesto a la renta
`2`	IVA	Retención del IVA
`6`	ISD	Impuesto a la salida de divisas

Estructura General del Documento

Información del Cliente/Proveedor

{
  "identification_number": "0123456789",
  "name": "Juan",
  "lastname": "Pérez",
  "identification_type": "CEDULA",
  "email": "[email protected]",
  "address": "Quito, Ecuador",
  "phone": "0987654321"
}

Información del Documento

{
  "date": "2024-01-15",
  "establishment": "001",
  "point_of_emission": "001",
  "sequential": 1,
  "currency": "DOLAR",
  "guide_number": "001-001-000000001"
}

Estructura de Items

{
  "code": "PROD-001",
  "description": "Producto de ejemplo",
  "rate": 10.00,
  "quantity": 2,
  "discount": 0,
  "subtotal": 20.00,
  "taxes": [
    {
      "code": "2",
      "percentaje_code": "2",
      "percentaje_tax": 12,
      "total_tax": 2.40
    }
  ]
}

Formas de Pago

Código	Descripción
`01`	Sin utilización del sistema financiero
`15`	Compensación de deudas
`16`	Tarjeta de débito
`17`	Dinero electrónico
`18`	Tarjeta prepago
`19`	Tarjeta de crédito
`20`	Otros con utilización del sistema financiero
`21`	Endoso de títulos

Validaciones Importantes

Datos Obligatorios

RUC/Cédula del cliente: Debe ser válido según algoritmo ecuatoriano
Establecimiento y punto de emisión: Deben estar registrados en el SRI
Secuencial: Se genera automáticamente si no se proporciona
Fecha: No puede ser futura ni muy antigua
Totales: Deben cuadrar matemáticamente

Reglas de Negocio

Los documentos se crean en estado draft por defecto
Si send_to_emit es true, se envía automáticamente al SRI
Los secuenciales se manejan automáticamente por establecimiento
Las retenciones solo aplican a ciertos tipos de contribuyentes
Los impuestos deben calcularse correctamente según las tarifas vigentes

Estados de Documentos

Estado	Descripción
`draft`	Borrador, no enviado al SRI
`pending`	Pendiente de autorización del SRI
`authorized`	Autorizado por el SRI
`rejected`	Rechazado por el SRI
`cancelled`	Anulado

Ambientes de Trabajo

Ambiente de Pruebas

URL SRI: https://celcer.sri.gob.ec/
Certificados: De prueba
Validez: Solo para testing
RUC de prueba: 1234567890001

Ambiente de Producción

URL SRI: https://cel.sri.gob.ec/
Certificados: Reales y válidos
Validez: Fiscal completa
RUC: Real del contribuyente

Flujo de Creación

Preparar datos - Validar información del cliente y productos
Crear documento - POST /api/v1/documents/create
Verificar respuesta - Confirmar creación exitosa
Emitir al SRI - Si no se hizo automáticamente
Verificar autorización - Consultar estado del documento
Generar PDF - Para entrega al cliente
Enviar por email - Notificación automática

Respuestas Comunes

Éxito (201 Created)

{
  "message": "Documento creado exitosamente",
  "status": "CREATED",
  "payload": {
    "id": 123456789,
    "environment": "PROD",
    "number": 1,
    "date": "2024-01-15",
    "total": "22.40",
    "access_key": "1501202401...",
    "status": "draft"
  }
}

Error de Validación (422)

{
  "message": "Error de validación",
  "status": "UNPROCESSABLE_ENTITY",
  "errors": {
    "customer.identification_number": [
      "El número de identificación no es válido"
    ],
    "items.0.rate": [
      "El precio debe ser mayor a 0"
    ]
  }
}

Códigos de Respuesta

Código	Descripción
`201`	Documento creado exitosamente
`400`	Error en los datos enviados
`401`	Token de autorización inválido
`422`	Error de validación
`500`	Error interno del servidor

Mejores Prácticas

1. Validación Previa

Verificar RUC/cédula antes de crear el documento
Validar que los productos existan en el sistema
Confirmar que los impuestos estén correctamente calculados

2. Manejo de Errores

Implementar reintentos para errores temporales
Validar respuestas del SRI
Mantener logs detallados de errores

3. Secuenciales

No enviar secuencial manualmente (se genera automáticamente)
Verificar que el establecimiento esté activo
Confirmar autorización antes de entregar al cliente

4. Testing

Usar ambiente de pruebas para desarrollo
Probar con diferentes tipos de clientes
Validar cálculos de impuestos

Notas Importantes

📋 Documentos únicos: Cada documento tiene un número secuencial único
🔐 Certificados digitales: Requeridos para firmar documentos
⏰ Tiempo de respuesta: El SRI puede tardar hasta 30 segundos en responder
📧 Notificaciones: Los emails se envían automáticamente si están configurados
💾 Almacenamiento: Los documentos se almacenan permanentemente
🔄 Sincronización: Los estados se actualizan automáticamente
📊 Reportes: Todos los documentos aparecen en reportes del SRI

Soporte y Documentación

Para información específica sobre cada tipo de documento, consulta las secciones individuales:

Facturas - Documentos de venta
Notas de Crédito - Anulaciones y devoluciones
Notas de Débito - Cargos adicionales
Comprobantes de Retención - Retenciones
Guías de Remisión - Transporte
Liquidaciones de Compra - Compras especiales