API REST

Crea el comprobante y lo encola. Responde 202 Accepted con el documento en processing —número, totales e ítems ya definitivos— y un Location a su detalle. La firma, el envío a SUNAT y el veredicto ocurren después, con reintentos automáticos. En producción es una emisión fiscal real.

Cabecera Prefer: wait

Si prefieres esperar el veredicto en la misma llamada, manda Prefer: wait=N (RFC 7240, segundos, tope 30). Si SUNAT contesta dentro del plazo la respuesta es 201 con el documento ya cerrado y la cabecera Preference-Applied: wait=N; si no, es 202 y consultas GET /api/v1/documents/{id} cuando quieras. Es una preferencia, no una garantía: el veredicto de SUNAT no es del request.

Cabecera Idempotency-Key

Envía Idempotency-Key: <clave única> (máx. 100 caracteres, p. ej. el ID de tu orden) en cada emisión. Si repites una clave ya usada por tu empresa, Bloques no emite de nuevo: responde 200 con el documento original y la cabecera Idempotent-Replay: true. Así un timeout o doble clic jamás genera dos comprobantes. Ojo: el replay devuelve el documento original aunque haya quedado en estado error — para reintentar de verdad usa una clave nueva.

Cuerpo

En qué sucursal queda la venta

El token actúa con el acceso por sucursal de quien lo creó. La sucursal de la venta (branch_id en la respuesta) sale, en este orden:

• con cash_register_id, la sucursal de la caja;
• si no, con branch_id, esa sucursal;
• si no, si el acceso es una sucursal, esa;
• si no, si son varias (pero no todas), 400 branch_required: manda branch_id o cash_register_id. No se crea nada ni se consume correlativo;
• con acceso a todas, como siempre: la única sucursal activa de la empresa si tiene una sola; si no, sin sucursal (branch_id: null).

Una series explícita cuyo dueño es una sucursal o caja fuera del acceso es 422 series_not_found, como una que no existe; una serie de empresa (sin dueño) sirve siempre.

Con qué RUC sale la venta

Un negocio puede emitir con varios RUC, cada uno con sus series y sus correlativos (dos RUC pueden tener cada uno su F001-1). La respuesta dice siempre con cuál salió el documento (issuer: { ruc, razon_social }). Con un solo RUC no cambia nada: todo sale con el principal.

El RUC por defecto de la venta lo decide el issuer_mode del negocio (ver GET /issuers):

• En modo register («Según la caja») la integración tiene que mandar cash_register_id (o un issuer_ruc): sin ninguno de los dos responde 400 register_required. Caer al principal en silencio emitiría con el RUC equivocado.
• El modo rige con dos o más RUC activos. Con uno solo (varios RUC encendido y los demás desactivados) toda venta sale con el principal, como en single: sin register_required, y una caja o sucursal asignada a un RUC desactivado vende con el principal.
• issuer_ruc elige otro RUC del negocio. Uno distinto del por defecto exige issuers:choose (403 insufficient_permissions); pedir el mismo por defecto no. Con issuer_mode: "single", cualquiera que no sea el principal es 400 validation.
• El RUC tiene que poder vender: ser del negocio (422 issuer_not_found), estar activo (409 issuer_inactive), autorizado ante el PSE (409 issuer_not_ready) y, si es del Nuevo RUS, vender solo en su sucursal (422 issuer_wrong_establishment) y nunca facturas (400 validation).
• El RUC se resuelve antes del correlativo: ninguno de estos errores consume número.
• Con un issuer_ruc distinto del por defecto, la caja y la sucursal se prefieren pero no obligan: la serie de ese RUC de la caja; si no, la de la sucursal de la venta; si no, la de empresa (sin dueño) de ese RUC. Solo falla (422 series_not_found) si ese RUC no tiene ninguna serie activa del tipo.

Objeto customer

Objeto item

Cada ítem referencia un producto del catálogo (product_id o code) o es una línea libre (description + unit_price).

Objeto payment

Ejemplo

curl -X POST https://enbloques.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: orden-8842" \
  -d '{
    "type": "factura",
    "customer": {
      "doc_type": "6",
      "doc_number": "20512345678",
      "name": "ACME PERU S.A.C.",
      "email": "facturas@acme.pe"
    },
    "items": [
      { "code": "CONSULT-HR", "quantity": 10 },
      { "description": "Bolsa ecológica", "quantity": 2, "unit_price": 5.90, "unit_code": "NIU" }
    ],
    "notes": "Orden de compra OC-2026-118"
  }'

