Flashfact API

Introducción

Con el plan API no operas desde el panel: emites y consultas comprobantes llamando a esta API. Cada empresa (RUC) tiene su propio par de claves y su propio certificado digital. Qué comprobantes incluye tu plan está en Plan, límites y términos.

La API tiene dos direcciones. api.flashfact.pe emite y consulta comprobantes y va firmada con tu Access Key y tu Secret. app-api.flashfact.pe sirve para dar de alta empresas y subir su certificado, y usa la sesión del panel.

Formato de las respuestas

• JSON con codificación UTF-8. Un recurso viene en { "data": … }; un listado añade "meta": { total, page, perPage }.
• Los comprobantes usan nombres en camelCase y en español (numDocumentoAdquirente). Clientes, sucursales y la parte de cuenta usan snake_case (id_type).
• Los id son números enteros. Fechas en YYYY-MM-DD; marcas de tiempo en ISO 8601 UTC.
• Los listados aceptan page y perPage; si no los envías, 1 y 20.

Primeros pasos

De cero a tu primer comprobante aceptado por SUNAT, en cuatro pasos.

1. Agrega tu empresa y guarda las credenciales

   Desde el panel con el botón Agregar empresa, o con POST /v1/settings/companies. Recibes el Access Key ID y el Secret, que se muestra una sola vez. Cada RUC tiene su propio par.

2. Sube el certificado digital y el usuario SOL

   Para emitir en producción necesitas el certificado .pfx o .p12 de la empresa y un usuario SOL secundario. Súbelos desde el panel o con POST /v1/settings/companies/{external_id}/certificate. Sin ellos el envío a SUNAT falla.

3. Firma y emite una boleta

   Elige serie y correlativo: la API no los asigna, y tú llevas la numeración. Este ejemplo emite la boleta B001-00000123.

   curlNode.jsPython

   bash

   API_KEY_ID="WISNA_..."
   API_SECRET="..."
   REQ_PATH="/v1/invoices"          # solo la ruta: sin dominio ni query string
   TIMESTAMP=$(date +%s)
   BODY='{"tipoDocumento":"03","tipoOperacion":"0101","serie":"B001","correlativo":"00000123","fechaEmision":"2026-10-11","moneda":"PEN","tipoDocumentoAdquirente":"1","numDocumentoAdquirente":"12345678","razonSocialAdquirente":"JUAN PEREZ","totalImpuestos":18.00,"totalValorVenta":100.00,"totalPrecioVenta":118.00,"importeTotal":118.00,"baseImponibleIGV":100.00,"totalIGV":18.00,"items":[{"numeroItem":1,"unidadMedida":"NIU","cantidad":2,"descripcion":"Polo de algodón","valorUnitario":50.00,"precioUnitario":59.00,"valorVenta":100.00,"afectacionIGV":"10","igv":18.00,"totalImpuestosItem":18.00}]}'
   
   BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
   SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$REQ_PATH" "$BODY_HASH" \
     | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')
   
   curl -X POST "https://api.flashfact.pe$REQ_PATH" \
     -H "X-Api-Key: $API_KEY_ID" \
     -H "X-Timestamp: $TIMESTAMP" \
     -H "X-Signature: $SIGNATURE" \
     -H "Content-Type: application/json" \
     -d "$BODY"

4. Consulta el resultado

   La respuesta del paso anterior trae estado: "DRAFT": el comprobante quedó en cola. Pide GET /v1/invoices/{id} hasta que pase a ACCEPTED o REJECTED.

   Aceptado

   json

   {
     "data": {
       "id": 1042,
       "serie": "B001",
       "correlativo": "00000123",
       "estado": "ACCEPTED",
       "codigoRespuesta": "0",
       "descripcionRespuesta": "La Boleta de Venta numero B001-00000123, ha sido aceptada",
       "pdfUrl": "https://…"
     }
   }

Autenticación

