Documentación

Factura

Consumidor final, cédula, RUC, descuentos, IVA mixto, crédito, varios pagos, propina y extranjeros.

Se emite con POST /v1/facturas (o POST /v1/comprobantes con "tipo": "factura"). Los totales los calcula el servicio a partir de los ítems.

Campos

compradorObligatorio: más de USD 50Descripción: Sin comprador es consumidor final. tipoIdentificacion, identificacion, razonSocial, y opcionales direccion, email o emails.
items[].descripcionObligatorio: síDescripción: Hasta 300 caracteres.
items[].cantidadObligatorio: síDescripción: Mayor que cero, hasta 6 decimales.
items[].precioUnitarioObligatorio: síDescripción: Precio sin IVA, hasta 6 decimales.
items[].ivaObligatorio: síDescripción: Tarifa: 15, 5, 8, 0, noObjeto o exento.
items[].descuentoObligatorio: noDescripción: Descuento del ítem en dólares (no porcentaje).
items[].codigoObligatorio: noDescripción: Tu código de producto (hasta 25 caracteres).
items[].codigoAuxiliarObligatorio: noDescripción: Código auxiliar; el de la Tabla 31 para materiales de construcción al 5 %.
items[].iceObligatorio: noDescripción: ICE: { codigoPorcentaje, tarifa } según la Tabla 18 del SRI.
items[].detallesAdicionalesObligatorio: noDescripción: Hasta 3 pares nombre: valor que se imprimen en el RIDE (talla, color, lote…).
pagos[].formaPagoObligatorio: síDescripción: efectivo, transferencia, tarjetaCredito, tarjetaDebito… (ver Formatos).
pagos[].totalObligatorio: con varios pagosDescripción: Lo pagado con esa forma; con un solo pago es el total de la factura.
pagos[].plazoObligatorio: noDescripción: Plazo de crédito, con unidadTiempo (dias, meses…).
propinaObligatorio: noDescripción: Servicio de restaurante, hasta el 10 % del subtotal; no lleva IVA.
infoAdicionalObligatorio: noDescripción: Hasta 15 pares nombre: valor (pedido, vendedor, observaciones…) que salen en el RIDE.
fechaEmisionObligatorio: noDescripción: AAAA-MM-DD; por defecto hoy en Ecuador. El SRI rechaza fechas fuera de plazo (error 65).
emisorObligatorio: si hay variosDescripción: RUC o id del emisor.
serieObligatorio: si hay variasDescripción: Establecimiento y punto de emisión: "002-001".
guiaRemision, placaObligatorio: noDescripción: Número de la guía de remisión asociada; placa para venta de combustibles.

Campo	Obligatorio	Descripción
comprador	más de USD 50	Sin comprador es consumidor final. `tipoIdentificacion`, `identificacion`, `razonSocial`, y opcionales `direccion`, `email` o `emails`.
items[].descripcion	sí	Hasta 300 caracteres.
items[].cantidad	sí	Mayor que cero, hasta 6 decimales.
items[].precioUnitario	sí	Precio sin IVA, hasta 6 decimales.
items[].iva	sí	Tarifa: `15`, `5`, `8`, `0`, `noObjeto` o `exento`.
items[].descuento	no	Descuento del ítem en dólares (no porcentaje).
items[].codigo	no	Tu código de producto (hasta 25 caracteres).
items[].codigoAuxiliar	no	Código auxiliar; el de la Tabla 31 para materiales de construcción al 5 %.
items[].ice	no	ICE: `{ codigoPorcentaje, tarifa }` según la Tabla 18 del SRI.
items[].detallesAdicionales	no	Hasta 3 pares nombre: valor que se imprimen en el RIDE (talla, color, lote…).
pagos[].formaPago	sí	efectivo, transferencia, tarjetaCredito, tarjetaDebito… (ver `Formatos`).
pagos[].total	con varios pagos	Lo pagado con esa forma; con un solo pago es el total de la factura.
pagos[].plazo	no	Plazo de crédito, con `unidadTiempo` (`dias`, `meses`…).
propina	no	Servicio de restaurante, hasta el 10 % del subtotal; no lleva IVA.
infoAdicional	no	Hasta 15 pares nombre: valor (pedido, vendedor, observaciones…) que salen en el RIDE.
fechaEmision	no	AAAA-MM-DD; por defecto hoy en Ecuador. El SRI rechaza fechas fuera de plazo (error 65).
emisor	si hay varios	RUC o id del emisor.
serie	si hay varias	Establecimiento y punto de emisión: `"002-001"`.
guiaRemision, placa	no	Número de la guía de remisión asociada; placa para venta de combustibles.

