Peru Invoices (CPE factura/boleta electrónica, SUNAT)

Official3 toolsLive

by junter1989k-ai · JavaScript

Peru CPE invoices for AI agents - issue, query, void facturas/boletas via SUNAT (2 backends).

Topics

ai-agentscpee-invoiceinvoicingmcpmcp-serverperusunatai-agentclaudeinvoicewishpool

Captured live from the server via tools/list.

create_invoice

Issue a Peru electronic CPE (comprobante de pago electrónico) — FACTURA (B2B, buyer RUC) or BOLETA (B2C consumer) — declared to SUNAT. Two backends (auto-selected from your credential header, or force with "provider"): NUBEFACT (headers x-nubefact-ruta = your unique full RUTA URL e.g. https://api.nubefact.com/api/v1/<hash>, AND x-nubefact-token = your account TOKEN; free DEMO at www.nubefact.com) or APISUNAT (PSE cloud; headers x-apisunat-persona-id + x-apisunat-persona-token + x-apisunat-ruc = your 11-digit issuer RUC; free self-signup at apisunat.com with a DEV persona for testing). Both keep your SUNAT credentials in your own provider account; this server forwards them per-request and stores nothing. The same credentials switch to production at the account level, so this server reports mode "nubefact-account"/"apisunat-account" honestly rather than guessing demo vs production. ⚠️ NUMBERING IS MERCHANT-MANAGED: this server is stateless and does NOT track sequences — YOU must supply "serie" (e.g. F001 for facturas, B001 for boletas) and the next sequential "numero" yourself; reusing a numero is rejected by SUNAT, skipping one leaves a gap. Give item prices WITH IGV included (precio_unitario) — this server computes valor_unitario, subtotal, IGV (18%) and totals for you.

Parameters13

provider	string	optional	Optional. Which backend OSE/PSE to issue through. Omit to auto-detect from your credential header (x-nubefact-ruta -> nubefact; x-apisunat-persona-id -> apisunat; default nubefact).
comprobante_type	string	required	factura = B2B invoice (buyer must have an 11-digit RUC); boleta = B2C consumer receipt (buyer DNI or none). Determines the tipo_de_comprobante and the required serie prefix (F.../B...).
serie	string	required	Document series, exactly 4 chars. FACTURA starts with F (e.g. F001); BOLETA starts with B (e.g. B001). Merchant-defined; must exist in your Nubefact account.
numero	integer	required	Sequential correlative number YOU manage (this server is stateless and does not track it). No leading zeros; 1 to 8 digits. Reusing a numero is rejected by SUNAT.
customer_document_type	string	optional	Buyer document type. RUC (11 digits) is REQUIRED for factura. DNI (8 digits) is typical for boleta. Defaults: factura->RUC, boleta->DNI.
customer_document_number	string	required	Buyer RUC (11 digits) or DNI (8 digits). For a factura this must be a valid 11-digit RUC.
customer_name	string	required	Buyer legal name / full name (razón social o nombre completo).
customer_address	string	optional	Buyer address (dirección). Recommended for factura; optional for boleta.
customer_email	string	optional	Optional buyer email — Nubefact emails the CPE to the buyer when provided.
items	array	required	Line items. Each price is the UNIT price INCLUDING IGV in PEN (soles); this server derives the untaxed value, IGV and totals.
igv_percent	number	optional	IGV rate percent. Default 18 (Peru standard). Only change if you know the item is under a special rate.
sunat_transaction	integer	optional	SUNAT transaction type (sunat_transaction). Default 1 (VENTA INTERNA). Other codes are for special operations (exportación, detracción, etc.).
fecha_de_emision	string	optional	Optional emission date DD-MM-AAAA. Defaults to today (America/Lima). SUNAT expects the current date.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "nubefact",
        "apisunat"
      ],
      "description": "Optional. Which backend OSE/PSE to issue through. Omit to auto-detect from your credential header (x-nubefact-ruta -> nubefact; x-apisunat-persona-id -> apisunat; default nubefact)."
    },
    "comprobante_type": {
      "type": "string",
      "enum": [
        "factura",
        "boleta"
      ],
      "description": "factura = B2B invoice (buyer must have an 11-digit RUC); boleta = B2C consumer receipt (buyer DNI or none). Determines the tipo_de_comprobante and the required serie prefix (F.../B...)."
    },
    "serie": {
      "type": "string",
      "description": "Document series, exactly 4 chars. FACTURA starts with F (e.g. F001); BOLETA starts with B (e.g. B001). Merchant-defined; must exist in your Nubefact account."
    },
    "numero": {
      "type": "integer",
      "minimum": 1,
      "description": "Sequential correlative number YOU manage (this server is stateless and does not track it). No leading zeros; 1 to 8 digits. Reusing a numero is rejected by SUNAT."
    },
    "customer_document_type": {
      "type": "string",
      "enum": [
        "RUC",
        "DNI"
      ],
      "description": "Buyer document type. RUC (11 digits) is REQUIRED for factura. DNI (8 digits) is typical for boleta. Defaults: factura->RUC, boleta->DNI."
    },
    "customer_document_number": {
      "type": "string",
      "description": "Buyer RUC (11 digits) or DNI (8 digits). For a factura this must be a valid 11-digit RUC."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer legal name / full name (razón social o nombre completo)."
    },
    "customer_address": {
      "type": "string",
      "description": "Buyer address (dirección). Recommended for factura; optional for boleta."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email — Nubefact emails the CPE to the buyer when provided."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each price is the UNIT price INCLUDING IGV in PEN (soles); this server derives the untaxed value, IGV and totals.",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Product/service description (descripción)."
          },
          "price": {
            "type": "number",
            "description": "Unit price INCLUDING 18% IGV, in PEN (soles)."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity (cantidad). Default 1."
          },
          "unit": {
            "type": "string",
            "enum": [
              "product",
              "service"
            ],
            "description": "product -> unidad_de_medida NIU, service -> ZZ. Default product."
          },
          "code": {
            "type": "string",
            "description": "Optional internal product/service code (codigo)."
          }
        },
        "required": [
          "description",
          "price"
        ]
      }
    },
    "igv_percent": {
      "type": "number",
      "description": "IGV rate percent. Default 18 (Peru standard). Only change if you know the item is under a special rate."
    },
    "sunat_transaction": {
      "type": "integer",
      "description": "SUNAT transaction type (sunat_transaction). Default 1 (VENTA INTERNA). Other codes are for special operations (exportación, detracción, etc.)."
    },
    "fecha_de_emision": {
      "type": "string",
      "description": "Optional emission date DD-MM-AAAA. Defaults to today (America/Lima). SUNAT expects the current date."
    }
  },
  "required": [
    "comprobante_type",
    "serie",
    "numero",
    "customer_document_number",
    "customer_name",
    "items"
  ]
}

