Ir al contenido
Facturalo

v3 — otrosCampos

Novedades Facturalo API v3: otrosCampos libres (Cajero, método de pago, mesa) en PDF/respuesta/webhook sin ir a SUNAT; wrapper documento, IGV automático, tokens duales.

Actualización

2026-11-10

Importar productos y reportes de ventas

  • NUEVO — Importar productos desde Excel o CSV: precio, categoría, marca y stock inicial con costo; actualiza por SKU o código de barras; validar para revisar antes.
  • NUEVO — Reporte de ventas: por día, producto, cajero y medio de pago, con ganancia según el kárdex y exportación a Excel. Permiso reportes.ver.
  • NUEVO — Los comprobantes emitidos desde la consola guardan qué usuario los emitió.
  • NUEVO — Más unidades de medida: kilo, gramo, litro, mililitro, galón, metro, metro cuadrado, docena, par, bolsa, botella, lata, rollo, hora y otras. Cantidades con decimales en el punto de venta.
  • NUEVO — Código de producto SUNAT por descripción, también en los SDKs (consultas.codigoProductoSunat) y en el MCP (find_sunat_product_code).
  • NUEVO — Verificar Clave SOL: prueba el usuario y la clave SOL con un login real en SUNAT y los guarda solo si son correctos. Máximo 5 intentos por minuto para no bloquear el usuario SOL.

Usuarios, roles y permisos

  • NUEVO — Usuarios y roles: el administrador general invita por correo y asigna roles con permisos que él define (Administrador, Cajero, Almacenero y Contador de inicio).
  • NUEVO — La API responde 403 SIN_PERMISO con el permiso que falta cuando el rol del usuario no alcanza. Las API keys sk_test_/sk_live_ mantienen acceso total.
  • NUEVO — Límites de usuarios, locales y cajas por plan.
  • NUEVO — Locales por usuario, precios del catálogo, PIN de supervisor (X-Facturalo-Autoriza), cierre ciego, costos ocultos y auditoría.

Cuentas por cobrar y por pagar

  • NUEVO — Cuentas por cobrar y por pagar: facturas, notas de venta y compras al crédito generan una partida por cuota; cobros y pagos parciales o totales, aplicados a la más antigua primero o donde indiques, con saldo a favor automático.
  • NUEVO — Resumen con antigüedad (por vencer, 1–30, 31–60, 61–90, +90 días) y estado de cuenta en JSON o PDF.
  • NUEVO — formaPago y cuotas en notas de venta y compras. Una nota de crédito rebaja las cuotas de su factura; anular o el rechazo de SUNAT las anula.
  • NUEVO — Cobros y pagos con caja entran o salen de la caja y cuentan en el arqueo (cobros y pagos en el reporte X/Z).

Cajas, punto de venta y notas de venta

  • NUEVO — Cajas: cajas por local con tres niveles de control (sin turnos, simple o con arqueo), turnos, medios de pago (Tabla 1 SUNAT), ingresos y retiros, y reportes X/Z en ticket o A4.
  • NUEVO — Al emitir, caja y pagos registran el cobro (pago mixto, vuelto). Una anulación o rechazo revierte el cobro solo. Ejemplo.
  • NUEVO — Notas de venta: documento interno que descuenta stock y se cobra en caja; se convierte en boleta o factura con notaVenta.
  • NUEVO — Categorías y marcas en el catálogo, con filtros en /productos y /productos/variantes (?explorar=1 para la cuadrícula del POS).

Compras

  • NUEVO — Compras: registra las facturas y boletas de tus proveedores; los ítems relacionados con un producto entran al stock (tipo 02) al costo sin IGV, con el documento del proveedor en el kárdex. Anular retira la mercadería.
  • NUEVO — Importación desde SUNAT: comprobantes recibidos del periodo (RCE) y su detalle con ítems, de cualquier sistema emisor, con la relación ítem → producto que se recuerda por proveedor.
  • NUEVO — Proveedores, creados solos al registrar compras.
  • NUEVO — Kárdex en Excel (formato=xlsx) y PDF (formato=pdf) con la cabecera del formato 13.1, además de CSV.

Actualización

2026-11-09