{
  "id": "9f1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "factura",
  "doc_type": "01",
  "series": "F001",
  "number": 42,
  "full_number": "F001-42",
  "file_name": "20123456789-01-F001-42",
  "issuer": { "ruc": "20123456789", "razon_social": "MI EMPRESA S.A.C." },
  "status": "processing",
  "issue_date": "2026-06-09",
  "issue_time": "14:32:05",
  "due_date": null,
  "currency": "PEN",
  "customer": {
    "docType": "6",
    "docNumber": "20512345678",
    "name": "ACME PERU S.A.C.",
    "email": "facturas@acme.pe"
  },
  "totals": {
    "gravado": "1010.00",
    "exonerado": "0.00",
    "inafecto": "0.00",
    "igv": "181.80",
    "isc": "0.00",
    "icbper": "0.00",
    "descuento": "0.00",
    "total_value": "1010.00",
    "recargo_consumo": "0.00",
    "recargo_rate": null,
    "total": "1191.80"
  },
  "amount_in_words": "MIL CIENTO NOVENTA Y UNO CON 80/100 SOLES",
  "payment": { "type": "Contado" },
  "notes": "Orden de compra OC-2026-118",
  "detraction": null,
  "sunat": {
    "hash": null,
    "settled_at": null,
    "cdr_description": null,
    "observations": null,
    "error_message": null
  },
  "files": { "pdf": null, "xml": null, "cdr": null, "zip": null },
  "items": [
    {
      "position": 1,
      "product_id": "1a2b3c4d-0000-4000-8000-000000000001",
      "code": "CONSULT-HR",
      "description": "Consultoría por hora",
      "unit_code": "HUR",
      "quantity": "10",
      "unit_price": "118.00",
      "unit_value": "100.0000000000",
      "line_base": "1000.00",
      "line_discount": "0.00",
      "disc_rate": null,
      "line_igv": "180.00",
      "line_isc": "0.00",
      "isc_rate": null,
      "line_icbper": "0.00",
      "line_total": "1180.00",
      "affectation": "10"
    },
    {
      "position": 2,
      "product_id": null,
      "code": null,
      "description": "Bolsa ecológica",
      "unit_code": "NIU",
      "quantity": "2",
      "unit_price": "5.90",
      "unit_value": "5.0000000000",
      "line_base": "10.00",
      "line_discount": "0.00",
      "disc_rate": null,
      "line_igv": "1.80",
      "line_isc": "0.00",
      "isc_rate": null,
      "line_icbper": "0.00",
      "line_total": "11.80",
      "affectation": "10"
    }
  ],
  "source": "api",
  "emailed_to": "facturas@acme.pe",
  "emailed_at": "2026-06-09T19:32:08.412Z",
  "created_at": "2026-06-09T19:32:06.120Z"
}

Códigos de estado

Errores

Ya no hay un 502 en la emisión. Un fallo del PSE ya no ocurre dentro del request: se reintenta con backoff y, si se agota, el documento queda en status: "error" (sin consumir tu plan) y puede reenviarse con su mismo número.

Lista documentos, los más recientes primero. Sin los ítems de línea (pídelos por id). Solo los de las sucursales del acceso de quien creó el token (y el total los cuenta igual); con acceso restringido, los documentos sin sucursal no aparecen.

curl "https://enbloques.com/api/v1/documents?from=2026-06-01&to=2026-06-30&type=boleta&status=accepted&per_page=50" \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "9f1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "boleta",
      "doc_type": "03",
      "series": "B001",
      "number": 117,
      "full_number": "B001-117",
      "file_name": "20123456789-03-B001-117",
      "issuer": { "ruc": "20123456789", "razon_social": "MI EMPRESA S.A.C." },
      "status": "accepted",
      "issue_date": "2026-06-09",
      "issue_time": "11:02:44",
      "due_date": null,
      "currency": "PEN",
      "customer": { "docType": "0", "docNumber": "0", "name": "CLIENTES VARIOS" },
      "totals": { "gravado": "100.00", "exonerado": "0.00", "inafecto": "0.00",
                  "igv": "18.00", "isc": "0.00", "icbper": "0.00", "descuento": "0.00", "total_value": "100.00",
                  "recargo_consumo": "0.00", "recargo_rate": null, "total": "118.00" },
      "amount_in_words": "CIENTO DIECIOCHO CON 00/100 SOLES",
      "payment": { "type": "Contado" },
      "notes": null,
      "sunat": { "hash": "xY9z...=", "cdr_description": "La Boleta numero B001-117, ha sido aceptada",
                 "observations": null, "error_message": null },
      "files": { "pdf": "/api/v1/documents/9f1b.../pdf", "xml": "/api/v1/documents/9f1b.../xml",
                 "cdr": "/api/v1/documents/9f1b.../cdr", "zip": "/api/v1/documents/9f1b.../zip" },
      "source": "api",
      "emailed_to": null,
      "emailed_at": null,
      "created_at": "2026-06-09T16:02:45.001Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 1
}