Cada request a api.flashfact.pe va firmado con el Access Key ID y el Secret de la empresa. No hay tokens que renovar: la firma se calcula en cada llamada.

Cómo firmar

Arma este mensaje, con saltos de línea (\n) entre sus cuatro partes y sin salto al final, y fírmalo con tu Secret:

{timestamp}
{MÉTODO_HTTP}
{ruta_sin_query_string}
{sha256_hex_del_body}

• El método va en mayúsculas: POST, GET, DELETE.
• La ruta es solo el path (/v1/invoices/1042): sin dominio y sin query string.
• El hash es el SHA-256 en hexadecimal de los bytes exactos del body. Sin body (un GET), usa el hash de la cadena vacía: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
• El resultado es el HMAC-SHA256 de ese mensaje con tu Secret como clave, en hexadecimal.

Qué cubre la firma

La firma protege el método, la ruta y el body. Los parámetros de query (los filtros de un listado) no entran en ella, así que no los uses para nada sensible.

Rechazos de autenticación

• 401 UNAUTHORIZED: faltan headers, el timestamp está fuera de la ventana, la key no existe o la firma no coincide.
• 403 FORBIDDEN: la key tiene una lista de IPs permitidas y el request viene de otra. Pídela a soporte si la necesitas.

Conceptos clave

La emisión es asíncrona: estados

Crear un comprobante responde de inmediato con estado: "DRAFT". El envío a SUNAT ocurre después y el resultado se lee con un GET. Estos son los estados:

Series y correlativos

Los eliges tú en cada emisión. La serie debe estar habilitada en SUNAT para tu empresa y el correlativo debe ser único dentro de ella. Facturas y boletas se numeran por serie (F001, B001); notas, retenciones, percepciones y guías tienen su propio prefijo.

Reintentos seguros

No existe un header de idempotencia: la clave es la serie y el correlativo. Si reenvías una factura, boleta o nota que ya existe, la API devuelve el documento original con 200 en lugar de duplicarlo. Retenciones, percepciones y guías no tienen esa protección.

Moneda extranjera y tipo de cambio

Si la moneda no es PEN puedes enviar tipoCambio. Si no lo envías, usamos el tipo de cambio SBS que corresponde por norma y lo guardamos con el comprobante. Un valor distinto al SBS se acepta y queda registrado como manual; si se aparta más de 10 %, debes confirmarlo con confirmarTipoCambio: true. La respuesta de creación trae tiposCambio con el valor usado.

Archivos del comprobante

El XML, el CDR y el PDF no tienen endpoint propio: llegan como enlaces firmados en xmlUrl, cdrUrl y pdfUrl, válidos por 15 minutos. Para un enlace más largo usa GET /v1/invoices/{id}/pdf-link (7 días).

Plan, límites y términos de uso

Este es un resumen para quien integra. Lo que vale es el texto completo de los Términos de uso, la Política de privacidad y la Política de cambios y devoluciones.

Qué incluye el plan API

El plan API no incluye el panel web. Una misma cuenta puede manejar varias empresas (RUC) y todas comparten el mismo límite mensual. Términos, sección 3.

Tu límite mensual

• Solo se descuentan las facturas, boletas y notas de crédito y débito que la SUNAT acepte. No se descuentan los rechazados, las guías, las retenciones ni las percepciones.
• Anular un comprobante no devuelve el uso de tu límite del mes.
• Al pasarte puedes seguir emitiendo hasta un 50 % más; esos comprobantes extra se cobran aparte, después de que termina el mes. Al llegar a ese tope no podrás emitir más hasta el mes siguiente o hasta cambiar de plan. Puedes desactivar el extra desde la configuración de tu plan: entonces el bloqueo es en tu límite exacto. Sección 7.

Lo que pones de tu parte