Productos, inventario y series

  • NUEVO — Productos y servicios: catálogo por empresa con variantes (talla, color…), SKU, código de barras, precio en soles y dólares y código SUNAT. En POST /documentos/enviar y cotizaciones, cada ítem acepta productoId o el SKU en codigo; lo que falta se completa del catálogo.
  • NUEVO — Inventario: stock por almacén y entorno, ingresos, salidas y transferencias con la tabla 12 de SUNAT, y kárdex valorizado (formato 13.1, promedio ponderado) en JSON o CSV. Facturas y boletas descuentan stock; notas de crédito lo devuelven; anulaciones y rechazos lo revierten.
  • NUEVO — Números de serie / IMEI opcionales por producto, con historial y garantía. Al vender, el ítem lleva series y la serie sale en el comprobante.
  • NUEVO — PLE de inventarios: TXT de los formatos 12.1 y 13.1 (RS 315-2018) listo para el PLE; resumen de inventario con valor por almacén, alertas y lo más vendido; codigoSunat (código de establecimiento anexo) en los establecimientos.

Cotizaciones y cuentas de pago

  • NUEVO — Cotizaciones: crea, edita, lista y descarga en PDF cotizaciones con validez en días (diasValidez), forma de pago, tiempo de entrega, términos y cuentas de pago. No van a SUNAT y no descuentan del cupo de tu plan.
  • NUEVO — GET /cotizaciones/{id}/comprobante devuelve el cuerpo listo para emitir. El campo opcional cotizacion en POST /documentos/enviar vincula el comprobante con la cotización (queda CONVERTIDA).
  • NUEVO — Cuentas de pago: cuentas bancarias (con CCI) y billeteras como Yape o Plin, por empresa. Se eligen en cada cotización y salen en su PDF.

Validar antes de emitir

  • NUEVO — POST /documentos/validar: valida una factura, boleta o nota con las reglas oficiales de validación de SUNAT sin emitirla. Devuelve todos los errores con el código que daría SUNAT. No usa el correlativo ni consume tu plan.
  • DOCS — El ejemplo de factura con retención usaba sunatTransaccion: 2001 (percepción) y SUNAT lo rechazaba con 3093. Ahora usa 0101: la retención no cambia el tipo de operación.
  • NUEVO — Request ID: toda respuesta trae X-Request-Id (req_…) y los errores también requestId en el cuerpo. Si envías tu propio X-Request-Id, vuelve en X-Correlation-Id.
  • NUEVO — GET /peticiones/{id} y GET /peticiones: qué pasó con una petición, el documento que creó y sus eventos (incluida la respuesta de SUNAT que llega después en cola). Retención: 30 días demo, 90 producción.
  • NUEVO — GET /empresa: la empresa y el entorno del token, su webhook y si la firma está lista para producción. Sin secretos.
  • MEJORA — POST /documentos/validar devuelve también totales e items calculados (gravada, IGV, total): sirven de vista previa antes de emitir.

Actualización

2026-11-08

Guías en demo validadas con las reglas de SUNAT

  • MEJORA — En demo (sk_test_) las guías de remisión remitente se validan con las reglas oficiales de validación de SUNAT. Una guía con errores responde RECHAZADA con el mismo código que daría SUNAT en producción (por ejemplo 2567 placa, 2573 licencia, 3373 código de producto). Antes la demo aceptaba la guía sin validarla. La guía transportista se incorporará más adelante.
  • MEJORA — numeroPlaca y numeroLicencia se normalizan: se quitan guiones y espacios y se pasan a mayúsculas (abc-123 → ABC123), como exige SUNAT. Aplica en demo y producción.
  • CORRECCIÓN — En la guía remitente, el RUC del emisor de los documentos relacionados (documentosRelacionados) es ahora el de tu empresa. Fuera de producción iba un RUC de pruebas antiguo y SUNAT respondía 3381.
  • DOCS — El ejemplo de placa pasa de ABC-123 a ABC123. Ver Guía remitente — transporte privado y Guía transportista.
  • CORRECCIÓN — Número ya usado en SUNAT por otro sistema (código 1033): la API, el webhook documento.sunat.respuesta y GET /documentos/{id} responden ahora el mismo estado, NO_ENVIADA. Antes la respuesta del envío decía RECHAZADA y la consulta NO_ENVIADA. Ver Estados.
  • MEJORA — Facturalo ya no reenvía un número que SUNAT respondió como informado (1032/1033): los reintentos automáticos solo consultan su estado. Reenviar o corregir ese comprobante responde 422 con la indicación de emitirlo con otro correlativo.
  • NUEVO — Evento documento.sunat.consulta en Eventos del documento: distingue una consulta del CDR de un envío a SUNAT.