Devuelve un documento por su UUID, incluyendo el arreglo items (misma forma que la respuesta de creación).

curl https://enbloques.com/api/v1/documents/9f1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer sk_live_..."

Descarga el PDF imprimible (application/pdf, adjunto {file_name}.pdf).

curl -L -o F001-42.pdf \
  "https://enbloques.com/api/v1/documents/9f1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d/pdf?template=ticket80" \
  -H "Authorization: Bearer sk_live_..."

Descarga el XML firmado (application/xml, {file_name}.xml) — el archivo con valor legal. Para bajar el XML firmado y el CDR en un solo archivo, usa /documents/{id}/zip.

Descarga el CDR de SUNAT (constancia de recepción) como XML (application/xml, {file_name}-cdr.xml). Solo existe cuando SUNAT respondió (documentos accepted o rejected); en la respuesta JSON, files.cdr es null cuando no hay CDR.

Descarga el XML firmado y el CDR juntos en un ZIP (application/zip, {file_name}.zip), con {file_name}.xml y {file_name}-cdr.xml dentro. Si solo existe uno de los dos —un documento rechazado se firmó pero no tiene CDR— el ZIP trae ese. Es la descarga que ofrece la app.

Corrige y reenvía un documento que SUNAT rechazó (status:"rejected") o que no llegó a transmitirse (status:"error"), reutilizando el mismo serie-correlativo. Un comprobante rechazado no existe legalmente, así que su número puede reusarse; uno accepted es inmutable —reenviarlo daría el error 1033 de SUNAT («el comprobante ya fue informado»)— y se bloquea con 409 not_resendable.

El cuerpo es el documento corregido, con la misma forma que POST /documents; se ignoran type y series (la identidad del documento es fija por su id). Se vuelven a correr todas las validaciones. La cuota se comporta como en una primera emisión: un reenvío que termina accepted consume una unidad del plan y, si vuelve a rechazarse, la devuelve (solo los accepted cuentan). Como la emisión, encola: devuelve 202 con el documento en processing, y honra Prefer: wait=N (entonces es 200 con el veredicto ya puesto).

curl -X POST https://enbloques.com/api/v1/documents/9f1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d/resend \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "factura",
    "currency": "PEN",
    "customer": { "doc_type": "6", "doc_number": "20123456789", "name": "ACME S.A.C." },
    "items": [ { "description": "Servicio de consultoría", "quantity": 1, "unit_price": 118.00 } ]
  }'

Exporta documentos a CSV (UTF-8 con BOM, separado por comas) con los mismos filtros del listado (from, to, type, status, q, issuer_ruc) y el mismo acceso por sucursal (con token, el de quien lo creó; desde la app con sesión, el botón «Exportar CSV», la sucursal elegida en la app). Máximo 5000 filas, las más recientes primero. Ideal para conciliaciones o para tu contador.

Columnas:

full_number, type, status, issue_date, issue_time, due_date, currency,
customer_doc_type, customer_doc_number, customer_name,
total_gravado, total_exonerado, total_inafecto, total_igv, total_value, total,
amount_in_words, sunat_hash, cdr_description, source, emailed_to, created_at, id

Un negocio que emite con varios RUC recibe además, al final, issuer_ruc e issuer_razon_social: el RUC con el que salió cada documento. Van al final para que quien lee el archivo por posición no se corra; con un solo RUC el archivo es el de siempre.

curl -L -o documentos-junio.csv \
  "https://enbloques.com/api/v1/documents/export?from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer sk_live_..."

Crea una cotización. Devuelve 201 con la cotización y sus ítems.

curl -X POST https://enbloques.com/api/v1/quotes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "PEN",
    "title": "Cambio de luminarias — Sede Surco",
    "valid_until": "2026-07-15",
    "customer": { "doc_type": "6", "doc_number": "20123456789", "name": "CLIENTE S.A.C." },
    "items": [{ "description": "Consultoría", "quantity": 1, "unit_price": 1180 }]
  }'

Lista cotizaciones (más recientes primero) con filtros y paginación.

Devuelve una cotización con sus ítems, totales, estado derivado y la ruta del PDF.

Reemplaza el contenido de una cotización editable (su code se conserva). El mismo cuerpo que POST /quotes. Falla si la cotización ya fue convertida.

Elimina una cotización. Falla con 409 si ya fue convertida en comprobante.

Descarga el PDF de la cotización (se genera al vuelo, no se cachea). ?template=clasica (por defecto), ?template=minimal, ?template=lino o ?template=oscura.

