# 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: REST API uses `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 and crm:read/crm:write — MCP only); rate limit 120 req/min/token. The MCP server uses OAuth 2.1 instead (see below)
- POST /api/v1/documents: create a factura/boleta and queue it for SUNAT (202 + `status: "processing"`; poll the document, or send `Prefer: wait=N` to block up to 30 s); 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|lino|oscura|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, GET/PATCH/DELETE /api/v1/customers/{id}: customer directory (POST upserts by doc_type + doc_number; DELETE is a hard delete that leaves history untouched)
- 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) authenticated with **OAuth 2.1** (MCP authorization spec 2025-06-18: dynamic client registration, PKCE, mandatory consent screen, refresh with rotation; `sk_live_` tokens still accepted during the transition) 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) and six CRM tools — list_crm_stages, get_crm_pipeline, move_crm_client, list_crm_interactions, log_crm_interaction (OAuth only: a log entry is signed by a person), archive_crm_interaction (the pipeline is operated over MCP, never configured: stages need a session)