query_invoice

Check a Peru CPE previously issued (consultar_comprobante) by its identity: comprobante_type + serie + numero (Nubefact/SUNAT identify documents by these, not by an opaque id). Status values: ACCEPTED (aceptada_por_sunat=true), PENDING (not yet sent/processing), REJECTED (SUNAT returned an error — see sunat_description). Also returns anulado (true if voided) and the PDF/XML/CDR links. Safe to call anytime.

Parameters4

provider	string	optional	Optional. Backend to query; omit to auto-detect from your credential header.
comprobante_type	string	required	The document type used when it was created.
serie	string	required	The series (e.g. F001 / B001).
numero	integer	required	The correlative number.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "nubefact",
        "apisunat"
      ],
      "description": "Optional. Backend to query; omit to auto-detect from your credential header."
    },
    "comprobante_type": {
      "type": "string",
      "enum": [
        "factura",
        "boleta"
      ],
      "description": "The document type used when it was created."
    },
    "serie": {
      "type": "string",
      "description": "The series (e.g. F001 / B001)."
    },
    "numero": {
      "type": "integer",
      "minimum": 1,
      "description": "The correlative number."
    }
  },
  "required": [
    "comprobante_type",
    "serie",
    "numero"
  ]
}

cancel_invoice

Void a Peru CPE at SUNAT (generar_anulacion — a comunicación de baja). Identified by comprobante_type + serie + numero, plus a free-text motivo (reason, e.g. "ERROR DEL SISTEMA"). SUNAT processes voids asynchronously via a ticket, so status is usually PENDING right after — call query_invoice later to confirm the document shows anulado=true. Note: for value corrections you normally issue a nota de crédito instead of a full void (notas not yet exposed by this server).

Parameters5

