Documentación
Conceptos
Lo mínimo de facturación electrónica peruana que necesitas para usar Bloques con confianza. Si vienes de otro país: SUNAT es la administración tributaria del Perú, el IGV es el impuesto al valor agregado (18%) y un PSE es un Proveedor de Servicios Electrónicos autorizado que firma y transmite los comprobantes.
Factura vs boleta
Bloques v1 emite dos tipos de comprobante del catálogo 01 de SUNAT: la factura electrónica (código 01) y la boleta de venta electrónica (código 03).
| Factura (01) | Boleta (03) | |
|---|---|---|
| Cliente | Empresa o negocio identificado con RUC (doc_type 6). Obligatorio. | Consumidor final: DNI (1), carnet de extranjería (4), pasaporte (7) o sin documento (0, "CLIENTES VARIOS"). |
| ¿Cuándo? | Ventas a empresas que necesitan sustentar costo/gasto y usar el crédito fiscal del IGV. | Ventas al público. El comprador no puede usar crédito fiscal. |
| Serie | Empieza con F (p. ej. F001) | Empieza con B (p. ej. B001) |
| Cliente omitido | No permitido — error customer_invalid. | Permitido — se emite a CLIENTES VARIOS. |
La regla RUC ↔ factura es estricta en ambos sentidos
Una factura exige cliente con RUC (doc_type 6) y una boleta no admite cliente con RUC — si tu cliente te da un RUC, lo correcto (y lo que Bloques valida) es emitir factura. Ambas violaciones responden 400 customer_invalid antes de consumir numeración.
Boletas mayores a S/ 700 exigen identificar al cliente
SUNAT exige que una boleta en soles cuyo total supere S/ 700 identifique al adquirente con su documento (DNI u otro). No puede ir a CLIENTES VARIOS: si omites el cliente, Bloques responde 400 customer_invalid antes de consumir numeración. Por debajo de S/ 700 el cliente sigue siendo opcional.
IGV y afectaciones (10 / 20 / 30)
El IGV es el 18%. En Bloques siempre escribes el precio final — lo que el cliente paga — y el sistema deriva la base imponible y el impuesto (base = total ÷ 1.18). Cada ítem lleva una afectación del catálogo 07 de SUNAT:
| Código | Nombre | Qué significa | Cálculo sobre el precio final |
|---|---|---|---|
10 | Gravado | Operación sujeta a IGV (el caso normal). Es el valor por defecto. | base = precio ÷ 1.18; IGV = precio − base. Ej.: 118.00 → base 100.00 + IGV 18.00. |
20 | Exonerado | Operación exonerada por ley (p. ej. ciertos productos agrícolas, Amazonía). | base = precio; IGV = 0. |
30 | Inafecto | Operación fuera del ámbito del IGV. | base = precio; IGV = 0. |
Un documento puede mezclar afectaciones; los totales gravado, exonerado e inafecto se acumulan por separado y el total siempre es la suma exacta de lo que cobraste por línea. El redondeo es a 2 decimales por línea (medio hacia arriba), igual que exige SUNAT.
Transferencias gratuitas (lo que regalas)
Cuando entregas algo sin cobrarlo —una bonificación "lleva 10, paga 9", una muestra, un premio, una donación— no se factura con precio 0 a secas: SUNAT lo trata como una operación no onerosa. La línea sale con precio e importe en 0.00, y lo que la sostiene es un valor de referencia: lo que ese bien habría costado si lo hubieras vendido.
En la venta eliges la afectación gratuita que corresponda (bonificación, publicidad, premio, donación, entrega a trabajadores…) y escribes el precio como siempre: ese número se convierte en el valor de referencia. Si la gratuita es gravada, su IGV se informa aparte y lo asumes tú — nunca se le cobra al cliente ni entra al total. Cuando todo el comprobante es gratuito, el importe total es 0.00 y lleva la leyenda "TRANSFERENCIA GRATUITA" que exige SUNAT.
Una línea gratuita no admite descuento, ISC ni ICBPER, y solo existe en facturas y boletas (una cotización o una nota de venta no declaran nada a SUNAT).
Recargo al consumo (restaurantes y bares)
Los restaurantes, bares y hoteles pueden cobrar un recargo al consumo (Decreto Ley 25988): un cargo de hasta el 13% del valor de los servicios que se reparte entre el personal. No es un tributo: no integra la base imponible del IGV ni genera IGV propio — simplemente se suma al total a pagar. Es opcional; tu empresa decide si lo aplica.
En Bloques lo activas en Configuración → Empresa (apagado por defecto) y eliges la tasa por defecto (p. ej. 5%). Al emitir puedes habilitarlo o cambiar la tasa por documento. El recargo se calcula sobre el valor de venta (la suma de las bases sin IGV): recargo = round2(valor_venta × tasa), y el total del comprobante pasa a ser monto con IGV + recargo.
En el XML UBL 2.1 se representa como un cac:AllowanceCharge global con ChargeIndicator=true y código 50 del catálogo 53 («cargo que no afecta la base del IGV»), sin TaxTotal propio. Alimenta ChargeTotalAmount y, por tanto, PayableAmount. El IGV no cambia.
Series y correlativos
Cada comprobante se numera como SERIE-CORRELATIVO, por ejemplo F001-42: serie F001, número 42 (sin ceros a la izquierda). Reglas:
- La serie tiene 4 caracteres: un prefijo obligatorio según el tipo —
Fpara facturas,Bpara boletas — seguido de 3 alfanuméricos (F001,B001,B0A2…). - El onboarding crea
F001yB001. Puedes tener varias series (una por local o canal). - El correlativo lo asigna Bloques de forma atómica y secuencial por serie en el momento de emitir; no se puede elegir ni reutilizar. Si no indicas serie, se usa la serie activa del tipo (la primera en orden alfabético).
- Consulta tus series y el próximo número con
GET /api/v1/series.
Estados del documento
| Estado | Qué significa | Qué hacer |
|---|---|---|
processing | El comprobante existe, su número ya está consumido y su PDF ya se puede imprimir y entregar, pero SUNAT todavía no lo evaluó: se está firmando y transmitiendo. Es el estado con el que nace TODO comprobante — la emisión es asíncrona. | Vuelve a consultarlo en unos segundos (o pide Prefer: wait al emitir). Nunca vuelvas a emitirlo: duplicarías el comprobante. |
accepted | SUNAT aceptó el comprobante. Tiene validez tributaria, hash y CDR. Es el estado final feliz. | Nada. Entrega el PDF/XML a tu cliente (Bloques puede enviarlo por correo automáticamente). |
rejected | SUNAT rechazó el comprobante (p. ej. RUC del cliente inválido o no habido). El número de serie ya se consumió y el documento cuenta para tu plan. | Lee sunat.cdr_description y sunat.observations, corrige el dato y emite un documento nuevo (tendrá otro correlativo). El rechazado no se puede "reparar". |
error | Falla técnica del PSE o de la red antes de obtener veredicto de SUNAT. No cuenta para tu plan. | Revisa sunat.error_message y vuelve a emitir con una nueva clave de idempotencia (la misma clave devolvería este documento fallido, no un reintento). |
El CDR
El CDR (Constancia de Recepción) es la respuesta firmada por SUNAT a tu comprobante: un ZIP con un XML que dice si fue aceptado o rechazado, con código y descripción (y a veces observaciones que no invalidan la aceptación). Es tu prueba legal de que el comprobante llegó a SUNAT — consérvalo. Bloques lo guarda automáticamente y lo expone en GET /api/v1/documents/{id}/cdr; la descripción viene resumida en el campo sunat.cdr_description del documento.
El hash y el código QR
El hash (campo sunat.hash) es el Valor Resumen del comprobante: el ds:DigestValue de la firma, es decir un resumen criptográfico del propio XML. Como no depende de la clave del firmante, Bloques lo calcula al emitir y no hay que esperar a SUNAT: el PDF sale con su QR completo desde el primer segundo, y al cerrarse se verifica contra el que devolvió el PSE. El código QR del PDF sigue el formato de la R.S. 097-2012/SUNAT, con campos separados por |:
RUC emisor | tipo (01/03) | serie | número | IGV | total | fecha emisión
| tipo doc. cliente | nro doc. cliente | hash
20123456789|03|B001|117|18.00|118.00|2026-06-09|1|44556677|kAbC...=Con el QR (o en la web de SUNAT con RUC + serie + número) cualquiera puede verificar el comprobante. Bloques lo genera e imprime automáticamente en todas las plantillas PDF.
Plazos SUNAT (7 días)
Los comprobantes electrónicos deben informarse a SUNAT dentro del plazo reglamentario. Bloques transmite en el momento, así que normalmente no piensas en esto; el límite importa solo si necesitas registrar una venta pasada:
issue_datepor defecto es hoy en hora de Lima (America/Lima).- Puedes fecharlo hasta 7 días hacia atrás como máximo.
- Nunca en el futuro. Fechas fuera de rango responden
400 validation.
Limitación importante de la v1
Aún no se emiten notas de crédito/débito ni anulaciones
Bloques v1 no emite notas de crédito (07), notas de débito (08) ni comunicaciones de baja (anulaciones). Están en el roadmap de la v2.
¿Qué implica? Un documento accepted es definitivo: no se puede editar ni eliminar. Si te equivocaste en un comprobante ya aceptado (monto, cliente, ítems), hoy debes gestionar la nota de crédito fuera de Bloques — por ejemplo desde el portal SOL de SUNAT (emisor SEE-SOL) u otro sistema autorizado — referenciando la serie y número del comprobante original.
Por eso: verifica los datos antes de emitir, y si automatizas con la API o agentes IA, usa claves de idempotencia y confirma con el usuario antes de cada emisión real.
Siguiente parada: la referencia completa de la API REST.