Actualización

2026-10-31

Idempotencia, webhooks ×5 y status

  • NUEVO — Idempotencia en POST /documentos/enviar y POST /guias/enviar: header Idempotency-Key (24 h) y clave natural serie+correlativo+tipo. Guía: Idempotencia.
  • MEJORA — Entrega de webhooks con hasta 5 reintentos automáticos (backoff 30 s → 10 min). Mismo id de evento en todos los intentos. Detalle: Webhooks.
  • NUEVO — Página de estado pública: status.facturalo.pe (API, docs, web, webhooks, SUNAT Factura y Guía).
  • SDK — Node @facturalo-pe/node y PHP facturalo-pe/facturalo-php aceptan idempotencyKey / $idempotencyKey al enviar documentos y guías.

Actualización

2026-08-26

Nuevo

  • NUEVO — documento.otrosCampos

Campos libres opcionales solo locales: [{ "label": "Cajero", "value": "Guillermo" }, { "label": "Método de pago", "value": "Yape" }, { "label": "Mesa", "value": "12" }]. Se guardan en el invoice, aparecen en el PDF (A4 y ticket), se devuelven en la respuesta y en el webhook documento.sunat.respuesta. No se envían a SUNAT.

Lanzamiento inicial

2026-06-13

Nuevo en v3

  • NUEVO — Endpoint unificado /documentos/enviar — Facturas, boletas, notas de crédito y débito se emiten desde un único endpoint. El tipo de comprobante se determina por tipoComprobante en el payload.
  • NUEVO — Cálculo automático de IGV — Solo se envía precioUnitario y tipoIgv por ítem. La API calcula IGV, subtotales y totales automáticamente.
  • NUEVO — Dos tipos de token — user_sk_... para gestión de cuenta. sk_test_... / sk_live_... para operaciones de documentos. El entorno se detecta automáticamente del prefijo.
  • NUEVO — Modo asíncrono con webhook — Envía "webhook": true para recibir una respuesta inmediata EN_PROCESO y obtener el resultado SUNAT en la URL de webhook configurada.
  • NUEVO — Endpoint /guias/enviar — Guías de remisión remitente (transporte público y privado) y transportista desde un endpoint dedicado.
  • NUEVO — Respuesta estructurada unificada — Todas las respuestas exitosas siguen el esquema: { success, message, data: { estado, entorno, documento, sunat, enlaces } }.
  • NUEVO — Archivos públicos sin autenticación — Los enlaces /{id}.pdf, /{id}.ticket.pdf, /{id}.xml y /{id}.cdr son públicos — compartibles directamente con el cliente sin exponer tokens.
  • NUEVO — Historial de eventos por documento y guía — GET /documentos/{id}/eventos y GET /guias/{id}/eventos retornan el ciclo completo: recepción, generación de XML, envío a SUNAT, respuesta SUNAT y notificación webhook.
  • NUEVO — Gestión completa de webhooks — Endpoints para listar eventos activos, activar/desactivar por tipo, consultar webhooks enviados y reenviar webhooks fallidos manualmente.
  • NUEVO — SIRE — Ventas (RVIE) y Compras (RCE)

Integración completa con el Sistema Integrado de Registros Electrónicos de SUNAT. Consulta periodos, resúmenes y comprobantes, acepta propuestas, exporta y descarga reportes, y gestiona preliminares. Compras incluye además conciliación automática contra los registros de Facturalo.

