La factura, campo por campo
Cómo se arma una factura, qué calculamos por ti y las reglas del SRI que revisamos antes de numerarla.
La factura es el comprobante más usado y el modelo de los demás: si la entiendes, entiendes las notas y la liquidación de compra.
{
"buyer": {
"identification_type": "ruc",
"identification": "1790012345001",
"name": "Ferretería El Sol S.A.",
"address": "Av. 10 de Agosto N21-44, Quito",
"email": "compras@elsol.ec"
},
"lines": [
{
"code": "TAL-800",
"description": "Taladro percutor 800 W",
"quantity": "2",
"unit_price": "189.00",
"discount": "10.00",
"taxes": [{ "type": "iva", "rate": "iva_15" }]
}
],
"payments": [
{
"method": "otros_sistema_financiero",
"term": { "length": 30, "unit": "days" }
}
],
"additional_info": [{ "name": "Orden de compra", "value": "OC-1041" }]
}El comprador
identification_type dice qué identificación trae:
| Valor | Identificación |
|---|---|
ruc | RUC, 13 dígitos con su dígito verificador |
cedula | Cédula, 10 dígitos con su dígito verificador |
pasaporte | Pasaporte |
exterior | Identificación del exterior |
consumidor_final | Sin identificación: no envíes nada más |
Consumidor final solo hasta USD 50
El SRI no acepta facturas a consumidor final por más de USD 50. Por encima, identifica al comprador. Lo revisamos antes de numerar.
Revisamos el dígito verificador de cada RUC y cédula, en todo lugar donde la API recibe uno: un dígito mal tipeado responde 422 en ese campo, con Esta cédula no es válida: revisa sus dígitos, en vez de llegar al SRI. Los RUC de sociedades (tercer dígito 9) no pasan por el módulo 11, como anunció el SRI al cambiar cómo los genera.
¿Tienes solo la identificación? Consulta el RUC o la cédula y completa el nombre con lo que registra el SRI.
email es obligatorio para quien no es consumidor final: ahí enviamos la factura autorizada, en cualquier ambiente, y aparece en su información adicional. Sin él, la API responde 422 en buyer.email. address es opcional.
El correo de consumidor final es siempre consumidorfinal@fiscalbase.io: si envías un email con él, lo aceptamos y lo ignoramos. La factura, su respuesta y su información adicional llevan esa dirección, y nunca le enviamos nada: ni el correo automático ni el código del portal. Un envío manual con to sí llega a la dirección que indiques.
Las líneas
| Campo | Regla |
|---|---|
description | Obligatorio, una sola línea, hasta 300 caracteres |
code, auxiliary_code | Opcionales, hasta 25 caracteres: tu código de producto y uno auxiliar. Una línea con IVA 5 % exige auxiliary_code (mira abajo) |
quantity, unit_price | Texto con hasta 6 decimales |
discount | Monto del descuento de la línea, dos decimales, nunca mayor que cantidad × precio. Por defecto, 0 |
taxes | Exactamente un IVA por línea, { "type": "iva", "rate": "iva_15" }, y si aplica un ICE y un IRBPNR (cómo) |
unit | Opcional, hasta 50 caracteres: saco, kg… |
unsubsidized_price | Opcional: el precio sin subsidio de un bien subsidiado |
additional_info | Hasta 3 detalles { name, value } bajo la línea |
Las tarifas de IVA son iva_15, iva_5, iva_0, no_objeto y exento. Cómo calculamos los totales está en Montos e impuestos.
Materiales de construcción (IVA 5 %)
El IVA 5 % existe solo para los materiales de construcción que el SRI lista, y el anexo 23 de la ficha técnica obliga a identificar cuál vendes: la línea lleva en auxiliary_code el código exacto de la tabla 31. Sin él respondemos 422 en lines[n].auxiliary_code.
{
"code": "CEM-50",
"auxiliary_code": "F010401",
"description": "Cemento 50 kg",
"quantity": "3",
"unit_price": "8.50",
"taxes": [{ "type": "iva", "rate": "iva_5" }]
}| Código | Material | Código | Material |
|---|---|---|---|
F010101 | Varilla corrugada AS42 de 8, 10 y 12 mm | F010501 | Chatarra ferrosa |
F010201 | Arcilla | F010601 | Morteros |
F010202 | Arena | F010701 | Clinker |
F010203 | Cal | F010702 | Puzolana |
F010204 | Caliza | F010703 | Yeso |
F010205 | Pétreos | F010801 | Adoquín |
F010301 | Hormigón premezclado | F010802 | Bloques |
F010401 | Cemento y sus derivados | F010803 | Ladrillos |
F010402 | Residuo cemento | F010804 | Productos de hormigón prefabricado |
La regla vale también para las notas de crédito y las liquidaciones de compra.
Transporte comercial
Si eres una operadora de transporte comercial (excepto taxis) o uno de sus socios, el anexo 25 fija los códigos de tus líneas en auxiliary_code:
| Código | Quién factura a quién | Qué exigimos |
|---|---|---|
H492001 | La operadora a su cliente | plate: la placa del vehículo |
H492002 | El socio a la operadora | Un comprador con RUC |
plate va en la factura. Para transporte comercial son tres letras y cuatro dígitos, como PCM4567 (tabla 33). La guardamos en mayúsculas.
{
"plate": "PCM4567",
"lines": [
{
"auxiliary_code": "H492001",
"description": "Flete Quito–Guayaquil",
"quantity": "1",
"unit_price": "180.00",
"taxes": [{ "type": "iva", "rate": "iva_0" }]
}
]
}Combustibles
Si vendes combustibles, cada línea de combustible lleva en code y description los de la tabla 30, y la factura la placa del vehículo en plate (anexos 12 y 16). Sin vehículo, usa ZZZ9999.
code | description |
|---|---|
0103 | SÚPER |
0101 | EXTRA |
0174 | EXTRA CON ETANOL |
0121 | DIESEL PREMIUM |
0104 | DIESEL 2 |
Fundas plásticas
Las fundas que entregas en caja van en una línea propia con código ICE-FPN-01, ICE-FPR-02 (con rebaja del 50 %) o ICE-FPE-03 (exenta), y las dos primeras llevan ICE 3680 específico por funda (anexo 18):
{
"code": "ICE-FPN-01",
"description": "Funda/bolsa plástica",
"quantity": "3",
"unit_price": "0",
"taxes": [
{ "type": "iva", "rate": "iva_15" },
{ "type": "ice", "code": "3680", "unit_amount": "0.04" }
]
}Los pagos
Cada pago lleva su forma (method) y, si es a crédito, su plazo (term):
method | Forma de pago del SRI |
|---|---|
sin_sistema_financiero | Sin utilización del sistema financiero (efectivo) |
tarjeta_credito | Tarjeta de crédito |
tarjeta_debito | Tarjeta de débito |
otros_sistema_financiero | Otros con utilización del sistema financiero (transferencia, cheque) |
dinero_electronico | Dinero electrónico |
tarjeta_prepago | Tarjeta prepago |
compensacion_deudas | Compensación de deudas |
endoso_titulos | Endoso de títulos |
Con un solo pago, omite amount: cubre el total. Con varios, la suma debe dar el total. term es { "length": 30, "unit": "days" } (days, months o years); el correo a tu cliente le muestra la fecha de vencimiento.
Lo que puedes agregar
Cada bloque es opcional y se envía entero cuando lo usas.
| Campo | Qué es |
|---|---|
tip | La propina: suma al total, hasta el 10 % del subtotal |
delivery_note_number | El número de la guía de remisión que acompaña la mercadería |
export | Factura de exportación (anexo 4): incoterm, incoterm_place, origin_country, loading_port, destination_port, subtotal_incoterm y, si aplica, destination_country, acquisition_country, international_freight, international_insurance, customs_costs, other_transport_costs. Los países son códigos de la tabla 25 (593); los costos suman al total. El comprador necesita address |
reimbursement | Reembolso de gastos (anexo 5): { "documents": [...] }, cada comprobante con su emisor (supplier, supplier_type), payment_country, document_type, number, issue_date, authorization_number y sus taxes tal como los escribió su emisor ({ "type": "iva", "rate", "base", "value" }). Calculamos los totales |
withholdings | Retenciones que declara la propia factura (tablas 22 y 23), si comercializas combustibles o eres editor, distribuidor o voceador: { "type": "renta_2_por_mil", "value": "0.13" } |
substitute_delivery_note | Factura sustitutiva de guía de remisión (anexo 9): el traslado, con transportista, placa, fechas y destinos |
third_party_charges | Otros rubros de terceros (anexo 8): valores que cobras por cuenta de otros, { concept, amount }. No suman al total |
negotiable | Factura comercial negociable (anexo 11): exige la dirección del comprador y el plazo de cada pago. notification_email solo si notificas en lote |
iva_refunds | Devolución del IVA a personas adultas mayores (anexo 20), por tarifa, tal como la autorizó el servicio DIG. Se resta del total; el comprador se identifica con cédula |
additional_discounts | Un descuento sobre la base del IVA de una tarifa, después de las líneas |
fiscal_machine | La máquina fiscal que emite el comprobante (anexo 13): brand, model, serial |
La información adicional
additional_info son campos libres que se imprimen en el RIDE: orden de compra, vendedor, dirección de entrega. Cada uno es { name, value }, de hasta 300 caracteres, y los nombres no se repiten.
El comprobante admite 15 campos en total, y algunos los escribimos nosotros, siempre después de los tuyos. Cuentan dentro de los 15:
Nombre (name) | Qué lleva | Cuándo lo agregamos |
|---|---|---|
Email | El correo de quien recibe el comprobante. A consumidor final, consumidorfinal@fiscalbase.io | Cuando el comprobante tiene correo: siempre, salvo en la guía de remisión, que no lo lleva |
Gran Contribuyente | La resolución que declaraste para tu negocio (anexo 24) | En facturas, liquidaciones de compra y notas de crédito y de débito, solo si tu negocio declaró una resolución de gran contribuyente |
RUC Proveedor | El RUC de Fiscalbase, el proveedor del sistema de facturación (anexo 26) | Siempre |
No puedes enviar un campo con esos nombres: la API responde 422. Te quedan, entonces, 13 campos propios en una factura con comprador (también a consumidor final, que lleva su correo fijo), 12 si tu negocio es gran contribuyente, y 14 en una guía de remisión. Una lista más larga que eso responde 422 en additional_info, diciendo cuántas entradas admite.
La consola muestra esas entradas arriba en Información adicional, bloqueadas y marcadas como automáticas, con el valor que tendrán, y cuenta tus campos contra lo que queda. Si cambias el correo del comprador, el conteo cambia en el momento.
Lo que calculamos nosotros
No envías la fecha, el número, la clave de acceso, los subtotales, el IVA ni el total. La respuesta los trae calculados:
| Campo | Qué es |
|---|---|
issue_date | Hoy en Ecuador |
number | establecimiento-punto-secuencial, de tu numeración |
access_key | Los 49 dígitos del SRI, con su dígito verificador |
lines[].net, lines[].taxes | Neto e impuestos de cada línea |
taxes | Base y valor por tarifa de IVA y por código de ICE e IRBPNR |
subtotal, discount, iva, ice, irbpnr, tip, total | Los totales del comprobante |
subsidy | El subsidio total, si alguna línea es subsidiada |
reimbursement | Los totales del reembolso |
withheld_iva, withheld_renta | Lo retenido por la propia factura, por impuesto |
payments[].amount | El monto de cada pago |