curl -L -o COT-0001.pdf \
  "https://enbloques.com/api/v1/quotes/{id}/pdf?template=minimal" \
  -H "Authorization: Bearer sk_live_..."

Crea un producto del catálogo.

Precios por cantidad

Un producto —o un modificador— puede llevar hasta 20 escalones: desde min_quantity unidades, el precio unitario final es unit_price. Son precios absolutos, no descuentos, y la aritmética fiscal no cambia (la base se sigue derivando del precio final). Gana el escalón más alto que la cantidad calificadora de la línea alcanza —su propia quantity, o la de la cuenta global cuando el producto tiene pool_tiers (ver abajo)—; por debajo del primero rige el unit_price del producto. El orden del array no importa y dos escalones no pueden compartir la misma min_quantity.

Los escalones solo entran cuando el ítem omite unit_price: un precio enviado gana siempre. Tampoco se exige que la tabla baje — puedes cobrar más a mayor cantidad si tu negocio lo necesita. Omitir price_tiers al actualizar no toca nada; [] los limpia. En las respuestas el campo está siempre presente ([] cuando no hay) y sus valores son strings, como todo importe de esta API. Un modificador usa los suyos y nunca hereda los del padre.

curl -X POST https://enbloques.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "POLO",
    "name": "Polo",
    "unit_price": 5.00,
    "price_tiers": [
      { "min_quantity": 12, "unit_price": 4.50 },
      { "min_quantity": 60, "unit_price": 4.00 }
    ]
  }'

# 30 polos, sin unit_price en el ítem → S/ 4.50 por unidad
curl -X POST https://enbloques.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "boleta", "items": [ { "code": "POLO", "quantity": 30 } ] }'

Cuenta global de escalones

Un producto puede tener encendida la cuenta global de escalones (pool_tiers), que hace que varios productos alcancen juntos los escalones de arriba. La cuenta nunca cambia qué tabla se lee —cada producto se cobra siempre con la suya—, solo con qué cantidad se consulta:

Con shorts a S/ 10 (desde 12 → S/ 9) y polos a S/ 15 (desde 12 → S/ 14), los dos con la cuenta encendida, un pedido de 7 shorts + 5 polos = 12 prendas se cobra a S/ 9 y S/ 14, cada uno leyendo su propia tabla.

Reglas que conviene saber antes de integrar: toda línea con producto identificado y cuenta encendida aporta su cantidad, sin importar cómo se fijó su precio —enviar unit_price conserva ese precio pero la línea igual cuenta—, y lo único que no aporta es una línea libre (sin producto). Un modificador no tiene cuenta propia: hereda la del producto y sigue usando sus escalones. Las líneas sin cuenta no suman entre sí: cada una se mira sola. Un producto con cuenta pero sin escalones propios aporta su cantidad y se cobra a su unit_price de siempre. En el PUT parcial el campo tiene dos estados: omitirlo no toca nada y un booleano lo enciende o apaga. La nota de crédito no vuelve a tarifar —copia los precios del comprobante original—, así que devolver 5 de 12 prendas las acredita al precio del escalón y las 7 que quedan lo conservan.

curl -X POST https://enbloques.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SHORT",
    "name": "Short",
    "unit_price": 10.00,
    "pool_tiers": true,
    "price_tiers": [ { "min_quantity": 12, "unit_price": 9.00 } ]
  }'

→ 201 { ..., "pool_tiers": true, ... }

# 7 shorts + 5 polos, los dos con pool_tiers y sin unit_price en los ítems
# → 12 unidades calificadoras: los shorts a S/ 9.00 y los polos a S/ 14.00
curl -X POST https://enbloques.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "boleta", "items": [ { "code": "SHORT", "quantity": 7 },
                                     { "code": "POLO-P", "quantity": 5 } ] }'

Opciones de precio

Cuatro booleanos dicen qué perillas de precio muestra la ficha del producto en la app: uses_modifiers (presentaciones), uses_price_tiers (price_tiers y pool_tiers), uses_extras (extras) y uses_agreements (la banda de solo lectura con lo que cobra cada acuerdo). Son solo de visualización: la emisión, las cotizaciones y las notas de venta tarifan con los datos, nunca con estos campos.

Mandar los datos enciende su opción, aunque el mismo request diga false: modifiers no vacío enciende uses_modifiers; escalones (del producto o de un modificador) o pool_tiers: true encienden uses_price_tiers; extras no vacío enciende uses_extras. Casi nunca hace falta mandarlos. La app muestra opción O datos, así que apagar una opción mientras el producto tiene esos datos no los esconde; y uses_agreements apagado solo oculta la banda: los acuerdos siguen aplicando. En el PUT parcial, omitir una clave no la toca.

