# Bloques

> Bloques emits SUNAT-valid Peruvian electronic invoices (facturas) and receipts (boletas): it builds the UBL 2.1 XML, signs and transmits it through the SmartPSE PSE, stores the signed XML / CDR / PDF, emails the customer, and exposes a web UI, a REST API and an MCP server for AI agents.

Two things to know before anything else: (1) every price sent to Bloques is a FINAL price with IGV 18% already included — the system back-calculates the tax base (base = total / 1.18); never send pre-tax prices. (2) Bloques operates against SUNAT in production: every accepted document is a real, fiscally binding tax document — there is no sandbox. v1 emits facturas and boletas only (no credit/debit notes, no voiding yet).

## Docs

- [Empieza aquí](/docs): product overview, 5-minute quickstart, plans (free: 10 docs/month; pro: S/40 for 3000 docs/month), the final-price/IGV rule (Spanish)
- [Conceptos](/docs/conceptos): factura vs boleta, IGV affectations 10/20/30, series and correlatives, document statuses, the CDR, hash and QR, SUNAT deadlines, v1 limitations (Spanish)
- [API REST](/docs/api): full endpoint reference with auth, scopes, request/response examples and error codes (Spanish)
- [MCP](/docs/mcp): MCP server connection guide and tool-by-tool reference (Spanish)
- [Guía para agentes IA](/docs/agentes-ia): step-by-step integration recipe for AI agents, worked checkout example, safety rules (English)
- [llms-full.txt](/llms-full.txt): complete self-contained API reference for LLMs — read this to integrate without browsing anything else (English)
- [openapi.json](/openapi.json): OpenAPI 3.1 specification of the REST API

## API basics

- Base URL: `/api/v1` — JSON in/out, CORS enabled
- Auth: `Authorization: Bearer sk_live_…` — tokens are created by a human in Configuración → API (session-only by design) with per-token scopes (documents/quotes/products/customers × read/write, plus expenses:write — MCP only); rate limit 120 req/min/token
- POST /api/v1/documents: create and emit a factura/boleta to SUNAT, synchronous; send an `Idempotency-Key` header for safe retries
- GET /api/v1/documents: list with filters (from, to, type, status, q, page, per_page); GET /api/v1/documents/{id}: one document with line items
- GET /api/v1/documents/{id}/pdf | /xml | /cdr | /zip: download files (pdf accepts ?template=clasica|moderna|minimal|ticket80; xml accepts ?unsigned=true; /zip bundles the signed XML and the CDR)
- GET /api/v1/documents/export: CSV export (same filters, max 5000 rows)
- POST/GET /api/v1/products, GET/PUT/DELETE /api/v1/products/{id}: product catalog (final prices, IGV included)
- POST/GET /api/v1/customers: customer directory (POST upserts by doc_type + doc_number)
- GET /api/v1/series: numbering series and next correlative; GET /api/v1/usage: monthly consumption vs plan; GET /api/v1/company: company profile
- MCP server: POST /api/mcp (Streamable HTTP, stateless, same Bearer tokens) with tools create_document, get_document, list_documents, get_document_files, list_products, create_product, search_customers, get_usage, create_expense (write-only: no tool reads expenses or money)