Endpoints disponibles

  • POST — /documentos/enviar — Emitir factura, boleta, nota de crédito o débito
  • POST — /guias/enviar — Emitir guía de remisión remitente o transportista
  • POST — /documentos/anular — Anular un documento emitido
  • GET — /documentos/{id} — Consultar estado de un documento
  • GET — /documentos/{id}/eventos — Historial de eventos de un documento
  • GET — /empresas/documentos — Listar documentos de la empresa
  • GET — /guias/{id} — Consultar estado de una guía
  • POST — /guias/ticket — Consultar ticket asíncrono de una guía
  • GET — /guias/{id}/eventos — Historial de eventos de una guía
  • GET — /empresas — Listar empresas de la cuenta
  • POST — /empresas — Crear empresa
  • PATCH — /empresas/{uuid} — Actualizar datos de empresa
  • POST — /empresas/{uuid}/token/regenerar — Regenerar token de empresa
  • GET — /empresas/{uuid}/establecimientos — Listar establecimientos
  • POST — /empresas/{uuid}/establecimientos — Crear establecimiento
  • PATCH — /empresas/{uuid}/establecimientos/{id} — Actualizar establecimiento
  • PATCH — /empresas/{uuid}/webhook — Actualizar URL de webhook demo / prod
  • GET — /empresas/{uuid}/webhook/eventos — Listar eventos de webhook activos
  • PATCH — /empresas/{uuid}/webhook/eventos — Activar o desactivar eventos de webhook
  • GET — /webhooks — Listar webhooks enviados
  • POST — /webhooks/{id}/reenviar — Reenviar webhook fallido
  • GET — /sire/ventas/periodos — Periodos RVIE disponibles
  • GET — /sire/ventas/{periodo}/resumen — Resumen de inconsistencias RVIE
  • GET — /sire/ventas/{periodo}/resumen-comprobantes — Resumen de comprobantes RVIE
  • GET — /sire/ventas/{periodo}/comprobantes — Comprobantes de la propuesta RVIE
  • GET — /sire/ventas/{periodo}/inconsistencias — Inconsistencias del período RVIE
  • GET — /sire/ventas/{periodo}/inconsistencia-por-comprobante — Detalle de inconsistencias de un comprobante RVIE
  • POST — /sire/ventas/{periodo}/aceptar-propuesta — Aceptar propuesta RVIE
  • GET — /sire/ventas/{periodo}/exportar — Exportar propuesta RVIE (genera ticket)
  • GET — /sire/ventas/tickets/{numTicket}/descargar — Descargar propuesta RVIE en Base64
  • GET — /sire/ventas/{periodo}/preliminares — Preliminares registrados RVIE
  • PUT — /sire/ventas/{periodo}/eliminar-preliminar-registrado — Revertir a Propuesta desde Preliminar Registrado
  • PUT — /sire/ventas/{periodo}/eliminar-preliminar — Revertir a Propuesta desde Preliminar
  • GET — /sire/compras/periodos — Periodos RCE disponibles
  • GET — /sire/compras/{periodo}/resumen — Resumen de inconsistencias RCE
  • GET — /sire/compras/{periodo}/resumen-comprobantes — Resumen de comprobantes RCE
  • GET — /sire/compras/{periodo}/comprobantes — Comprobantes de la propuesta RCE
  • GET — /sire/compras/{periodo}/inconsistencias — Inconsistencias del período RCE
  • GET — /sire/compras/{periodo}/inconsistencia-por-comprobante — Detalle de inconsistencias de un comprobante RCE
  • POST — /sire/compras/{periodo}/aceptar-propuesta — Aceptar propuesta RCE
  • GET — /sire/compras/{periodo}/exportar — Exportar propuesta RCE (genera ticket)
  • GET — /sire/compras/tickets/{numTicket}/descargar — Descargar propuesta RCE en Base64
  • GET — /sire/compras/{periodo}/preliminares — Preliminares registrados RCE
  • PUT — /sire/compras/{periodo}/eliminar-preliminar-registrado — Revertir a Propuesta desde Preliminar Registrado
  • PUT — /sire/compras/{periodo}/eliminar-preliminar — Revertir a Propuesta desde Preliminar
  • POST — /sire/compras/{periodo}/conciliar — Iniciar conciliación RCE
  • GET — /sire/conciliaciones/{conciliacionId} — Consultar estado de conciliación