Combos

Un combo agrupa varios productos con su propio precio: «Combo clásico» = 1 hamburguesa + 1 papas + 2 gaseosas a S/ 25.00. Es un producto con kind: "combo": su unit_price es el precio del combo, se fija al crearlo y se edita como cualquier precio — nunca se recalcula desde sus componentes, y cambiar el precio de uno no lo mueve. En la venta es una línea (por product_id o code), y en el comprobante y el XML sale esa línea con los impuestos del combo. Los componentes solo cuentan para el stock: vender n combos descuenta n × quantity de cada uno (con el módulo de inventario), una nota de crédito por devolución los repone, y el combo nunca lleva stock propio (track_stock se guarda en false). Un combo va siempre en NIU, sin icbper y sin presentaciones ni extras: su precio es unit_price, con price_tiers para precios por volumen.

kind y components van juntos: components con productos y sin kind lo vuelve combo; kind: "combo" sin productos, o product/service con productos, en el mismo request es un 400 validation. components se reemplaza entero, como images: omitirlo no toca nada, [] lo vuelve un producto normal (lo que diga su unidad, o el kind que mandes). Las respuestas lo traen como [{ product_id, quantity, position }] (quantity con 3 decimales), [] si no es combo. Las reglas se comprueban en toda escritura de producto, también en una que no manda components pero cambia algo de lo que el combo depende:

• un componente que no es un producto de la empresa → 422 component_not_found (el id de otra empresa contesta igual);
• el combo dentro de sí mismo, un combo dentro de otro, o volver combo un producto que ya va dentro de uno → 422 invalid_combo (sin anidamiento);
• todos los componentes llevan la affectation del combo y ninguno lleva isc_rate ni icbper: la línea del comprobante es una, con los impuestos del combo → 422 invalid_combo. Por lo mismo no se puede cambiar la afectación del combo, ni ponerle ISC o ICBPER a un componente, mientras estén juntos;
• kind: "combo" en un producto sin componentes, o product/service en un combo sin mandar también components: [] → 422 invalid_combo;
• presentaciones (modifiers) o extras en un combo: en el mismo request, 400 validation; si el producto que se vuelve combo ya los tiene, 422 invalid_combo;
• el mismo product_id dos veces → 400 validation.

curl -X POST https://enbloques.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "COMBO-1", "name": "Combo clásico", "kind": "combo", "unit_price": 25.00,
        "components": [ { "product_id": "<id hamburguesa>", "quantity": 1 },
                        { "product_id": "<id papas>", "quantity": 1 },
                        { "product_id": "<id gaseosa>", "quantity": 2 } ] }'

Por MCP se arman igual: bloques_create_product y bloques_update_product aceptan components y kind: "combo" con las mismas reglas, y bloques_list_products devuelve los components de cada combo.

Imágenes del producto

Un producto puede llevar hasta 3 imágenes. El orden del array es el orden y la primera es la portada (la miniatura que se ve en el catálogo de la app). Lo que viaja por esta API es la referencia, nunca los bytes:

"images": [
  {
    "key": "products/{company_id}/{product_id}/9f2c…-polo.webp",
    "name": "polo-azul.webp",
    "content_type": "image/webp",
    "bytes": 48213
  }
]

La subida es solo con sesión de navegador. Los bytes van a POST /api/products/images (multipart, campo file, con product_id opcional), que los guarda en R2 y devuelve exactamente el objeto de arriba — eso es lo que se reenvía dentro de images. La app convierte cada foto a WebP en el navegador antes de subirla, porque la API corre en Cloudflare Workers y no tiene códec de imagen. No hay ruta v1 para la subida y un token no puede hacerla; leer los bytes (GET /api/products/images?key=…) también es solo sesión, y por eso este contrato no promete ninguna URL.

La key se comprueba al escribir, no solo al servir: una clave que no vive bajo el prefijo de tu propia empresa devuelve 422 invalid_image_key — es el único aislamiento entre empresas que tiene R2. Se aceptan PNG, JPEG y WebP, decididos por magic number (no por el tipo declarado), 5 MB máximo por archivo; el PDF se rechaza. En el PUT, images es reemplazo completo: omitirlo no toca nada, [] deja el producto sin imágenes y cualquier array reemplaza la lista entera. Quitar una imagen del array no borra el objeto de R2.

Modificadores: cómo se sincronizan

Los modificadores no tienen rutas propias: se gestionan dentro del payload del producto, en un solo request atómico. Al crear o actualizar, el array modifiers se sincroniza preservando ids:

