Documentación

Empieza aquí

Bloques emite boletas y facturas electrónicas aceptadas por SUNAT en segundos. Tú describes la venta (cliente, ítems, precios finales); Bloques construye el XML UBL 2.1, lo firma y transmite a SUNAT a través del PSE SmartPSE, guarda el XML firmado, el CDR y el PDF, envía el comprobante por correo a tu cliente y te devuelve el resultado en la misma llamada. Todo está disponible desde la interfaz web, una API REST y un servidor MCP para agentes IA.

Quickstart — tu primera boleta en 5 minutos

1. 1

   Crea tu cuenta

   Regístrate con tu correo en la página principal. Una cuenta administra una empresa (un RUC).

2. 2

   Completa el onboarding con tu RUC

   Ingresa tu RUC y dirección fiscal. Bloques registra tu empresa ante el PSE (SmartPSE) directamente en producción y crea tus series iniciales F001 (facturas) y B001 (boletas). No hay ambiente de pruebas: lo que emitas tiene validez tributaria.

3. 3

   Autoriza al PSE en SUNAT SOL (checklist)

   Una sola vez, en SUNAT Operaciones en Línea (SOL) con tu Clave SOL:

   • Autoriza a SmartPSE como tu Proveedor de Servicios Electrónicos (PSE) para la emisión de comprobantes electrónicos.
   • Verifica que tu RUC esté activo y habido, con domicilio fiscal actualizado.

   Sin esta autorización SUNAT rechazará tus comprobantes.

4. 4

   Crea un producto (opcional pero recomendado)

   En Productos registra tu catálogo con código, nombre y precio final (con IGV incluido). Luego emites referenciando el código y Bloques completa descripción, unidad, precio y afectación. También puedes emitir con líneas libres sin catálogo.

5. 5

   Emite tu primera boleta

   Desde la UI: Nuevo documento → Boleta, agrega un ítem y emite. Si no indicas cliente, sale a nombre de CLIENTES VARIOS. O desde la API (crea antes un token en Configuración → API):

   curl -X POST https://bloques.example.com/api/v1/documents \
     -H "Authorization: Bearer sk_live_..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: primera-boleta-001" \
     -d '{
       "type": "boleta",
       "items": [
         { "description": "Menú del día", "quantity": 2, "unit_price": 25.00 }
       ]
     }'

   La respuesta llega con status: "accepted", los totales calculados, el hash de SUNAT y las rutas para descargar PDF, XML y CDR.

La regla más importante: precios finales con IGV

En Bloques todos los precios que envías o registras son precios FINALES: lo que el cliente paga, con el IGV (18%) ya incluido. Nunca envíes precios sin impuesto. El sistema calcula la base hacia atrás dividiendo entre 1.18:

Tú envías:        unit_price = 118.00   (precio final, lo que se cobra)
Bloques calcula:    base  = 118.00 / 1.18 = 100.00   (valor de venta)
                  IGV   = 118.00 - 100.00 = 18.00
                  total = 118.00

118 = 100 + 18  →  el total nunca cambia respecto a lo que cobraste.

Esto evita el clásico descuadre de un céntimo entre tu caja y el comprobante. La afectación del IGV se indica por ítem: 10 gravado (con IGV, por defecto), 20 exonerado y 30 inafecto (sin IGV en ambos casos: el precio final es la base). Más detalle en Conceptos.

Planes y límites

• Los meses se cuentan por calendario de America/Lima (el contador se reinicia el día 1 a las 00:00 hora de Lima).
• Cuentan los documentos accepted, rejected y processing (un rechazo también consumió una firma del PSE). Los que terminan en error no cuentan.
• Al alcanzar el límite, la emisión responde 402 plan_limit. Consulta tu consumo en GET /api/v1/usage o en el panel.

¿Qué sigue?

¿Integras con un LLM? Apunta a tu agente a /llms-full.txt — una referencia autocontenida de toda la API — o al spec /openapi.json.