Emite comprobantes SUNAT con una llamada HTTP

Inicio rápido

Emitir un comprobante son tres llamadas: abrir una sesión con la Clave SOL del emisor, enviar la venta y, si lo necesitas, descargar el PDF para imprimirlo o enviarlo por WhatsApp.

1. Abre una sesiónPOST /v1/sessions

   Con el DNI y la Clave SOL del emisor. Recibes un token válido por 1 hora.

2. EmitePOST /v1/receipts

   Con la venta en JSON y un Idempotency-Key único. SUNAT asigna la serie y el número.

3. DescargaGET /v1/files

   El PDF o el XML del comprobante, en base64.

# 1. Sesión: guarda el token (vale 1 hora)
TOKEN=$(curl -s https://facturador.innobyte.pe/v1/sessions \
  -H "x-api-key: $FACTURADOR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"mode":"dni","dni":"45678901","password":"'"$CLAVE_SOL"'"}' | jq -r .accessToken)

# 2. Emitir una boleta
curl -s https://facturador.innobyte.pe/v1/receipts \
  -H "x-api-key: $FACTURADOR_API_KEY" \
  -H "authorization: Bearer $TOKEN" \
  -H "idempotency-key: venta-000123" \
  -H "content-type: application/json" \
  -d @boleta.json

# 3. Descargar el PDF
curl -s "https://facturador.innobyte.pe/v1/files?ruc=10456789012&codCpe=03&series=B001&number=1&date=2026-11-01&format=PDF" \
  -H "x-api-key: $FACTURADOR_API_KEY" \
  -H "authorization: Bearer $TOKEN" | jq -r .base64 | base64 -d > boleta.pdf

const BASE = 'https://facturador.innobyte.pe';
const apiKey = process.env.FACTURADOR_API_KEY;

// 1. Sesión
const session = await fetch(`${BASE}/v1/sessions`, {
  method: 'POST',
  headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
  body: JSON.stringify({ mode: 'dni', dni: '45678901', password: claveSol }),
}).then((r) => r.json());

// 2. Emitir
const res = await fetch(`${BASE}/v1/receipts`, {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    authorization: `Bearer ${session.accessToken}`,
    'idempotency-key': `venta-${venta.id}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify(boleta),
});
const { series, number } = await res.json(); // { series: 'B001', number: '1' }

Antes de empezar

Necesitas tres cosas:

• Una API key del Facturador. Se envía en el header x-api-key en todas las llamadas. Solo la usa tu backend: nunca la pongas en una app móvil ni en el navegador.
• La Clave SOL del emisor. Es el usuario y la contraseña con los que el emisor entra a SUNAT Operaciones en Línea. El Facturador la usa para abrir la sesión y no la guarda.
• Un RUC habilitado para emitir comprobantes electrónicos desde SEE-SOL. Puedes comprobarlo con condiciones de emisión.

Todas las peticiones y respuestas son JSON en UTF-8. Los montos van en soles como números decimales (2.5, no "2.50").

Autenticación

Hay dos credenciales, y cada una responde a una pregunta distinta:

Abrir una sesión

POST/v1/sessions

Requiere x-api-key.

{
  "accessToken": "eyJraWQiOiJhcGkuc3VuYXQuZ29iLnBlLmtpZDAwMSIs…",
  "tokenType": "JWT",
  "expiresIn": 3600
}

Reutiliza el token durante su hora de vida: abrir una sesión por cada venta es lento y multiplica los intentos de login contra SUNAT. Cuando cualquier llamada responda 401, abre una sesión nueva y repite la llamada.

Idempotencia: nunca emitir dos veces

Si una emisión se corta por un timeout, no sabes si SUNAT llegó a registrar el comprobante. Reintentar a ciegas podría crear una segunda boleta, real e imborrable. Por eso, todas las rutas de emisión exigen el header Idempotency-Key.

• Usa un valor único por venta y estable entre reintentos, por ejemplo el id de la venta en tu sistema: venta-000123. Admite hasta 128 caracteres.
• Si repites la petición con la misma key y el mismo body, recibes la respuesta original con el header Idempotent-Replayed: true, y no se emite nada nuevo.
• Las keys se recuerdan durante 7 días.

Qué responde un reintento

Si la emisión falla por una razón que garantiza que no se emitió nada (datos inválidos o rechazo de SUNAT), la key se libera y puedes reintentar con ella después de corregir el problema.

Fechas y montos

Fechas en hora de Perú

Las fechas se envían en ISO 8601. Si no indicas zona horaria, se interpretan en hora de Perú (UTC−5), igual que las muestra SUNAT:

Cómo se calculan los montos

Envías el valor unitario sin IGV (unitValue) y la cantidad. El Facturador calcula el resto con el mismo redondeo que SUNAT, a dos decimales:

importeVenta   = redondear(unitValue × quantity − discount)
igv            = redondear(importeVenta × igvRate / 100)      // solo si es "gravado"
precioUnitario = redondear(importeVenta × (1 + igvRate / 100) / quantity)
total          = suma de importeVenta + suma de igv

Ejemplo con IGV 18%: 2 unidades a S/ 2.50 dan un importe de 5.00, un IGV de 0.90 y un total de S/ 5.90. Un emisor del Nuevo RUS no cobra IGV: usa igvRate: 0, tipoOperacion: "0113" y líneas exonerado.

Errores

Todos los errores devuelven JSON con un mensaje en error. Los de validación incluyen la lista completa de problemas en issues, para que los corrijas de una sola vez:

{
  "error": "invalid comprobante: lines[0].quantity must be a number; customer.document must be a non-empty string",
  "issues": [
    "lines[0].quantity must be a number",
    "customer.document must be a non-empty string"
  ]
}

Reintentos

Una política simple y segura para las emisiones:

1. Genera el Idempotency-Key una vez por venta, antes del primer intento, y guárdalo con la venta.
2. Ante un error de red, 502, 504 o 429, reintenta con la misma key tras 2, 4 y 8 segundos.
3. Ante un 401, abre una sesión nueva y reintenta una vez con la misma key.
4. Ante un 400 o 422, no reintentes: muestra el error para corregir la venta.
5. Si llegas a un 409 incierto, marca la venta para revisión manual.

Configura en tu cliente HTTP un timeout de al menos 30 segundos para las emisiones: SUNAT a veces tarda.

Límites

Emitir una boleta

POST/v1/receipts

Requiere x-api-key, authorization e Idempotency-Key. Responde 201.

La boleta de venta (código 03) es el comprobante para consumidores finales. SUNAT asigna la serie y el número: no los envíes.

Parámetros de consulta

Body

Cada línea

{
  "solUser": "45678901",
  "issuer": { "document": "10456789012" },
  "customer": { "documentTypeCode": "-", "document": "-", "name": "VARIOS" },
  "currency": "PEN",
  "issueDate": "2026-11-01T09:30:00",
  "igvRate": 0,
  "tipoOperacion": "0113",
  "lines": [
    { "code": "PAN001", "description": "PAN FRANCES", "unitCode": "NIU", "itemTypeCode": "Z",
      "quantity": 10, "unitValue": 0.3, "affectation": "exonerado" },
    { "code": "PAN002", "description": "PAN DE YEMA", "unitCode": "NIU", "itemTypeCode": "Z",
      "quantity": 4, "unitValue": 0.5, "affectation": "exonerado" }
  ]
}

{
  "ruc": "10456789012",
  "kind": "receipt",
  "codCpe": "03",
  "series": "B001",
  "number": "1"
}

Reglas que se validan antes de enviar a SUNAT

• El cliente no puede ser el mismo emisor.
• Si el cliente tiene DNI, son 8 dígitos; si tiene RUC, son 11.
• Un cliente con carné de extranjería o pasaporte necesita nombre.
• La cantidad y el valor unitario son mayores que 0, y el valor es menor que 9 999 999 999.99.

Emitir una factura

POST/v1/invoices

Requiere x-api-key, authorization e Idempotency-Key. Responde 201.

La factura (código 01) usa el mismo body que la boleta, con estas diferencias:

• El cliente es siempre una empresa o negocio con RUC de 11 dígitos y nombre.
• Admite payment ({ "onCredit": true } para una venta al crédito) y dueDate (fecha de vencimiento).
• En régimen general o MYPE las líneas suelen ser gravado con igvRate: 18.

{
  "solUser": "45678901",
  "issuer": { "document": "20601234567" },
  "customer": { "document": "20509876543", "name": "DISTRIBUIDORA EL HORNO SAC" },
  "currency": "PEN",
  "issueDate": "2026-11-03T16:00:00",
  "igvRate": 18,
  "tipoOperacion": "0101",
  "payment": { "onCredit": false },
  "lines": [
    { "code": "HAR050", "description": "HARINA PREPARADA 50 KG", "unitCode": "NIU", "itemTypeCode": "Z",
      "quantity": 2, "unitValue": 2.5, "affectation": "gravado" }
  ]
}

Esta línea da un importe de S/ 5.00, un IGV de S/ 0.90 y un total de S/ 5.90.

Notas de crédito y débito

POST/v1/credit-notes

POST/v1/debit-notes

Requieren x-api-key, authorization e Idempotency-Key. Responden 201.

Una nota de crédito (07) reduce o anula el monto de un comprobante ya emitido; una nota de débito (08) lo aumenta, por ejemplo por intereses. Así se corrige un comprobante, porque no se pueden borrar.

{
  "solUser": "45678901",
  "issuer": { "document": "10456789012" },
  "reference": { "series": "B001", "number": "1", "comprobanteTypeCode": "03" },
  "reasonCode": "04",
  "reasonText": "Devolucion de producto",
  "issueDate": "2026-11-02T10:00:00",
  "amount": 1
}

Descargar el PDF o el XML

GET/v1/files

Requiere x-api-key y authorization.

{ "base64": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5n…", "fileType": "PDF" }

Buscar un cliente

GET/v1/parties?document=20509876543

Requiere x-api-key y authorization.

Devuelve el nombre y la ubicación de un DNI (8 dígitos) o un RUC (11) según SUNAT, para mostrarlos en tu caja antes de emitir. Responde 404 si SUNAT no conoce el documento.

{
  "document": "20509876543",
  "name": "DISTRIBUIDORA EL HORNO SAC",
  "address": { "ubigeoCode": "150103", "department": "LIMA", "province": "LIMA", "district": "ATE" }
}

Condiciones de emisión

GET/v1/emission-conditions?ruc=10456789012&comprobante=03

Requiere x-api-key y authorization.

Indica si el RUC puede emitir ese tipo de comprobante. Es la mejor forma de comprobar que la integración funciona sin emitir nada.

{
  "indValidoEmision": true,
  "indPrimeraEmision": true,
  "indEmisionIcbper": false,
  "indPermiteEmitirADni": false
}

Productos

GET/v1/products?ruc=10456789012

Requiere x-api-key y authorization.

El catálogo de productos que el emisor registró en SUNAT. Devuelve [] si está vacío.

Catálogos SUNAT

GET/v1/parameters?numParametro=1002

Requiere x-api-key y authorization.

Los catálogos vigentes que publica SUNAT: tipos de documento, monedas, unidades de medida, motivos de nota y otros. Sin numParametro devuelve el conjunto completo; con él, solo los códigos indicados, separados por comas.

[
  { "numParametro": "1002", "lstParam": [
    { "codParametro": "1", "desParametro": "DOCUMENTO NACIONAL DE IDENTIDAD", "estado": "1" },
    { "codParametro": "4", "desParametro": "CARNET DE EXTRANJERÍA", "estado": "1" },
    { "codParametro": "6", "desParametro": "REGISTRO ÚNICO DE CONTRIBUYENTES", "estado": "1" },
    { "codParametro": "7", "desParametro": "PASAPORTE", "estado": "1" }
  ] }
]

Códigos y catálogos

Cliente completo en JavaScript

Un cliente para Node.js 18 o superior que reutiliza la sesión, renueva el token ante un 401 y reintenta las emisiones de forma segura. Puedes copiarlo tal cual a tu backend.

const BASE = 'https://facturador.innobyte.pe';
const RETRYABLE = new Set([429, 502, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export class Facturador {
  constructor({ apiKey, dni, claveSol }) {
    this.apiKey = apiKey;
    this.credentials = { mode: 'dni', dni, password: claveSol };
    this.token = null;
    this.expiresAt = 0;
  }

  // Reutiliza el token hasta 5 minutos antes de que venza.
  async session() {
    if (this.token && Date.now() < this.expiresAt) return this.token;
    const res = await this.call('POST', '/v1/sessions', { body: this.credentials });
    this.token = res.accessToken;
    this.expiresAt = Date.now() + (res.expiresIn - 300) * 1000;
    return this.token;
  }

  // ventaId identifica la venta en tu sistema: se usa como Idempotency-Key.
  emitirBoleta(ventaId, boleta)  { return this.emitir('/v1/receipts', ventaId, boleta); }
  emitirFactura(ventaId, factura) { return this.emitir('/v1/invoices', ventaId, factura); }

  async emitir(path, ventaId, body) {
    const key = `venta-${ventaId}`;
    for (let intento = 0; ; intento++) {
      try {
        return await this.call('POST', path, { body, key, auth: true });
      } catch (err) {
        if (err.status === 401 && intento === 0) { this.token = null; continue; }
        const transitorio = !err.status || RETRYABLE.has(err.status);
        if (!transitorio || intento >= 3) throw err;  // 400, 409, 422: no reintentar
        await sleep(2000 * 2 ** intento);
      }
    }
  }

  async call(method, path, { body, key, auth } = {}) {
    const headers = { 'x-api-key': this.apiKey, 'content-type': 'application/json' };
    if (auth) headers.authorization = `Bearer ${await this.session()}`;
    if (key) headers['idempotency-key'] = key;
    const res = await fetch(BASE + path, {
      method, headers,
      body: body ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(35_000),
    });
    const data = await res.json();
    if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
    return data;
  }
}

// Uso
const facturador = new Facturador({ apiKey: process.env.FACTURADOR_API_KEY, dni: '45678901', claveSol });
const { series, number } = await facturador.emitirBoleta(venta.id, boleta);

Especificación OpenAPI

El contrato completo está en formato OpenAPI 3.1. Impórtalo en Postman, Insomnia o tu generador de clientes:

Descargar openapi.yaml