La position no se envía: es el índice en el array. Los nombres son únicos por producto entre los modificadores activos, y los code no nulos también. Toda respuesta de producto incluye modifiers (array vacío cuando no hay).

curl -X POST https://enbloques.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "CAFE-250", "name": "Café molido 250g", "unit_price": 35.00 }'

curl -X POST https://enbloques.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "POLO-ALG",
    "name": "Polo algodón",
    "unit_code": "ZZ",
    "unit_price": 32.00,
    "modifiers": [
      { "name": "Cuello camisero · Adulto", "code": "CAM-AD", "unit_price": 32.00 },
      { "name": "Cuello rib · Adulto",      "code": "RIB-AD", "unit_price": 28.00 },
      { "name": "Cuello camisero · Niño",   "code": "CAM-NI", "unit_price": 30.00 }
    ]
  }'

{
  "id": "1a2b3c4d-0000-4000-8000-000000000001",
  "code": "CAFE-250",
  "name": "Café molido 250g",
  "description": null,
  "unit_code": "NIU",
  "kind": "product",
  "unit_price": "35.00",
  "currency": "PEN",
  "affectation": "10",
  "isc_rate": null,
  "icbper": false,
  "track_stock": true,
  "min_stock": null,
  "barcode": null,
  "cost": null,
  "price_tiers": [],
  "pool_tiers": false,
  "uses_modifiers": false,
  "uses_price_tiers": false,
  "uses_extras": false,
  "uses_agreements": false,
  "is_public": false,
  "categories": [],
  "category_ids": [],
  "active": true,
  "modifiers": [],
  "components": [],
  "created_at": "2026-06-09T15:00:00.000Z",
  "updated_at": "2026-06-09T15:00:00.000Z"
}

{
  "id": "2b3c4d5e-0000-4000-8000-000000000002",
  "code": "POLO-ALG",
  "name": "Polo algodón",
  "unit_code": "ZZ",
  "unit_price": "32.00",
  "currency": "PEN",
  "affectation": "10",
  "active": true,
  "modifiers": [
    { "id": "aaaa1111-0000-4000-8000-000000000001", "name": "Cuello camisero · Adulto", "code": "CAM-AD", "unit_price": "32.00", "position": 0, "active": true },
    { "id": "aaaa1111-0000-4000-8000-000000000002", "name": "Cuello rib · Adulto",      "code": "RIB-AD", "unit_price": "28.00", "position": 1, "active": true },
    { "id": "aaaa1111-0000-4000-8000-000000000003", "name": "Cuello camisero · Niño",   "code": "CAM-NI", "unit_price": "30.00", "position": 2, "active": true }
  ],
  "created_at": "2026-08-01T15:00:00.000Z",
  "updated_at": "2026-08-01T15:00:00.000Z"
}

Lista el catálogo (solo activos por defecto), ordenado por código.

Cada producto de la página trae su arreglo modifiers (vacío cuando no tiene), resuelto en la misma consulta: no hace falta un segundo request para descubrirlas. También trae su pool_tiers (cuenta global de escalones) y sus cuatro uses_* (opciones de precio).

{ "data": [ { "id": "…", "code": "CAFE-250", "modifiers": [], … } ], "page": 1, "per_page": 50, "total": 12 }

Devuelve un producto por UUID, incluyendo sus modifiers activas ordenadas por position.

Actualización parcial: envía solo los campos a cambiar (mismos campos y reglas que la creación; todos opcionales; description admite null para limpiar). Los documentos ya emitidos conservan su snapshot. Mandar modifiers sincroniza la lista completa con la semántica de arriba (con id actualiza, sin id crea, ausente desactiva); omitirlo no toca ninguna. pool_tiers tiene dos estados: omitirlo no toca la cuenta global y un booleano la enciende o apaga — si tu cliente guarda el producto entero, mándalo explícito. Omitir kind conserva la clase actual en lo que la unidad nueva permita: un servicio en ZZ que pasa a KGM sigue siendo servicio, y uno que pasa a NIU se vuelve producto. Un combo deja de serlo solo con components: [] (ver «Combos»). Las opciones de precio (uses_*) tienen los mismos dos estados. category_ids es la lista completa: omitirla conserva las categorías, [] las quita todas y una lista las reemplaza — para sumar una, manda las actuales más la nueva.

curl -X PUT https://enbloques.com/api/v1/products/1a2b3c4d-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "unit_price": 38.00 }'

