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.

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 — F para facturas, B para boletas — seguido de 3 alfanuméricos (F001, B001, B0A2…).
El onboarding crea F001 y B001. 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`	Estado transitorio mientras se firma y transmite. La emisión es síncrona, así que rara vez lo verás en una respuesta.	Vuelve a consultar el documento en unos segundos.
`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

Al firmar el XML se genera un hash criptográfico (campo sunat.hash) que identifica el documento firmado y se imprime en la representación impresa. 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_date por 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.