Casos

Venta a consumidor final

Sin comprador: el SRI la registra a CONSUMIDOR FINAL (9999999999999). Sólo se permite hasta USD 50; por encima hay que identificar al comprador.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-consumidor-final-1" \
  -d '{
  "items": [
    {
      "descripcion": "Café americano",
      "cantidad": 2,
      "precioUnitario": "2.50",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "efectivo"
    }
  ]
}'

Si la cuenta tiene un solo emisor y un solo punto de emisión, no hace falta indicar emisor ni serie.

Cliente con cédula y correo

El comprador recibe el RIDE (PDF) y el XML autorizado por correo apenas el SRI autoriza. Puedes guardar datos propios en infoAdicional (hasta 15 campos).

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-cedula-correo-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "cedula",
    "identificacion": "0912345675",
    "razonSocial": "María Cliente",
    "direccion": "Av. 9 de Octubre 100, Guayaquil",
    "email": "maria@example.com"
  },
  "items": [
    {
      "codigo": "P-001",
      "descripcion": "Martillo de acero",
      "cantidad": 2,
      "precioUnitario": "10.00",
      "iva": "15"
    },
    {
      "descripcion": "Libro de carpintería",
      "cantidad": 1,
      "precioUnitario": "5.00",
      "iva": "0"
    }
  ],
  "pagos": [
    {
      "formaPago": "transferencia"
    }
  ],
  "infoAdicional": {
    "Pedido": "PED-1001",
    "Vendedor": "Ana"
  }
}'

Empresa con RUC y varios correos

Para ventas a sociedades: el RIDE llega a todos los correos de la lista (por ejemplo, compras y contabilidad).

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-empresa-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "ruc",
    "identificacion": "1792146739001",
    "razonSocial": "DISTRIBUIDORA EL SOL S.A.",
    "direccion": "Av. Amazonas N24-10, Quito",
    "emails": [
      "compras@example.com",
      "contabilidad@example.com"
    ]
  },
  "items": [
    {
      "codigo": "SRV-SOPORTE",
      "descripcion": "Soporte técnico mensual",
      "cantidad": 1,
      "precioUnitario": "180.00",
      "iva": "15"
    },
    {
      "codigo": "SRV-HORAS",
      "descripcion": "Horas adicionales de desarrollo",
      "cantidad": "6.5",
      "precioUnitario": "25.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "tarjetaCredito"
    }
  ]
}'

Las cantidades admiten hasta 6 decimales y se pueden enviar como texto ("6.5") o número.

Descuento por ítem

El descuento es un valor en dólares (no un porcentaje) y se resta antes de calcular el IVA de ese ítem.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-descuento-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "cedula",
    "identificacion": "1710034065",
    "razonSocial": "Carlos Andrade"
  },
  "items": [
    {
      "codigo": "TV-55",
      "descripcion": "Televisor 55 pulgadas",
      "cantidad": 1,
      "precioUnitario": "650.00",
      "descuento": "50.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "tarjetaDebito"
    }
  ]
}'

Base: 650,00 − 50,00 = 600,00; IVA 15 % = 90,00; total 690,00. Los totales los calcula el servicio.

Ítems con distintas tarifas de IVA

Cada ítem lleva su tarifa: "15", "5", "0", "8" (feriados turísticos), "noObjeto" o "exento". Los materiales de construcción al 5 % llevan su código de la Tabla 31 en codigoAuxiliar.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-iva-mixto-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "ruc",
    "identificacion": "1792146739001",
    "razonSocial": "DISTRIBUIDORA EL SOL S.A."
  },
  "items": [
    {
      "descripcion": "Pintura de caucho galón",
      "cantidad": 3,
      "precioUnitario": "18.00",
      "iva": "15"
    },
    {
      "codigoAuxiliar": "F010401",
      "descripcion": "Cemento Portland saco 50 kg",
      "cantidad": 10,
      "precioUnitario": "8.20",
      "iva": "5"
    },
    {
      "descripcion": "Arroz blanco funda 5 kg",
      "cantidad": 2,
      "precioUnitario": "6.75",
      "iva": "0"
    }
  ],
  "pagos": [
    {
      "formaPago": "transferencia"
    }
  ]
}'