# El modificador omitida del array se desactiva; la que lleva id conserva su id.
curl -X PUT https://enbloques.com/api/v1/products/2b3c4d5e-0000-4000-8000-000000000002 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "modifiers": [
      { "id": "aaaa1111-0000-4000-8000-000000000001", "name": "Cuello camisero · Adulto", "code": "CAM-AD", "unit_price": 34.00 },
      { "id": "aaaa1111-0000-4000-8000-000000000002", "name": "Cuello rib · Adulto",      "code": "RIB-AD", "unit_price": 28.00 }
    ]
  }'

Borrado suave: marca el producto como inactivo (active: false) y responde 200 con el producto actualizado. Deja de aparecer en listados y de poder usarse en emisiones; el historial no se toca. Reactívalo con PUT { "active": true }.

Crea un cliente en el directorio. name es lo único obligatorio. Sin número se guarda como tipo "0" y doc_number null (ficha para nota de venta o cotización) — y esas fichas nunca chocan: cada POST sin número crea una nueva. Un tipo sin su número, un número sin su tipo o un "0" con número son 400. Si ya existe uno con el mismo doc_type + doc_number, nombre, email, teléfono y dirección se sobrescriben con lo enviado (responde 201 igualmente). custom_fields es la excepción: ausente se preserva lo guardado; presente se valida contra las definiciones activas de tu empresa (Configuración → Campos) y reemplaza el objeto completo. Nota: emitir un documento con datos de cliente en línea también lo registra/actualiza — y nunca toca los campos personalizados.

curl -X POST https://enbloques.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "doc_type": "6", "doc_number": "20512345678", "name": "ACME PERU S.A.C.", "email": "compras@acme.pe" }'

{
  "id": "7a8b9c0d-0000-4000-8000-000000000002",
  "doc_type": "6",
  "doc_number": "20512345678",
  "name": "ACME PERU S.A.C.",
  "nickname": "ACME",
  "email": "compras@acme.pe",
  "phone": "987654321",
  "address": null,
  "custom_fields": { "segmento": "Corporativo", "vip": true },
  "agreement_id": "3c4d5e6f-0000-4000-8000-000000000009",
  "created_at": "2026-06-09T15:10:00.000Z"
}

Lista o busca clientes, ordenados por nombre.

{ "data": [ { "id": "…", "doc_type": "6", "doc_number": "20512345678", "name": "ACME PERU S.A.C.", … } ],
  "page": 1, "per_page": 50, "total": 1 }

Un cliente por id, con la misma forma que la respuesta del POST (incluye phone y custom_fields).

Edita la ficha. Parche parcial: lo ausente no se toca; null limpia apodo, email, teléfono o dirección. custom_fields presente se valida y reemplaza el objeto completo (igual que en el POST).

doc_type + doc_number son una puerta de un solo sentido: se mandan juntos para agregarle documento a una ficha que no lo tiene (la que se creó solo con nombre), nunca para cambiar uno ya puesto. Ese par es la clave del directorio, y reescribirlo mudaría a otra persona las ventas ya hechas — un documento mal tipeado se arregla dando de alta otra ficha. Agregarlo no le quita su historial: las ventas que hizo sin documento siguen siendo suyas, y los comprobantes ya emitidos no se reescriben (su copia congelada sigue diciendo SIN DOCUMENTO).

curl -X PATCH https://enbloques.com/api/v1/customers/7a8b9c0d-… \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "987654321", "custom_fields": { "segmento": "Retail", "vip": false } }'

curl -X PATCH https://enbloques.com/api/v1/customers/7a8b9c0d-… \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "doc_type": "1", "doc_number": "12345678" }'

Borrado duro: saca al cliente del directorio y responde { "deleted": true, "id": "…" }. No se puede deshacer — a diferencia de los productos, que solo se desactivan. Lo que es solo del cliente se borra con él: sus medidas de la vista (ópticas) y su etapa e interacciones del CRM. Todo lo demás se queda y solo pierde el enlace vivo: los comprobantes, cotizaciones, notas de venta y reservas guardan su propia copia de los datos del cliente, y las ventas registradas, cuentas por cobrar, envíos, órdenes de trabajo y cuentas del mostrador quedan como están. Si vuelves a emitir a ese documento, el cliente se crea de nuevo.

Las sucursales activas del acceso de quien creó el token, cada una con sus cajas activas, en el orden de Configuración. Sirve para elegir branch_id o cash_register_id al emitir. branch_access es all si esa persona trabaja en todas las sucursales (una venta sin ninguno de los dos campos queda como siempre) y some si su acceso está restringido (con varias sucursales, la emisión exige uno de los dos). Las sucursales y cajas desactivadas no se listan. Un token con solo documents:write emite igual, pero para listarlas necesita documents:read.

{
  "branch_access": "some",
  "data": [
    { "id": "…uuid…", "name": "Miraflores", "address": "Av. Larco 123",
      "cash_registers": [ { "id": "…uuid…", "name": "Caja 1" } ] }
  ]
}