• Un certificado digital vigente, emitido a nombre de tu empresa (.pfx o .p12). Si vence no podrás emitir hasta subir uno nuevo.
• Un usuario SOL secundario. Nunca nos des tu clave SOL principal: no te la pediremos.
• La exactitud de los datos, precios e impuestos de cada comprobante. Nosotros enviamos lo que tú envías. Sección 4.
• Descargar y conservar tus comprobantes: la obligación de guardarlos por el plazo legal es tuya. Sección 12.

Tus claves de conexión

Son personales: todo lo que se haga con ellas se considera hecho por ti. Se muestran una sola vez; si las pierdes tendrás que crear unas nuevas. Si crees que alguien accedió sin permiso, revócalas de inmediato y avísanos. Sección 5.

Uso correcto del servicio

No está permitido emitir comprobantes falsos o de operaciones que no existieron, intentar entrar a cuentas ajenas, copiar, revender o ceder el acceso, ni sobrecargar el sistema con envíos masivos que afecten a otros clientes. Si se incumple, podemos limitar, pausar o cerrar la cuenta. Sección 14.

Pagos pendientes, cancelación y disponibilidad

• Si un pago queda pendiente más de 7 días, la cuenta se pausa hasta que lo pagues. No se borran tus datos. Sección 10.
• Tras cancelar conservamos tus datos 30 días; pasado ese plazo eliminamos tu certificado, tus credenciales SOL y tus llaves de acceso. Descarga tus comprobantes antes. Sección 11.
• Trabajamos para que el servicio esté siempre disponible, pero no podemos garantizar que funcione sin interrupciones: pueden ocurrir mantenimientos o fallas de la SUNAT y de terceros. Sección 15.

Buenas prácticas

Límites técnicos

• El body de un request puede pesar hasta 4 MB.
• Los enlaces xmlUrl, cdrUrl y pdfUrl caducan a los 15 minutos; el de pdf-link, a los 7 días.
• Una factura o boleta solo se puede anular dentro de los 7 días posteriores a su emisión.
• El certificado digital que subes puede pesar hasta 512 KB y debe ser .pfx o .p12.

No hay webhooks: consulta el estado

La API no te avisa cuando SUNAT responde. Después de crear un documento consúltalo con un GET y espacia las consultas de forma creciente (por ejemplo 2, 4 y 8 segundos) en vez de repetirlas sin pausa. Deja de consultar cuando el estado sea ACCEPTED, REJECTED o FAILED.

Reintentos

• Si un POST se corta sin respuesta, reenvíalo con la misma serie y correlativo: en facturas, boletas y notas recibirás el documento original en lugar de un duplicado.
• Ante un 503 con Retry-After, espera ese tiempo antes de reintentar.
• Un 422 no se arregla reintentando: corrige los campos que indica details.
• Si el documento quedó en FAILED, no reenvíes uno nuevo con otro correlativo: contacta a soporte con el id.

Guarda lo que necesitas

Conserva el id, la serie y el correlativo de cada documento. Descarga el XML, el CDR y el PDF cuando el estado sea ACCEPTED y guárdalos en tu sistema; no guardes los enlaces firmados, porque caducan.

Errores

Todos los errores de la API siguen el mismo formato:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "se encontraron errores de validación",
    "details": [
      { "field": "serie", "code": "1001", "message": "la serie es obligatoria" }
    ]
  }
}

details solo aparece en errores de validación.

Un 409 con BAD_REQUEST también aparece al reenviar un comprobante que no está en DRAFT o cuando una serie y correlativo ya existen y no se puede devolver el original.

Modelos de respuesta

Los ejemplos de cada endpoint muestran solo algunos campos. Aquí está la estructura completa. Tu cliente debe ignorar los campos que no conozca: podemos añadir campos nuevos dentro de v1 sin avisar.

Catálogos

Varios campos reciben códigos de los catálogos oficiales de la SUNAT (Anexo 8 de las reglas de validación, actualizadas al 24/04/2026). Cuando la API acepta solo una parte de un catálogo, la tabla lo indica en una columna aparte.