provider	string	optional	Optional. Backend to void through; omit to auto-detect from your credential header.
comprobante_type	string	required	The document type to void.
serie	string	required	The series (e.g. F001 / B001).
numero	integer	required	The correlative number to void.
motivo	string	optional	Reason for the void (motivo), 3 to 100 chars, e.g. "ERROR DEL SISTEMA". Default "ERROR DEL SISTEMA".

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "nubefact",
        "apisunat"
      ],
      "description": "Optional. Backend to void through; omit to auto-detect from your credential header."
    },
    "comprobante_type": {
      "type": "string",
      "enum": [
        "factura",
        "boleta"
      ],
      "description": "The document type to void."
    },
    "serie": {
      "type": "string",
      "description": "The series (e.g. F001 / B001)."
    },
    "numero": {
      "type": "integer",
      "minimum": 1,
      "description": "The correlative number to void."
    },
    "motivo": {
      "type": "string",
      "description": "Reason for the void (motivo), 3 to 100 chars, e.g. \"ERROR DEL SISTEMA\". Default \"ERROR DEL SISTEMA\"."
    }
  },
  "required": [
    "comprobante_type",
    "serie",
    "numero"
  ]
}

README.md5 KBView on GitHub

Peru Invoice MCP 🇵🇪 — How can my AI agent issue a factura o boleta electrónica in Peru?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "peru-invoice": {
      "type": "http",
      "url": "https://inv-pe.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/peru-invoice-mcp && cd peru-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent issue Peru electronic CPE (comprobante de pago electrónico — factura for B2B, boleta for consumers), declared to SUNAT. Aggregation layer: two interchangeable OSE/PSE backends — Nubefact and APISUNAT (PSE cloud) — behind the same tools. Stateless, bring-your-own credentials, never stores anything.

Live endpoint: https://inv-pe.wishpool.app/mcp · Registry: app.wishpool/peru-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "peru-invoice": {
      "type": "http",
      "url": "https://inv-pe.wishpool.app/mcp",
      "headers": {
        "x-nubefact-ruta": "https://api.nubefact.com/api/v1/<your-hash>",
        "x-nubefact-token": "<your-token>"
      }
    }
  }
}

A free DEMO account at nubefact.com gives you both a RUTA and a TOKEN (menu Api-Integración). The same credentials switch to production at the account level (numbering resets on go-live), so results report mode: "nubefact-account" honestly — verify demo vs production in your Nubefact dashboard.

Or use APISUNAT (second backend)

Prefer APISUNAT? Send its headers instead — the server auto-selects the backend from whichever credential you send (or force it with the tool's optional provider field: "nubefact" / "apisunat"):

json

"headers": {
  "x-apisunat-persona-id": "<your-persona-id>",
  "x-apisunat-persona-token": "<your-persona-token>",
  "x-apisunat-ruc": "<your-11-digit-RUC>"
}

Free self-signup at apisunat.com; a DEV persona lets you test without sending to SUNAT before switching the persona to production (mode: "apisunat-account"). APISUNAT signs and sends your CPE with your persona's certificate (PSE model); this server only forwards the credentials.

Tools

Tool	What it does
`create_invoice`	Issue a factura (buyer 11-digit RUC) or boleta (consumer DNI/none). You supply `serie` (F001/B001) and the next `numero`; item prices go in including IGV, and this layer computes `valor_unitario`, `subtotal`, IGV 18% and totals. Returns the SUNAT link + PDF/XML.
`query_invoice`	Status check by `comprobante_type` + `serie` + `numero`: `ACCEPTED` / `PENDING` / `REJECTED`, plus `anulado` and PDF/XML/CDR links.
`cancel_invoice`	Void (anular — comunicación de baja) a CPE at SUNAT with a `motivo`. Asynchronous: confirm later with `query_invoice`.

⚠️ Numbering is merchant-managed. This server is stateless and does not track sequences — the caller supplies serie and the next numero. Reusing a numero is rejected by SUNAT; skipping one leaves a gap.

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The cap applies to the invoice total in PEN.

Develop

bash

node test/serve.js   # local server on :3229
node test/e2e.js     # protocol + validation + IGV math + fake-cred live probes

Safety

Pure stateless translation layer. The SUNAT certification burden sits with the chosen backend (Nubefact or APISUNAT, OSE/PSE); credentials travel per-request in headers, nothing is stored. Privacy policy.

Sister servers

Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included. Invoice family live: Mexico CFDI 4.0 (inv-mx.wishpool.app). More invoice countries coming: Brazil NF-e · Chile DTE · Colombia · India GST · Poland KSeF · Italy SdI.

MIT licensed.

Install

Tools (3)

create_invoicequery_invoicecancel_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-pe.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "peru-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-pe.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.