address es null si la sucursal no tiene dirección.

Los RUC del negocio, el principal primero: el catálogo de issuer_ruc para emitir. Nunca expone credenciales. Un negocio de un solo RUC lista su principal con issuer_mode: "single".

{
  "issuer_mode": "register",
  "can_choose": false,
  "data": [
    { "ruc": "20123456789", "razon_social": "MI EMPRESA S.A.C.", "is_primary": true,
      "active": true, "ready": true, "nuevo_rus": false, "establishment_branch_id": null },
    { "ruc": "10456789012", "razon_social": "ANA PEREZ LOPEZ", "is_primary": false,
      "active": true, "ready": true, "nuevo_rus": true, "establishment_branch_id": "…uuid…" }
  ]
}

• issuer_mode: de dónde sale el RUC por defecto de cada venta (single, sale, branch o register; ver Con qué RUC sale la venta). Con register, manda cash_register_id en cada venta.
• can_choose: si quien llama puede mandar un issuer_ruc distinto del por defecto (issuers:choose).
• ready: conectado al PSE y, si es un RUC adicional, con su «Autorizo PSE» hecho. Un RUC que no está active o no está ready no vende.
• nuevo_rus: solo boletas, y solo en establishment_branch_id cuando lo tiene.

Series de numeración disponibles por tipo de documento y el próximo correlativo de cada una. Cada serie incluye su owner (company / branch / register): el dueño decide qué serie se elige al emitir desde una caja. Solo lista las series que el token puede usar: las de empresa siempre; las de una sucursal o caja, solo si esa sucursal está en el acceso de quien lo creó. issuer_ruc es el RUC que numera con esa serie (SUNAT numera por RUC: con varios, dos series pueden tener el mismo código); null en las de nota de venta, que no es fiscal.

{
  "data": [
    { "type": "factura", "doc_type": "01", "code": "F001", "issuer_ruc": "20123456789",
      "next_number": 43, "active": true, "owner": "company", "branch_id": null, "cash_register_id": null },
    { "type": "boleta",  "doc_type": "03", "code": "B002", "issuer_ruc": "20123456789",
      "next_number": 118, "active": true, "owner": "register", "branch_id": null, "cash_register_id": "…uuid…" }
  ]
}

Consumo del mes en curso (calendario America/Lima) contra el límite del plan.

Es un número de toda la empresa que no se parte por sucursal: solo lo ve un token cuyo creador tiene acceso a todas las sucursales (el propietario o alguien con «todas»). Si el creador tiene acceso a solo algunas, responde 403 requires_all_branches — y lo mismo en el siguiente request si se lo restringen después, sin tocar el token.

{
  "plan": "pro",
  "planStatus": "active",
  "used": 137,
  "limit": 3000,
  "remaining": 2863,
  "periodStart": "2026-06-01T05:00:00.000Z"
}

Perfil público de la empresa autenticada (nunca expone credenciales). Con varios RUC, la identidad fiscal (ruc, domicilio, environment) es la del RUC principal; los demás están en GET /issuers.

{
  "id": "c0a80001-0000-4000-8000-000000000003",
  "ruc": "20123456789",
  "razon_social": "MI EMPRESA S.A.C.",
  "email": "facturacion@miempresa.pe",
  "direccion": "Av. Arequipa 1234, Lince",
  "ubigeo": "150116",
  "distrito": "Lince",
  "provincia": "Lima",
  "departamento": "Lima",
  "environment": "produccion",
  "plan": "pro",
  "plan_status": "active",
  "pdf_template": "moderna",
  "email_enabled": true,
  "created_at": "2026-01-15T14:00:00.000Z",
  "igv_rate": "0.180000",
  "series_mode": "company",
  "can_emit": true,
  "modules": ["catalogo", "clientes", "cotizaciones", "finanzas"],
  "membership": null
}

Sirve además de arranque del cliente: igv_rate es la tasa IGV+IPM efectiva de esta empresa (úsala para previsualizar totales, nunca un 0.18 fijo), series_mode dice a qué nivel viven las series (company, per_branch o per_register) y modules lista los módulos activos. membership trae { role, capabilities } solo en llamadas con sesión; con un token sk_live_… es null, porque un token tiene scopes y no rol.

ruc puede ser null y can_emit false: un negocio que todavía no se formalizó existe, vende y responde acá, pero no puede emitir. Mira can_emit antes de llamar a POST /api/v1/documents — si no, responde 409 company_not_ready. Pasa a true cuando su dueño conecta el RUC desde la aplicación, y nunca vuelve atrás.