¿Dudas con la tarifa? POST /v1/inteligencia/tarifa-iva sugiere la de cada ítem con su base legal.

Venta a crédito (pago a plazo)

Indica el plazo y su unidad en el pago. El RIDE muestra la forma de pago con el plazo.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-credito-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "ruc",
    "identificacion": "1792146739001",
    "razonSocial": "DISTRIBUIDORA EL SOL S.A.",
    "email": "pagos@example.com"
  },
  "items": [
    {
      "codigo": "LAP-14",
      "descripcion": "Laptop 14 pulgadas",
      "cantidad": 5,
      "precioUnitario": "720.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "transferencia",
      "plazo": "30",
      "unidadTiempo": "dias"
    }
  ]
}'

Varias formas de pago

Con más de una forma de pago, indica cuánto se pagó con cada una: la suma debe dar el total de la factura.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-pago-mixto-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "cedula",
    "identificacion": "1710034065",
    "razonSocial": "Carlos Andrade"
  },
  "items": [
    {
      "descripcion": "Zapatos deportivos",
      "cantidad": 1,
      "precioUnitario": "40.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "efectivo",
      "total": "20.00"
    },
    {
      "formaPago": "tarjetaCredito",
      "total": "26.00"
    }
  ]
}'

40,00 + IVA 6,00 = 46,00 = 20,00 en efectivo + 26,00 con tarjeta.

Restaurante con propina

La propina (hasta el 10 % del subtotal) no lleva IVA y se suma al total.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-propina-1" \
  -d '{
  "items": [
    {
      "descripcion": "Almuerzo ejecutivo",
      "cantidad": 2,
      "precioUnitario": "8.50",
      "iva": "15"
    },
    {
      "descripcion": "Jugo natural",
      "cantidad": 2,
      "precioUnitario": "2.00",
      "iva": "15"
    }
  ],
  "propina": "2.10",
  "pagos": [
    {
      "formaPago": "tarjetaDebito"
    }
  ]
}'

Subtotal 21,00 + IVA 3,15 + propina 2,10 = 26,25.

Turista con pasaporte

Para compradores sin cédula ni RUC: pasaporte o identificación del exterior.

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-extranjero-1" \
  -d '{
  "comprador": {
    "tipoIdentificacion": "pasaporte",
    "identificacion": "AB1234567",
    "razonSocial": "John Smith",
    "email": "john.smith@example.com"
  },
  "items": [
    {
      "descripcion": "Tour Quilotoa día completo",
      "cantidad": 2,
      "precioUnitario": "45.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "tarjetaCredito"
    }
  ]
}'

Elegir emisor, serie y fecha

Si la cuenta tiene varios emisores o puntos de emisión, indica cuál usar. La fecha por defecto es hoy (hora de Ecuador).

POST /v1/facturas

curl -X POST "https://api.devfact.fonles.com/v1/facturas" \
  -H "Authorization: Bearer $DEVFACT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factura-emisor-serie-1" \
  -d '{
  "emisor": "1799999990001",
  "serie": "002-001",
  "fechaEmision": "2026-11-04",
  "comprador": {
    "tipoIdentificacion": "cedula",
    "identificacion": "0912345675",
    "razonSocial": "María Cliente"
  },
  "items": [
    {
      "descripcion": "Mantenimiento de equipos",
      "cantidad": 1,
      "precioUnitario": "120.00",
      "iva": "15"
    }
  ],
  "pagos": [
    {
      "formaPago": "transferencia"
    }
  ]
}'

emisor acepta el RUC o el id; serie es "establecimiento-punto" (001-001, 002-001…).

¿Te equivocaste en una factura ya autorizada? No se edita: emite una nota de crédito o, si estás dentro del plazo, anúlala (cómo).