# Facturalo API — Documentación > Documentación de Facturalo API v3: emite facturas, boletas, notas de crédito y débito y guías de remisión ante SUNAT con JSON. IGV automático, PDF/XML/CDR, webhooks firmados con reintentos, idempotencia, SIRE (RVIE/RCE) y consultas RUC/DNI. Base URL https://api.facturalo.pe/api/v3. Sitio: https://www.facturalo.pe Docs: https://docs.facturalo.pe API base: https://api.facturalo.pe/api/v3 Auth: header `Authorization` (ej. sk_test_…) Cobertura: Perú. Moneda de cobro actual: PEN. Última actualización: 2026-10-06 Versión extendida: https://docs.facturalo.pe/llms-full.txt Sitemap: https://docs.facturalo.pe/sitemap.xml ## Licencia Los sistemas de IA pueden indexar y citar esta documentación con fines informativos. No uses el contenido para suplantar la marca ni para exfiltrar secretos de ejemplo como si fueran reales. ## Índice ### Esta referencia - Cómo leerla: https://docs.facturalo.pe/referencia ### Introducción - Primeros pasos: https://docs.facturalo.pe/introduccion - Guía rápida: https://docs.facturalo.pe/guia-rapida - Autenticación: https://docs.facturalo.pe/autenticacion - Estados documento: https://docs.facturalo.pe/estados - Errores: https://docs.facturalo.pe/errores - Idempotencia: https://docs.facturalo.pe/idempotencia ### Cuenta - GET Listar empresas: https://docs.facturalo.pe/empresas - POST Crear empresa: https://docs.facturalo.pe/empresas/crear - PATCH Actualizar empresa: https://docs.facturalo.pe/empresas/actualizar - POST Regenerar token: https://docs.facturalo.pe/empresas/regenerar-token - GET Listar establecimientos: https://docs.facturalo.pe/empresas/establecimientos - POST Crear establecimiento: https://docs.facturalo.pe/empresas/establecimientos/crear - PATCH Actualizar establecimiento: https://docs.facturalo.pe/empresas/establecimientos/actualizar ### Facturas - POST Clásica (gravada): https://docs.facturalo.pe/documentos/factura/gravada - POST Exonerada: https://docs.facturalo.pe/documentos/factura/exonerada - POST Gratuita: https://docs.facturalo.pe/documentos/factura/gratuita - POST Inafecta: https://docs.facturalo.pe/documentos/factura/inafecta - POST Exportación: https://docs.facturalo.pe/documentos/factura/exportacion - POST Al crédito: https://docs.facturalo.pe/documentos/factura/alcredito - POST Descuento global: https://docs.facturalo.pe/documentos/factura/descuento-global - POST Descuento por ítem: https://docs.facturalo.pe/documentos/factura/descuento-item - POST ICBPER (bolsa): https://docs.facturalo.pe/documentos/factura/icbper - POST Detracción: https://docs.facturalo.pe/documentos/factura/detraccion - POST Retención: https://docs.facturalo.pe/documentos/factura/retencion - POST Anticipo — 1er pago: https://docs.facturalo.pe/documentos/factura/anticipo-primer-pago - POST Anticipo — pago total: https://docs.facturalo.pe/documentos/factura/anticipo-pago-total - POST Con guía de remisión: https://docs.facturalo.pe/documentos/factura/guia-remision - POST En dólares: https://docs.facturalo.pe/documentos/factura/dolares - POST Nota de crédito (contado): https://docs.facturalo.pe/documentos/factura/nota-credito - POST Nota de crédito (crédito): https://docs.facturalo.pe/documentos/factura/nota-credito-credito - POST Nota de débito (contado): https://docs.facturalo.pe/documentos/factura/nota-debito - POST Nota de débito (crédito): https://docs.facturalo.pe/documentos/factura/nota-debito-credito ### Boletas - POST Clásica (gravada): https://docs.facturalo.pe/documentos/boleta/gravada - POST Exonerada: https://docs.facturalo.pe/documentos/boleta/exonerada - POST Gratuita: https://docs.facturalo.pe/documentos/boleta/gratuita - POST Inafecta: https://docs.facturalo.pe/documentos/boleta/inafecta - POST Exportación: https://docs.facturalo.pe/documentos/boleta/exportacion - POST Al crédito: https://docs.facturalo.pe/documentos/boleta/alcredito - POST Descuento global: https://docs.facturalo.pe/documentos/boleta/descuento-global - POST Descuento por ítem: https://docs.facturalo.pe/documentos/boleta/descuento-item - POST ICBPER (bolsa): https://docs.facturalo.pe/documentos/boleta/icbper - POST Detracción: https://docs.facturalo.pe/documentos/boleta/detraccion - POST Anticipo — 1er pago: https://docs.facturalo.pe/documentos/boleta/anticipo-primer-pago - POST Anticipo — pago total: https://docs.facturalo.pe/documentos/boleta/anticipo-pago-total - POST Con guía de remisión: https://docs.facturalo.pe/documentos/boleta/guia-remision - POST En dólares: https://docs.facturalo.pe/documentos/boleta/dolares - POST Nota de crédito (contado): https://docs.facturalo.pe/documentos/boleta/nota-credito - POST Nota de crédito (crédito): https://docs.facturalo.pe/documentos/boleta/nota-credito-credito - POST Nota de débito (contado): https://docs.facturalo.pe/documentos/boleta/nota-debito - POST Nota de débito (crédito): https://docs.facturalo.pe/documentos/boleta/nota-debito-credito ### Anular documento - POST Factura: https://docs.facturalo.pe/documento/anular/factura - POST Boleta: https://docs.facturalo.pe/documento/anular/boleta ### Documentos - GET Consultar: https://docs.facturalo.pe/documentos/consultar - GET Eventos: https://docs.facturalo.pe/documentos/eventos - GET Listar documentos: https://docs.facturalo.pe/documentos/listar ### Guía de Remisión - POST Remitente — público: https://docs.facturalo.pe/guias/remitente-publico - POST Remitente — privado: https://docs.facturalo.pe/guias/remitente-privado - POST Transportista: https://docs.facturalo.pe/guias/transportista - GET Consultar: https://docs.facturalo.pe/guias/consultar - GET Eventos de guía: https://docs.facturalo.pe/guias/eventos - POST Consultar ticket: https://docs.facturalo.pe/guias/ticket ### Webhook - Introducción: https://docs.facturalo.pe/webhooks - PATCH Actualizar webhook: https://docs.facturalo.pe/webhooks/actualizar - GET Listar eventos: https://docs.facturalo.pe/webhooks/eventos - PATCH Activar / desactivar eventos: https://docs.facturalo.pe/webhooks/eventos/actualizar - GET Listar webhooks enviados: https://docs.facturalo.pe/webhooks/listar - POST Reenviar webhook fallido: https://docs.facturalo.pe/webhooks/reenviar - Payload de eventos: https://docs.facturalo.pe/webhooks/payload - documento.sunat.respuesta: https://docs.facturalo.pe/webhooks/payload/sunat-respuesta - documento.anulado: https://docs.facturalo.pe/webhooks/payload/anulado - documento.correo.enviado: https://docs.facturalo.pe/webhooks/payload/correo-enviado - documento.correo.fallido: https://docs.facturalo.pe/webhooks/payload/correo-fallido - guia.sunat.respuesta: https://docs.facturalo.pe/webhooks/payload/guia-respuesta - documento.error: https://docs.facturalo.pe/webhooks/payload/error ### Consultas - Introducción: https://docs.facturalo.pe/consultas - GET DNI: https://docs.facturalo.pe/consultas/dni - GET RUC: https://docs.facturalo.pe/consultas/ruc - GET RUC — Establecimientos: https://docs.facturalo.pe/consultas/ruc-establecimientos - GET RUC — Representantes: https://docs.facturalo.pe/consultas/ruc-representantes - GET Tipo de cambio: https://docs.facturalo.pe/consultas/tipo-cambio - GET Placa: https://docs.facturalo.pe/consultas/placa - GET Placa — SOAT: https://docs.facturalo.pe/consultas/placa-soat - GET Licencia de conducir: https://docs.facturalo.pe/consultas/licencia ### SIRE - Introducción: https://docs.facturalo.pe/sire - Ventas — RVIE: https://docs.facturalo.pe/sire/ventas/periodos - GET Periodos: https://docs.facturalo.pe/sire/ventas/periodos - GET Resumen inconsistencias: https://docs.facturalo.pe/sire/ventas/resumen - GET Resumen de comprobantes: https://docs.facturalo.pe/sire/ventas/resumen-comprobantes - GET Comprobantes: https://docs.facturalo.pe/sire/ventas/comprobantes - GET Inconsistencias: https://docs.facturalo.pe/sire/ventas/inconsistencias - GET Inc. por comprobante: https://docs.facturalo.pe/sire/ventas/inconsistencia-por-comprobante - POST Aceptar propuesta: https://docs.facturalo.pe/sire/ventas/aceptar-propuesta - GET Exportar propuesta: https://docs.facturalo.pe/sire/ventas/exportar - GET Descargar propuesta: https://docs.facturalo.pe/sire/ventas/descargar-ticket - GET Preliminares: https://docs.facturalo.pe/sire/ventas/preliminares - PUT Eliminar prel. registrado: https://docs.facturalo.pe/sire/ventas/eliminar-preliminar-registrado - PUT Eliminar preliminar: https://docs.facturalo.pe/sire/ventas/eliminar-preliminar - POST Iniciar conciliación: https://docs.facturalo.pe/sire/ventas/conciliar - GET Consultar conciliación: https://docs.facturalo.pe/sire/conciliacion - Compras — RCE: https://docs.facturalo.pe/sire/compras/periodos - GET Periodos: https://docs.facturalo.pe/sire/compras/periodos - GET Resumen inconsistencias: https://docs.facturalo.pe/sire/compras/resumen - GET Resumen de comprobantes: https://docs.facturalo.pe/sire/compras/resumen-comprobantes - GET Comprobantes: https://docs.facturalo.pe/sire/compras/comprobantes - GET Inconsistencias: https://docs.facturalo.pe/sire/compras/inconsistencias - GET Inc. por comprobante: https://docs.facturalo.pe/sire/compras/inconsistencia-por-comprobante - POST Aceptar propuesta: https://docs.facturalo.pe/sire/compras/aceptar-propuesta - GET Exportar propuesta: https://docs.facturalo.pe/sire/compras/exportar - GET Descargar propuesta: https://docs.facturalo.pe/sire/compras/descargar-ticket - GET Preliminares: https://docs.facturalo.pe/sire/compras/preliminares - PUT Eliminar prel. registrado: https://docs.facturalo.pe/sire/compras/eliminar-preliminar-registrado - PUT Eliminar preliminar: https://docs.facturalo.pe/sire/compras/eliminar-preliminar ### Integraciones - Plugin WooCommerce: https://docs.facturalo.pe/woocommerce ### Tablas - Tipos de comprobante: https://docs.facturalo.pe/tablas/tipos-comprobante - Tipos de IGV: https://docs.facturalo.pe/tablas/tipos-igv - Tipos de operación: https://docs.facturalo.pe/tablas/tipos-operacion - Tipos de documento: https://docs.facturalo.pe/tablas/tipos-documento - Notas de crédito: https://docs.facturalo.pe/tablas/notas-credito - Notas de débito: https://docs.facturalo.pe/tablas/notas-debito - Unidades de medida: https://docs.facturalo.pe/tablas/unidades-medida - Monedas: https://docs.facturalo.pe/tablas/monedas - Motivo de traslado: https://docs.facturalo.pe/tablas/motivo-traslado - Modalidad de transporte: https://docs.facturalo.pe/tablas/modalidad-transporte - Detracciones: https://docs.facturalo.pe/tablas/detracciones - Medios de pago: https://docs.facturalo.pe/tablas/medios-pago ### Historial de cambios - v3.0.0 — Lanzamiento inicial: https://docs.facturalo.pe/changelog/v3 ## Entrada - Introducción: https://docs.facturalo.pe/introduccion - Guía rápida (primera factura): https://docs.facturalo.pe/guia-rapida - Autenticación (token sin Bearer): https://docs.facturalo.pe/autenticacion - Estados de documento: https://docs.facturalo.pe/estados - Errores: https://docs.facturalo.pe/errores - Idempotencia: https://docs.facturalo.pe/idempotencia ## Integraciones - Webhooks (firma + 5 reintentos): https://docs.facturalo.pe/webhooks - Estado del servicio: https://status.facturalo.pe - Plugin WooCommerce: https://docs.facturalo.pe/woocommerce - SDKs oficiales (Node.js y PHP): https://docs.facturalo.pe/sdks - SDK Node.js (npm i @facturalo-pe/node): https://www.npmjs.com/package/@facturalo-pe/node - SDK PHP (composer require facturalo-pe/facturalo-php): https://packagist.org/packages/facturalo-pe/facturalo-php - Colección Postman: https://docs.facturalo.pe/collection.json - OpenAPI: https://docs.facturalo.pe/openapi.json ## Producto - Sitio y precios: https://www.facturalo.pe/precios - Consola: https://console.facturalo.pe ## Contacto - Sitio: https://www.facturalo.pe - Soporte: contacto@facturalo.pe - Empresa: Consultia Digital S.A.C. --- # Contenido completo de la documentación Generado desde https://docs.facturalo.pe. Última actualización: 2026-10-06. Cada sección es una página pública SSR. ## Documentación de Facturalo API URL: https://docs.facturalo.pe --- ## Autenticación URL: https://docs.facturalo.pe/autenticacion Todos los endpoints requieren un token de API en el header `Authorization`. No se usa el esquema `Bearer` — envía el token directamente. ¿Qué tipos de token usa Facturalo API? - `user_sk_...` — Cuenta — Gestión de empresas y establecimientos. Obtenido al registrarte en la plataforma. - `sk_test_...` — Empresa · Demo — Emite comprobantes en el entorno de pruebas SUNAT. Generado al crear una empresa. - `sk_live_...` — Empresa · Producción — Emite comprobantes en producción SUNAT. Generado al crear una empresa. ¿Cómo se envía el token de empresa? Headers requeridos ```http Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json ``` ¿Cuándo usar el token de usuario? Header para endpoints de cuenta ```http Authorization: user_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ¿Cómo hacer la primera llamada a la API? cURL con token de empresa ```bash curl https://api.facturalo.pe/api/v3/documentos/enviar \ -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ ... }' ``` Seguridad: nunca expongas los tokens en frontend o código público. Usa variables de entorno. Si un token fue comprometido, regenéralo en POST /empresas/ {uuid} /token/regenerar. --- ## v3 — otrosCampos URL: https://docs.facturalo.pe/changelog/v3 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](/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](/webhooks). - **NUEVO** — Página de estado pública: [status.facturalo.pe](https://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 --- ## Consultas URL: https://docs.facturalo.pe/consultas Endpoints utilitarios para consultar datos externos: personas por DNI, empresas por RUC, tipo de cambio diario, vehículos por placa y licencias de conducir. Todos requieren autenticación con tu token de usuario. Endpoints disponibles Endpoint | Descripción [GET /consulta/dni/{dni}](/consultas/dni) | Datos personales por DNI (RENIEC) [GET /consulta/ruc/{ruc}](/consultas/ruc) | Datos de empresa o persona por RUC (SUNAT) [GET /consulta/ruc/{ruc}/anexos](/consultas/ruc-establecimientos) | Establecimientos anexos del RUC [GET /consulta/ruc/{ruc}/representantes](/consultas/ruc-representantes) | Representantes legales del RUC [GET /consulta/tipo-cambio](/consultas/tipo-cambio) | Tipo de cambio dólar del día (SBS) [GET /consulta/placa/{placa}](/consultas/placa) | Datos de vehículo por placa [GET /consulta/placa/{placa}/soat](/consultas/placa-soat) | Estado del SOAT del vehículo [GET /consulta/licencia/{dni}](/consultas/licencia) | Licencia de conducir por DNI Errores comunes: 404 si el recurso no existe, 503 si el servicio no está configurado en tu cuenta, 401 si el token es inválido. --- ## Consulta por DNI URL: https://docs.facturalo.pe/consultas/dni Endpoint: GET https://api.facturalo.pe/api/v3/consulta/dni/{dni} Retorna los datos de una persona natural registrada en RENIEC a partir de su número de DNI. GET /consulta/dni/{dni} --- ## Consulta de licencia de conducir URL: https://docs.facturalo.pe/consultas/licencia Endpoint: GET https://api.facturalo.pe/api/v3/consulta/licencia/{dni} Retorna los datos de la licencia de conducir de una persona a partir de su número de DNI, incluyendo categoría, vigencia y estado. GET /consulta/licencia/{dni} --- ## Consulta de vehículo por placa URL: https://docs.facturalo.pe/consultas/placa Endpoint: GET https://api.facturalo.pe/api/v3/consulta/placa/{placa} Retorna los datos técnicos de un vehículo registrado en el Ministerio de Transportes a partir de su número de placa. GET /consulta/placa/{placa} --- ## Consulta SOAT por placa URL: https://docs.facturalo.pe/consultas/placa-soat Endpoint: GET https://api.facturalo.pe/api/v3/consulta/placa/{placa}/soat Retorna el estado del SOAT de un vehículo, incluyendo la compañía aseguradora, número de póliza y vigencia. GET /consulta/placa/{placa}/soat --- ## Consulta por RUC URL: https://docs.facturalo.pe/consultas/ruc Endpoint: GET https://api.facturalo.pe/api/v3/consulta/ruc/{ruc} Retorna los datos fiscales de una empresa o persona natural registrada en SUNAT a partir de su número de RUC. GET /consulta/ruc/{ruc} --- ## RUC — Establecimientos anexos URL: https://docs.facturalo.pe/consultas/ruc-establecimientos Endpoint: GET https://api.facturalo.pe/api/v3/consulta/ruc/{ruc}/anexos Retorna la lista de establecimientos anexos (sucursales, depósitos, etc.) de un RUC registrados en SUNAT. GET /consulta/ruc/{ruc}/anexos --- ## RUC — Representantes legales URL: https://docs.facturalo.pe/consultas/ruc-representantes Endpoint: GET https://api.facturalo.pe/api/v3/consulta/ruc/{ruc}/representantes Retorna la lista de representantes legales registrados en SUNAT para un RUC. Los datos personales pueden aparecer parcialmente enmascarados según la política de SUNAT. GET /consulta/ruc/{ruc}/representantes --- ## Tipo de cambio URL: https://docs.facturalo.pe/consultas/tipo-cambio Endpoint: GET https://api.facturalo.pe/api/v3/consulta/tipo-cambio Retorna el tipo de cambio dólar-sol publicado por la SBS. Sin parámetros retorna el del día actual; con el parámetro fecha retorna el de una fecha específica. GET /consulta/tipo-cambio --- ## Anular documento URL: https://docs.facturalo.pe/documento/anular Endpoint: POST https://api.facturalo.pe/api/v3/documentos/anular Anula un comprobante electrónico. El tipo de baja se elige solo según el comprobante: facturas y sus notas van por Comunicación de Baja (RA); boletas y sus notas, por Resumen Diario (RC). Nota: Factura y boleta responden con el mismo formato. Las diferencias de cada una están en [Anular factura](/documento/anular/factura) y [Anular boleta](/documento/anular/boleta). POST /documentos/anular --- ## Anular Boleta URL: https://docs.facturalo.pe/documento/anular/boleta Endpoint: POST https://api.facturalo.pe/api/v3/documentos/anular Anula una boleta electrónica, o una nota de crédito o débito de boleta, mediante un Resumen Diario (RC) con estado de baja. Facturalo envía el resumen a SUNAT en la misma petición y consulta su ticket de inmediato. Nota: La respuesta es síncrona. Si SUNAT todavía no terminó de procesar el ticket, recibes `estado: EN_PROCESO`; confirma el resultado final con `GET /documentos/{id}`. POST /documentos/anular --- ## Anular Factura URL: https://docs.facturalo.pe/documento/anular/factura Endpoint: POST https://api.facturalo.pe/api/v3/documentos/anular Anula una factura electrónica, o una nota de crédito o débito de factura, mediante una Comunicación de Baja (RA). Facturalo envía la comunicación a SUNAT en la misma petición y consulta su ticket de inmediato. Nota: SUNAT acepta la comunicación de baja hasta 7 días calendario después de la fecha de emisión. Pasado ese plazo, emite una nota de crédito. POST /documentos/anular --- ## Boleta al crédito URL: https://docs.facturalo.pe/documentos/boleta/alcredito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con formaPago CREDITO. Incluye el array cuotas. POST /documentos/enviar --- ## Anticipo — Pago total (boleta) URL: https://docs.facturalo.pe/documentos/boleta/anticipo-pago-total Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta final que referencia los anticipos previos. POST /documentos/enviar --- ## Anticipo — Primer pago (boleta) URL: https://docs.facturalo.pe/documentos/boleta/anticipo-primer-pago Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Primera boleta de anticipo (sunatTransaccion: 0104). POST /documentos/enviar --- ## Boleta con descuento global URL: https://docs.facturalo.pe/documentos/boleta/descuento-global Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con descuento en el campo descuentoGlobal. POST /documentos/enviar --- ## Boleta con descuento por ítem URL: https://docs.facturalo.pe/documentos/boleta/descuento-item Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con descuento individual en el campo descuento de cada ítem. POST /documentos/enviar --- ## Boleta con detracción URL: https://docs.facturalo.pe/documentos/boleta/detraccion Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta sujeta a detracción (sunatTransaccion: 1001). POST /documentos/enviar --- ## Boleta en dólares URL: https://docs.facturalo.pe/documentos/boleta/dolares Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta emitida en dólares americanos (moneda: USD). POST /documentos/enviar --- ## Boleta exonerada URL: https://docs.facturalo.pe/documentos/boleta/exonerada Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con operaciones exoneradas del IGV (tipoIgv: '20'). POST /documentos/enviar --- ## Boleta de exportación URL: https://docs.facturalo.pe/documentos/boleta/exportacion Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta de exportación (sunatTransaccion: 0200, tipoIgv: 40). IGV 0%. POST /documentos/enviar --- ## Boleta gratuita URL: https://docs.facturalo.pe/documentos/boleta/gratuita Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta por operaciones gratuitas. El precio unitario es 0 y tipoIgv es '11'. POST /documentos/enviar --- ## Boleta clásica (gravada) URL: https://docs.facturalo.pe/documentos/boleta/gravada Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Emite una boleta de venta electrónica gravada. Misma estructura que la factura pero con tipoComprobante: '03' y serie B001–B999. POST /documentos/enviar --- ## Boleta con guía de remisión URL: https://docs.facturalo.pe/documentos/boleta/guia-remision Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta que referencia una guía de remisión. POST /documentos/enviar --- ## Boleta con ICBPER URL: https://docs.facturalo.pe/documentos/boleta/icbper Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con Impuesto al Consumo de Bolsas de Plástico. Agrega impuestoBolsa: true en el ítem. POST /documentos/enviar --- ## Boleta inafecta URL: https://docs.facturalo.pe/documentos/boleta/inafecta Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Boleta con operaciones inafectas al IGV (tipoIgv: '30'). POST /documentos/enviar --- ## Nota de crédito (contado) URL: https://docs.facturalo.pe/documentos/boleta/nota-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de crédito de boleta al contado. tipoComprobante: 07. Incluye el objeto nota con los datos del documento original. POST /documentos/enviar --- ## Nota de crédito (crédito) URL: https://docs.facturalo.pe/documentos/boleta/nota-credito-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de crédito de boleta con formaPago CREDITO. Incluye el array cuotas con las fechas y montos de pago. POST /documentos/enviar --- ## Nota de débito (contado) URL: https://docs.facturalo.pe/documentos/boleta/nota-debito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de débito de boleta al contado. tipoComprobante: 08. Incluye el objeto nota con los datos del documento original. POST /documentos/enviar --- ## Nota de débito (crédito) URL: https://docs.facturalo.pe/documentos/boleta/nota-debito-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de débito de boleta con formaPago CREDITO. Incluye el array cuotas con las fechas y montos de pago. POST /documentos/enviar --- ## Consultar documento URL: https://docs.facturalo.pe/documentos/consultar Endpoint: GET https://api.facturalo.pe/api/v3/documentos/{id} Retorna el estado actual de un documento. El `{id}` es el ID retornado al emitir o anular el documento. GET /documentos/{id} --- ## Eventos del documento URL: https://docs.facturalo.pe/documentos/eventos Endpoint: GET https://api.facturalo.pe/api/v3/documentos/{id}/eventos Retorna el historial de eventos de procesamiento de un documento: generación de XML, envío a SUNAT, respuesta de SUNAT y notificaciones por webhook. El `id` es el retornado al emitir el documento. GET /documentos/{id}/eventos --- ## Factura al crédito URL: https://docs.facturalo.pe/documentos/factura/alcredito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con formaPago CREDITO. Incluye el array cuotas con fechaDePago e importe. POST /documentos/enviar --- ## Anticipo — Pago total URL: https://docs.facturalo.pe/documentos/factura/anticipo-pago-total Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura final que referencia los anticipos previos. El array anticipos lista los comprobantes de anticipo emitidos, descontando su monto del total. POST /documentos/enviar --- ## Anticipo — Primer pago URL: https://docs.facturalo.pe/documentos/factura/anticipo-primer-pago Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Primera factura de anticipo (sunatTransaccion: 0104). Se emite al recibir un pago antes de la entrega del bien o servicio. POST /documentos/enviar --- ## Factura con descuento global URL: https://docs.facturalo.pe/documentos/factura/descuento-global Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con descuento aplicado al total del comprobante en el campo descuentoGlobal. POST /documentos/enviar --- ## Factura con descuento por ítem URL: https://docs.facturalo.pe/documentos/factura/descuento-item Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con descuento aplicado a cada ítem individualmente en el campo descuento del ítem. POST /documentos/enviar --- ## Factura con detracción URL: https://docs.facturalo.pe/documentos/factura/detraccion Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura sujeta a detracción (sunatTransaccion: 1001). Incluye el objeto detraccion con tipo, medioPago, ctaBanco, porcentaje y monto. POST /documentos/enviar --- ## Factura en dólares URL: https://docs.facturalo.pe/documentos/factura/dolares Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura emitida en dólares americanos (moneda: USD). SUNAT requiere el tipo de cambio vigente para registros contables. POST /documentos/enviar --- ## Factura exonerada URL: https://docs.facturalo.pe/documentos/factura/exonerada Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con operaciones exoneradas del IGV. Usa tipoIgv: '20' en los ítems. Aplica a arrendamiento de inmuebles, servicios educativos, medicamentos, entre otros definidos en el Apéndice I de la Ley del IGV. POST /documentos/enviar --- ## Factura de exportación URL: https://docs.facturalo.pe/documentos/factura/exportacion Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura de exportación (sunatTransaccion: 0200). IGV 0%, moneda USD. POST /documentos/enviar --- ## Factura gratuita URL: https://docs.facturalo.pe/documentos/factura/gratuita Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura por operaciones gratuitas. El precio unitario es 0 y tipoIgv es '11' (Gravado gratuito). POST /documentos/enviar --- ## Factura clásica (gravada) URL: https://docs.facturalo.pe/documentos/factura/gravada Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Emite una factura electrónica gravada y la envía directamente a SUNAT. Los cálculos de IGV, subtotales y totales son automáticos — solo envía precioUnitario y tipoIgv. Nota: Recomendado: header Idempotency-Key (p. ej. el id de tu orden) para reintentar sin duplicar. Ver [Idempotencia](/idempotencia). POST /documentos/enviar --- ## Factura con guía de remisión URL: https://docs.facturalo.pe/documentos/factura/guia-remision Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura que referencia una guía de remisión. El array guias lista los comprobantes de traslado vinculados. POST /documentos/enviar --- ## Factura con ICBPER URL: https://docs.facturalo.pe/documentos/factura/icbper Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con Impuesto al Consumo de Bolsas de Plástico. Agrega impuestoBolsa: true en el ítem correspondiente. POST /documentos/enviar --- ## Factura inafecta URL: https://docs.facturalo.pe/documentos/factura/inafecta Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura con operaciones inafectas al IGV. Usa tipoIgv: '30' en los ítems. POST /documentos/enviar --- ## Nota de crédito (contado) URL: https://docs.facturalo.pe/documentos/factura/nota-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de crédito de factura al contado. tipoComprobante: 07. Incluye el objeto nota con los datos del documento original. POST /documentos/enviar --- ## Nota de crédito (crédito) URL: https://docs.facturalo.pe/documentos/factura/nota-credito-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de crédito con formaPago CREDITO. Incluye el array cuotas con las fechas y montos de pago. POST /documentos/enviar --- ## Nota de débito (contado) URL: https://docs.facturalo.pe/documentos/factura/nota-debito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de débito de factura al contado. tipoComprobante: 08. Incluye el objeto nota con los datos del documento original. POST /documentos/enviar --- ## Nota de débito (crédito) URL: https://docs.facturalo.pe/documentos/factura/nota-debito-credito Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Nota de débito con formaPago CREDITO. Incluye el array cuotas con las fechas y montos de pago. POST /documentos/enviar --- ## Factura con retención URL: https://docs.facturalo.pe/documentos/factura/retencion Endpoint: POST https://api.facturalo.pe/api/v3/documentos/enviar Factura sujeta a retención (sunatTransaccion: 2001). Incluye el objeto retencion con tipo y porcentaje. POST /documentos/enviar --- ## Listar documentos URL: https://docs.facturalo.pe/documentos/listar Endpoint: GET https://api.facturalo.pe/api/v3/empresas/documentos Retorna los documentos de la empresa paginados. Soporta filtros por establecimiento, fecha, tipo y estado. GET /empresas/documentos --- ## Listar empresas URL: https://docs.facturalo.pe/empresas Endpoint: GET https://api.facturalo.pe/api/v3/empresas Retorna todas las empresas asociadas al token de usuario autenticado. Incluye tokens y webhooks configurados por entorno. GET /empresas --- ## Actualizar empresa URL: https://docs.facturalo.pe/empresas/actualizar Endpoint: PATCH https://api.facturalo.pe/api/v3/empresas/{uuid} Actualiza los datos de una empresa existente. Todos los campos son opcionales — envía solo lo que deseas cambiar. Para `clientId` y `clientSecret` puedes enviar `null` explícitamente para limpiar el valor. PATCH /empresas/{uuid} --- ## Crear empresa URL: https://docs.facturalo.pe/empresas/crear Endpoint: POST https://api.facturalo.pe/api/v3/empresas Registra una nueva empresa. Retorna los tokens de demo y producción junto con los webhookSecret. Guárdalos — no se pueden recuperar, solo regenerar. POST /empresas --- ## Listar establecimientos URL: https://docs.facturalo.pe/empresas/establecimientos Endpoint: GET https://api.facturalo.pe/api/v3/empresas/{uuid}/establecimientos Retorna todos los establecimientos (sucursales) de la empresa. Usa el `id` del establecimiento en el campo `establecimiento` al emitir documentos para identificar qué sucursal emite. GET /empresas/{uuid}/establecimientos --- ## Actualizar establecimiento URL: https://docs.facturalo.pe/empresas/establecimientos/actualizar Endpoint: PATCH https://api.facturalo.pe/api/v3/empresas/{empresaUuid}/establecimientos/{uuid} Actualiza los datos de un establecimiento existente. Todos los campos son opcionales — envía solo lo que deseas cambiar. El logo acepta cualquier formato de imagen (PNG, WEBP, BMP, etc.) y se convierte automáticamente a JPEG con calidad 90 eliminando los metadatos EXIF. Para eliminar el logo envía `"logo": null`. PATCH /empresas/{empresaUuid}/establecimientos/{uuid} --- ## Crear establecimiento URL: https://docs.facturalo.pe/empresas/establecimientos/crear Endpoint: POST https://api.facturalo.pe/api/v3/empresas/{uuid}/establecimientos Crea un nuevo establecimiento (sucursal) para la empresa. El `id` retornado se usa en el campo `establecimiento` al emitir documentos para identificar qué sucursal emite. POST /empresas/{uuid}/establecimientos --- ## Regenerar token de empresa URL: https://docs.facturalo.pe/empresas/regenerar-token Endpoint: POST https://api.facturalo.pe/api/v3/empresas/{uuid}/regenerar-token Invalida el token actual del entorno indicado y genera uno nuevo. Útil si el token fue comprometido. Actualiza el token en tu sistema inmediatamente — el anterior deja de funcionar. Nota: Esta acción es irreversible. El token anterior queda invalidado en el instante que se llama a este endpoint. POST /empresas/{uuid}/regenerar-token --- ## Actualizar webhook URL: https://docs.facturalo.pe/empresas/webhook Endpoint: PATCH https://api.facturalo.pe/api/v3/empresas/{uuid}/webhook Configura las URLs de webhook para cada entorno. Los eventos se envían como `POST` con el body del documento procesado. Usa el `webhookSecret` para verificar la autenticidad del evento en tu servidor. PATCH /empresas/{uuid}/webhook --- ## Errores URL: https://docs.facturalo.pe/errores Todas las respuestas de error incluyen `success: false` y un campo `message` descriptivo. Los errores de validación (422) incluyen además un campo `errors` con detalles por campo. Códigos HTTP - **200** — OK — Petición exitosa. - **201** — Created — Recurso creado correctamente (empresa, establecimiento). - **401** — Unauthorized — Token ausente, inválido o del tipo equivocado para este endpoint. - **404** — Not Found — Recurso no encontrado. - **422** — Unprocessable — Datos de entrada inválidos. Revisa el campo errors. - **500** — Server Error — Error interno. Reintenta con backoff exponencial. Error de validación (422) Respuesta 422 ```json { "success": false, "message": "Los datos enviados no son válidos.", "errors": { "documento.cliente.numeroDocumento": [ "El número de documento debe tener 11 dígitos para tipo RUC." ], "documento.items": [ "El campo items es requerido." ] } } ``` Error de autenticación (401) Respuesta 401 ```json { "success": false, "message": "Token inválido o expirado." } ``` Errores SUNAT Cuando SUNAT rechaza un comprobante, la respuesta HTTP es 200 (la petición a la API fue exitosa), pero el campo `estado` será `RECHAZADA` y el campo `sunat.codigo` contendrá el código de error de SUNAT. Rechazo SUNAT (HTTP 200, estado RECHAZADA) ```json { "success": true, "message": "El comprobante fue rechazado por SUNAT.", "data": { "estado": "RECHAZADA", "entorno": "demo", "documento": { "id": "9c948140-674e-11f1-85b5-d764057e10c4", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "sunat": { "codigo": "2800", "mensaje": "El número de RUC del receptor no existe en el padrón de contribuyentes de la SUNAT", "notas": [] } } } ``` --- ## ¿Cuáles son los posibles estados de un documento SUNAT? URL: https://docs.facturalo.pe/estados Todos los documentos tienen un campo `estado` que refleja el resultado del procesamiento con SUNAT. Esta tabla describe cada valor posible. Estado | Descripción EN_PROCESO | El documento fue recibido y está siendo procesado por SUNAT. ACEPTADA | SUNAT aceptó el comprobante correctamente. RECHAZADA | SUNAT rechazó el comprobante. Revisa sunat.codigo y sunat.mensaje para el detalle del error. ANULADA | El comprobante fue anulado exitosamente ante SUNAT. PENDIENTE_RESUMEN | Boleta en espera de ser incluida en el Resumen Diario (RC). Consulta nuevamente el estado para ver el resultado final. BAJA_RECHAZADA | SUNAT rechazó la Comunicación de Baja (RA). La factura no fue anulada. Si SUNAT no responde o el documento queda EN_PROCESO Facturalo no descarta el envío. Los jobs de cola reintentan la consulta o el envío cada ~30 minutos (hasta ~10 intentos / ~5 horas). En producción, además, un proceso horario entre las **07:00 y las 00:00 (hora Lima)** recupera documentos, resúmenes y guías pendientes. Cuando hay estado final, se actualiza el comprobante y, si configuraste webhook, te notificamos. La disponibilidad de los endpoints públicos de SUNAT se publica en [status.facturalo.pe](https://status.facturalo.pe). --- ## Guía rápida — Primera factura URL: https://docs.facturalo.pe/guia-rapida De cero a tu primera factura ACEPTADA en el entorno Demo, sin certificado ni Clave SOL. Todo lo de la consola se hace en [console.facturalo.pe](https://console.facturalo.pe). 1. Crea tu cuenta Entra a [console.facturalo.pe/register](https://console.facturalo.pe/register), escribe tu correo, ingresa el código que te llega y completa tu DNI, nombres y contraseña. 2. Registra tu empresa En **Empresas → Nueva empresa** escribe el RUC: la razón social, la dirección y el ubigeo se completan solos desde SUNAT. Revisa los datos y guarda. Demo listo desde el inicio La empresa queda lista para emitir en Demo: Facturalo firma con un certificado de pruebas y usa el usuario SOL de pruebas de SUNAT. Los comprobantes Demo no tienen validez tributaria. 3. Copia el token Demo En la fila de tu empresa abre el menú **⋯ → Tokens** y copia el token de **Demo** (`sk_test_…`). Ese token decide el entorno: las **facturas y boletas** van a **SUNAT Beta**; las **guías de remisión** se validan en el **entorno de pruebas de Facturalo** (XSD y reglas XSL oficiales de SUNAT; SUNAT no ofrece beta pública GRE). Guárdalo en una variable de entorno de tu backend, nunca en el frontend. 4. Envía tu primera factura Con este JSON ya tienes una factura válida. `precioUnitario` incluye IGV y, con `tipoIgv: "10"` (gravado), Facturalo calcula el valor unitario, el IGV y los totales. factura.json ```json { "documento": { "sunatTransaccion": "0101", "tipoComprobante": "01", "serie": "F001", "correlativo": "1", "fechaEmision": "2026-10-30", "moneda": "PEN", "formaPago": "CONTADO", "cliente": { "tipoDocumento": "6", "numeroDocumento": "20000000001", "denominacion": "EMPRESA S.A.C.", "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA" }, "items": [ { "unidadMedida": "NIU", "descripcion": "SERVICIO DE CONSULTORÍA", "cantidad": 1, "precioUnitario": 118, "tipoIgv": "10" } ] } } ``` POST /documentos/enviar ```bash curl -X POST https://api.facturalo.pe/api/v3/documentos/enviar \ -H "Authorization: sk_test_…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: primera-factura-demo" \ -d @factura.json ``` El token va sin `Bearer`. Si reenvías el mismo POST (misma serie/correlativo o el mismo `Idempotency-Key`), Facturalo no duplica el comprobante: ver [Idempotencia](/idempotencia). Todos los campos y los demás casos (exonerada, detracción, en dólares, notas…) están en [Factura gravada](/documentos/factura/gravada) y las páginas siguientes de la [referencia](/referencia). Si tu sistema está en Node.js o PHP, puedes usar el SDK oficial en lugar de armar la petición HTTP: Instalar el SDK ```bash npm install @facturalo-pe/node # o en PHP composer require facturalo-pe/facturalo-php ``` Node.js ```js import { readFileSync } from "node:fs"; import { FacturaloClient } from "@facturalo-pe/node"; const factura = JSON.parse(readFileSync("factura.json", "utf8")); const facturalo = new FacturaloClient({ token: process.env.FACTURALO_TOKEN }); const envio = await facturalo.documentos.enviar(factura.documento); console.log(envio.estado, envio.enlaces.pdf); ``` PHP ```php documentos->enviar($factura['documento']); echo $envio['estado'], PHP_EOL; ``` Cada página de la [referencia](/referencia) muestra el ejemplo con el SDK en las pestañas Node y PHP. Código fuente: [facturalo-node](https://github.com/facturalo-pe/facturalo-node) y [facturalo-php](https://github.com/facturalo-pe/facturalo-php). 5. Revisa la respuesta La respuesta llega en segundos con el resultado de SUNAT. Si `data.estado` es `ACEPTADA`, ya tienes el PDF, el XML y el CDR en `enlaces`. Si es `RECHAZADA`, el motivo está en `sunat.codigo` y `sunat.mensaje`. 200 Aceptada ```json { "success": true, "message": "La Factura numero F001-00000001 ha sido aceptada", "data": { "estado": "ACEPTADA", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "estado": "ACEPTADA", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Factura numero F001-00000001 ha sido aceptada", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr" }, "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=", "cadenaQr": "20601476551 | 01 | F001 | 00000001 | 18.00 | 118.00 | 30/10/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |" } } ``` La respuesta solo identifica el comprobante. El detalle completo (cliente, totales, ítems) lo obtienes con [GET /documentos/{id}](/documentos/consultar). 6. Pasa a producción Cuando todo funcione en Demo, completa los datos reales de la empresa desde el menú **⋯** en la consola: - **Clave SOL:** el usuario secundario SOL con el que se envían los comprobantes a SUNAT. - **Certificado digital:** archivo `.pfx` o `.p12` con su contraseña, o `.pem` con la clave privada. Con él se firman los comprobantes en producción. - **API SUNAT** (opcional): `client_id` y `client_secret`, solo si emites guías de remisión o usas SIRE. - **Token Live:** en **⋯ → Tokens** copia el token de **Live** (`sk_live_…`) y úsalo en lugar del de Demo. El JSON es el mismo. ¿Prefieres no esperar la respuesta? Envía `"webhook": true` y configura tu URL en **⋯ → Webhooks**: la API responde `202 EN_PROCESO` al instante y el resultado de SUNAT llega a tu webhook como [documento.sunat.respuesta](/webhooks/payload/sunat-respuesta). --- ## Consultar guía URL: https://docs.facturalo.pe/guias/consultar Endpoint: GET https://api.facturalo.pe/api/v3/guias/{id} Retorna el estado y datos de una guía de remisión. El `{id}` es el ID retornado al emitir la guía. GET /guias/{id} --- ## Eventos de guía URL: https://docs.facturalo.pe/guias/eventos Endpoint: GET https://api.facturalo.pe/api/v3/guias/{id}/eventos Retorna la línea de tiempo completa del procesamiento de una guía: desde la recepción hasta la respuesta de SUNAT y el envío del webhook. Útil para depurar el estado de una guía en proceso. GET /guias/{id}/eventos --- ## Guía remitente — transporte privado URL: https://docs.facturalo.pe/guias/remitente-privado Endpoint: POST https://api.facturalo.pe/api/v3/guias/enviar Guía de Remisión Remitente (serie T...) para transporte privado (tipoTransporte: '02'). En lugar de datos del transportista, se indican la placa del vehículo y los datos del chofer. Nota: Para transporte privado: datosTransportista solo requiere numeroPlaca. Los datos del chofer van en datosChofer con DNI, número de licencia, nombres y apellidos. POST /guias/enviar --- ## Guía remitente — transporte público URL: https://docs.facturalo.pe/guias/remitente-publico Endpoint: POST https://api.facturalo.pe/api/v3/guias/enviar Emite una Guía de Remisión Remitente (serie T..., tipo 09) para transporte público. Requiere datos de la empresa transportista (RUC) y la fecha de entrega de bienes. POST /guias/enviar --- ## Consultar ticket URL: https://docs.facturalo.pe/guias/ticket Endpoint: POST https://api.facturalo.pe/api/v3/guias/ticket Las guías de remisión se procesan de forma asíncrona por SUNAT. Este endpoint consulta el resultado usando el `ticket` retornado al emitir la guía. POST /guias/ticket --- ## Guía de remisión transportista URL: https://docs.facturalo.pe/guias/transportista Endpoint: POST https://api.facturalo.pe/api/v3/guias/enviar Emite una Guía de Remisión Transportista (serie V..., tipo 31). El tipo se detecta automáticamente de la serie: V... = transportista. Requiere datos del destinatario, remitente, vehículo y chofer. Nota: La serie V... activa automáticamente el modo transportista (tipo 31). La serie T... genera una guía remitente (tipo 09). No se necesita ningún campo adicional para diferenciarlos. POST /guias/enviar --- ## Idempotencia URL: https://docs.facturalo.pe/idempotencia Si tu cliente HTTP se cae a mitad de un envío o reintentas el mismo POST, Facturalo no debe emitir dos veces el mismo comprobante. Hay dos capas de protección. 1. Clave natural (serie + correlativo + tipo) Si ya existe un documento o guía con la misma empresa, entorno, tipo, serie y correlativo, el envío **no crea otro**: responde el estado actual del existente y marca la respuesta con el header `X-Idempotent-Replayed: true`. 2. Header Idempotency-Key (recomendado) Envía un identificador único de tu lado (por ejemplo el id de la orden en tu ERP) en el header `Idempotency-Key`. La primera respuesta exitosa (2xx) se guarda **24 horas**. El mismo key + el mismo cuerpo devuelve la respuesta original con `X-Idempotent-Replayed: true`. El mismo key con **otro** cuerpo responde `409`. cURL ```bash curl -X POST https://api.facturalo.pe/api/v3/documentos/enviar \ -H "Authorization: sk_live_…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: orden-1042" \ -d @factura.json ``` SDK Node.js ```ts await facturalo.documentos.enviar(documento, { idempotencyKey: "orden-1042", }); ``` SDK PHP ```php $facturalo->documentos->enviar($documento, webhook: false, establecimiento: null, idempotencyKey: 'orden-1042'); ``` Dónde aplica `POST /documentos/enviar` y `POST /guias/enviar`. También acepta `X-Idempotency-Key` o el campo `idempotencyKey` / `idempotency_key` en el JSON. Headers de respuesta Header | Significado `Idempotency-Key` | Eco de la clave que enviaste. `X-Idempotent-Replayed: true` | Se devolvió una respuesta ya conocida (replay), no una emisión nueva. `X-Idempotent-Replayed: false` | Primera vez que se guardó esa clave. --- ## Facturalo API URL: https://docs.facturalo.pe/introduccion API v3 API REST para emisión de comprobantes electrónicos ante SUNAT (Perú). Soporta Facturas, Boletas, Notas de Crédito/Débito y Guías de Remisión. Los cálculos de IGV, subtotales y totales son automáticos — solo envía el `precioUnitario` y el `tipoIgv`. - [Emitir factura](/documentos/factura/gravada) — `POST /documentos/enviar` - [Emitir boleta](/documentos/boleta/gravada) — `POST /documentos/enviar` - [Emitir guía](/guias/remitente-privado) — `POST /guias/enviar` - [SIRE — Ventas](/sire/ventas/periodos) — Registro de Ventas e Ingresos (RVIE) - [SIRE — Compras](/sire/compras/periodos) — Registro de Compras Electrónico (RCE) Idempotencia y webhooks - [Idempotencia](/idempotencia) — `Idempotency-Key` y clave natural para no emitir dos veces - [Webhooks](/webhooks) — Firma HMAC-SHA256 y hasta 5 reintentos automáticos - [Estado del servicio](https://status.facturalo.pe) — API, docs, web, webhooks y SUNAT Autenticación Hay dos tipos de token, ambos se envían en el header `Authorization`. El entorno (demo / producción) se detecta automáticamente del prefijo del token. - `user_sk_...` — Token de usuario — Crear y gestionar empresas y establecimientos. - `sk_test_...` — Token de empresa — Demo — Facturas/boletas en SUNAT Beta; guías en el simulador GRE de Facturalo (validación XSD/XSL real). - `sk_live_...` — Token de empresa — Producción — Documentos y guías en producción SUNAT. Headers de autenticación ```http // Token de empresa — documentos y guías Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx // Token de usuario — gestión de empresas y establecimientos Authorization: user_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Ejemplo rápido cURL — Factura normal ```bash curl -X POST https://api.facturalo.pe/api/v3/documentos/enviar \ -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "webhook": false, "documento": { "sunatTransaccion": "0101", "tipoComprobante": "01", "serie": "F001", "correlativo": "1", "fechaEmision": "2026-06-13", "moneda": "PEN", "formaPago": "CONTADO", "otrosCampos": [ { "label": "Cajero", "value": "Guillermo" }, { "label": "Método de pago", "value": "Yape" }, { "label": "Mesa", "value": "12" } ], "cliente": { "tipoDocumento": "6", "numeroDocumento": "20000000001", "denominacion": "EMPRESA S.A.C.", "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA" }, "items": [{ "unidadMedida": "NIU", "descripcion": "SERVICIO DE CONSULTORÍA", "cantidad": 1, "precioUnitario": 590, "tipoIgv": "10" }] } }' ``` Respuesta — 200 OK ```json { "success": true, "message": "La Factura numero F001-00000001 ha sido aceptada", "data": { "estado": "ACEPTADA", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "estado": "ACEPTADA", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Factura numero F001-00000001 ha sido aceptada", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr" }, "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=", "cadenaQr": "20601476551 | 01 | F001 | 00000001 | 720.00 | 4720.00 | 13/06/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |" } } ``` Características clave - **Cálculos automáticos** — Solo envía precioUnitario y tipoIgv por ítem. La API calcula IGV, subtotales y totales automáticamente. - **Entorno por token** — El entorno (demo / producción) se detecta del token. sk_test_ = demo, sk_live_ = producción. No existe parámetro de entorno. En demo, facturas → SUNAT Beta; guías → simulador GRE de Facturalo (SUNAT no tiene beta GRE pública). - **Síncrono o asíncrono** — Con "webhook": false (default) la respuesta incluye el resultado SUNAT. Con "webhook": true retorna EN_PROCESO y el resultado llega al webhook. - **Si SUNAT no responde** — El comprobante o guía queda en proceso: reintentos en cola (~30 min, hasta ~5 h) y, en producción, recuperación horaria de pendientes entre 07:00 y 00:00 (hora Lima). - **Archivos públicos** — Los endpoints /{id}.pdf, /{id}.xml y /{id}.cdr no requieren autenticación — son links compartibles directamente con el cliente. - **Respuesta estructurada** — Todas las respuestas exitosas siguen el mismo esquema: success, message, data. Dentro de data: estado, entorno, documento, sunat.notas, enlaces. Códigos de respuesta HTTP - **200** — OK — Petición exitosa - **201** — Created — Recurso creado (empresa, establecimiento) - **400** — Bad Request — Cuerpo de la petición mal formado o JSON inválido - **401** — Unauthorized — Token inválido o ausente - **403** — Forbidden — El token no tiene permisos para este recurso - **404** — Not Found — Recurso no encontrado - **422** — Unprocessable Entity — Errores de validación — revisa el campo errors - **429** — Too Many Requests — Límite de peticiones alcanzado — reintenta más tarde - **500** — Internal Server Error — Error interno del servidor --- ## Referencia de la API URL: https://docs.facturalo.pe/referencia El sidebar izquierdo es el índice de `https://api.facturalo.pe/api/v3`. No hay un host distinto para demo y producción: el entorno lo decide el token que envías. Guías o esta pestaña [Guías](/guia-rapida) te lleva de cero a tu primer comprobante aceptado. Aquí abres un endpoint concreto y ves sus campos, ejemplos de respuesta y el código para llamarlo. Secciones Sección | Para qué | Empieza por Cuenta | Empresas emisoras, sus tokens y establecimientos | [Listar empresas](/empresas) Facturas | Emitir facturas y sus notas de crédito y débito, un caso por página | [Factura gravada](/documentos/factura/gravada) Boletas | Emitir boletas y sus notas | [Boleta gravada](/documentos/boleta/gravada) Anular documento | Dar de baja facturas (RA) y boletas (RC) | [Anular documento](/documento/anular) Documentos | Consultar un comprobante con su detalle completo, su historial y listarlos | [Consultar](/documentos/consultar) Guía de remisión | Emitir guías remitente y transportista y consultarlas | [Remitente — público](/guias/remitente-publico) Webhook | Configurar tu URL, elegir eventos y ver los payloads | [Payload de eventos](/webhooks/payload) Consultas | RUC, DNI y tipo de cambio | [RUC](/consultas/ruc) SIRE | Registro de ventas (RVIE) y de compras (RCE) | [Periodos de ventas](/sire/ventas/periodos) Lo que se repite en todas las llamadas - **Autenticación:** el token va en el header `Authorization` sin `Bearer`. `user_sk_…` para la sección Cuenta; `sk_test_…` (demo) o `sk_live_…` (producción) para todo lo demás. Detalle en [Autenticación](/autenticacion). - **Formato de respuesta:** siempre `{ success, message, data }`. Los errores de validación responden `422` con `errors` por campo. - **Correlativos** a 8 dígitos en las respuestas (`00000001`), aunque los envíes sin ceros. - **Envío síncrono o con webhook:** con `webhook: false` (por defecto) la respuesta ya trae el resultado de SUNAT; con `webhook: true` responde `202 EN_PROCESO` y el resultado llega a tu webhook. - **Respuesta corta, consulta completa:** enviar devuelve solo la identificación del comprobante, el resultado de SUNAT, los enlaces (PDF, XML, CDR), `hash` y `cadenaQr`. El detalle completo se obtiene con `GET /documentos/{id}` o `GET /guias/{id}`. Base URL ```bash https://api.facturalo.pe/api/v3 ``` Tu primera factura Con un token `sk_test_…` esto emite una factura en demo. Todos los campos están explicados en Factura gravada. POST /documentos/enviar ```bash curl -s https://api.facturalo.pe/api/v3/documentos/enviar \ -H 'Authorization: sk_test_…' \ -H 'Content-Type: application/json' \ -d @factura.json ``` - [Factura gravada](/documentos/factura/gravada) — cuerpo completo, respuesta y errores de POST /documentos/enviar - [Estados](/estados) — qué significa cada estado de SUNAT y de Facturalo - [Errores](/errores) — códigos HTTP y errores de SUNAT más comunes --- ## SDKs oficiales URL: https://docs.facturalo.pe/sdks Los SDKs son clientes delgados sobre la API REST v3. Son solo para tu servidor: usan el token de la empresa (`sk_test_...` en demo, `sk_live_...` en producción), así que nunca los importes en el navegador. - Node.js: @facturalo-pe/node · npm. Node 18 o superior, con tipos de TypeScript. - PHP: facturalo-pe/facturalo-php · Composer. PHP 8.1 o superior, funciona con Laravel. Qué cubren Hay dos clientes, según el token. Los métodos tienen los mismos nombres que la API y son iguales en Node y PHP. - **FacturaloClient** (token de empresa): `documentos` (enviar, generarXml, consultar, buscar, listar, anular, reenviar, eventos, eliminar, descargar), `guias` (enviar, consultar, consultarTicket, eventos, listar, descargar), `consultas` (RUC, DNI, tipo de cambio, placa, SOAT, licencia), `webhooks` (listar, reenviar) y `sire.ventas` / `sire.compras`. - **FacturaloCuentaClient** (token de usuario `user_sk_...`): `empresas` (crear, actualizar, tokens, webhook y eventos) y `establecimientos`. Útil si tu software da de alta las empresas de tus clientes. - **Webhooks**: verificación de la firma `X-Facturalo-Firma` en tiempo constante, sobre el cuerpo crudo. Cómo se comportan Un rechazo de SUNAT no lanza excepción: vuelve con `estado: "RECHAZADA"` y el motivo en `sunat`. Las excepciones son para errores de la petición (validación, token, red). Sin `idempotencyKey`, los POST de envío no se reintentan solos. Con `idempotencyKey`, el SDK puede reintentar de forma segura ante 429/5xx; en el servidor la clave evita duplicados (ver [Idempotencia](/idempotencia)). ## Node.js npm ```bash npm install @facturalo-pe/node ``` Emitir una factura ```ts import { FacturaloClient } from "@facturalo-pe/node"; const facturalo = new FacturaloClient({ token: process.env.FACTURALO_TOKEN! }); const envio = await facturalo.documentos.enviar({ sunatTransaccion: "0101", tipoComprobante: "01", serie: "F001", correlativo: "1", fechaEmision: "2026-10-30", moneda: "PEN", formaPago: "CONTADO", cliente: { tipoDocumento: "6", numeroDocumento: "20000000001", denominacion: "EMPRESA S.A.C.", direccion: "AV. LIMA 123 - LIMA", }, items: [ { unidadMedida: "NIU", descripcion: "SERVICIO", cantidad: 1, precioUnitario: 118, tipoIgv: "10" }, ], }, { idempotencyKey: "orden-1042" }); if (envio.estado === "ACEPTADA") { console.log(envio.enlaces.pdf); } else { console.log(envio.sunat?.codigo, envio.sunat?.mensaje); } ``` Recibir un webhook (Express) ```ts import express from "express"; import { construirEventoWebhook } from "@facturalo-pe/node"; app.post("/webhooks/facturalo", express.raw({ type: "application/json" }), (req, res) => { const evento = construirEventoWebhook( req.body, req.header("X-Facturalo-Firma"), process.env.FACTURALO_WEBHOOK_SECRET!, ); // evento.evento, evento.documento, evento.sunat, evento.enlaces res.sendStatus(200); }); ``` ## PHP Composer ```bash composer require facturalo-pe/facturalo-php ``` Emitir una factura ```php documentos->enviar([ 'sunatTransaccion' => '0101', 'tipoComprobante' => '01', 'serie' => 'F001', 'correlativo' => '1', 'fechaEmision' => '2026-10-30', 'moneda' => 'PEN', 'formaPago' => 'CONTADO', 'cliente' => [ 'tipoDocumento' => '6', 'numeroDocumento' => '20000000001', 'denominacion' => 'EMPRESA S.A.C.', 'direccion' => 'AV. LIMA 123 - LIMA', ], 'items' => [ ['unidadMedida' => 'NIU', 'descripcion' => 'SERVICIO', 'cantidad' => 1, 'precioUnitario' => 118, 'tipoIgv' => '10'], ], ], webhook: false, establecimiento: null, idempotencyKey: 'orden-1042'); if ($envio['estado'] === 'ACEPTADA') { echo $envio['enlaces']['pdf']; } else { echo $envio['sunat']['mensaje'] ?? ''; } ``` Recibir un webhook (Laravel) ```php use Facturalo\Exception\FacturaloSignatureVerificationException; use Facturalo\Webhook; Route::post('/webhooks/facturalo', function (Request $request) { try { $evento = Webhook::construirEvento( $request->getContent(), $request->header('X-Facturalo-Firma'), config('services.facturalo.webhook_secret'), ); } catch (FacturaloSignatureVerificationException) { abort(401); } // $evento['evento'], $evento['documento'], $evento['sunat'], $evento['enlaces'] return response()->noContent(); }); ``` Cada página de la [referencia](/referencia) muestra su ejemplo con el SDK en las pestañas Node y PHP. El código está en GitHub: [facturalo-node](https://github.com/facturalo-pe/facturalo-node) y [facturalo-php](https://github.com/facturalo-pe/facturalo-php). Siguiente - [Guía rápida](/guia-rapida) — de cero a tu primera factura en demo - [Payload de eventos](/webhooks/payload) — qué llega a tu webhook en cada evento - [Plugins · WooCommerce](/woocommerce) — facturación en tu tienda sin programar --- ## SIRE URL: https://docs.facturalo.pe/sire El Sistema Integrado de Registros Electrónicos (SIRE) permite gestionar el **Registro de Ventas e Ingresos (RVIE)** y el **Registro de Compras Electrónico (RCE)** directamente en SUNAT, sin necesidad de ingresar al portal manualmente. **Requisito previo:** Para usar cualquier endpoint de SIRE debes configurar las credenciales SOL de tu empresa en la sección de datos de la empresa: **Client ID**, **Client Secret**, **Usuario SOL** y **Clave SOL**. Sin estas credenciales los endpoints retornarán un error de autenticación. Todos los endpoints de SIRE operan directamente contra producción SUNAT — no existe entorno de pruebas. Puedes usar tu token `sk_test_*` o `sk_live_*` indistintamente. ¿Cómo funciona la conexión con SUNAT? Facturalo se conecta automáticamente a SUNAT usando tus credenciales SOL cada vez que consumes un endpoint de SIRE. No necesitas gestionar tokens ni sesiones — solo asegúrate de tener las credenciales configuradas correctamente en tu empresa. Ventas — RVIE Método | Endpoint | Descripción GET | [Periodos RVIE](/sire/ventas/periodos) | Lista períodos del padrón de omisos GET | [Resumen de inconsistencias](/sire/ventas/resumen) | Totales y calidad de la propuesta GET | [Resumen de comprobantes](/sire/ventas/resumen-comprobantes) | Desglose por Facturas, Boletas, NC, ND GET | [Comprobantes](/sire/ventas/comprobantes) | Detalle de comprobantes de la propuesta GET | [Inconsistencias](/sire/ventas/inconsistencias) | Listado de inconsistencias del período GET | [Inc. por comprobante](/sire/ventas/inconsistencia-por-comprobante) | Detalle del punto rojo de un comprobante POST | [Aceptar propuesta](/sire/ventas/aceptar-propuesta) | Acepta la propuesta SUNAT tal cual GET | [Exportar propuesta](/sire/ventas/exportar) | Genera ticket para descargar TXT/ZIP GET | [Descargar propuesta](/sire/ventas/descargar-ticket) | Polling y descarga del archivo ZIP GET | [Preliminares registrados](/sire/ventas/preliminares) | Obtiene id para revertir PUT | [Eliminar preliminar registrado](/sire/ventas/eliminar-preliminar-registrado) | Revierte a Propuesta desde Preliminar Registrado PUT | [Eliminar preliminar](/sire/ventas/eliminar-preliminar) | Revierte a Propuesta desde Preliminar (flujo TUS.IO) POST | [Iniciar conciliación](/sire/ventas/conciliar) | Compara propuesta SUNAT vs Facturalo Compras — RCE Método | Endpoint | Descripción GET | [Periodos RCE](/sire/compras/periodos) | Lista períodos del padrón de omisos GET | [Resumen de inconsistencias](/sire/compras/resumen) | Totales y calidad de la propuesta GET | [Resumen de comprobantes](/sire/compras/resumen-comprobantes) | Desglose por Facturas, Liquidaciones, NC, ND GET | [Comprobantes](/sire/compras/comprobantes) | Detalle de comprobantes de la propuesta GET | [Inconsistencias](/sire/compras/inconsistencias) | Listado de inconsistencias del período GET | [Inc. por comprobante](/sire/compras/inconsistencia-por-comprobante) | Detalle del punto rojo de un comprobante POST | [Aceptar propuesta](/sire/compras/aceptar-propuesta) | Acepta la propuesta SUNAT tal cual GET | [Exportar propuesta](/sire/compras/exportar) | Genera ticket para descargar TXT/ZIP GET | [Descargar propuesta](/sire/compras/descargar-ticket) | Polling y descarga del archivo ZIP GET | [Preliminares registrados](/sire/compras/preliminares) | Obtiene id para revertir PUT | [Eliminar preliminar registrado](/sire/compras/eliminar-preliminar-registrado) | Revierte a Propuesta desde Preliminar Registrado PUT | [Eliminar preliminar](/sire/compras/eliminar-preliminar) | Revierte a Propuesta desde Preliminar (flujo TUS.IO) POST | [Iniciar conciliación](/sire/compras/conciliar) | Compara propuesta SUNAT vs Facturalo Errores comunes HTTP | Causa 200 | Respuesta siempre 200, incluso en errores de negocio SUNAT 401 | Token Facturalo inválido o expirado 502 | SUNAT SIRE no respondió correctamente 500 | Error interno inesperado --- ## Aceptar propuesta URL: https://docs.facturalo.pe/sire/compras/aceptar-propuesta Endpoint: POST https://api.facturalo.pe/api/v3/sire/compras/{periodo}/aceptar-propuesta Acepta la propuesta de compras de SUNAT tal cual y avanza el período a Preliminar Registrado. Nota: ¡Atención! Esta acción se ejecuta directamente en SUNAT y mueve el período a Preliminar Registrado. Si necesitas revertirlo, usa el endpoint Eliminar preliminar registrado antes de que el período avance a un estado irreversible. POST /sire/compras/{periodo}/aceptar-propuesta --- ## Comprobantes URL: https://docs.facturalo.pe/sire/compras/comprobantes Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/comprobantes Lista paginada de los comprobantes de compras del período. Sin fechas incluye también los emitidos en meses anteriores que SUNAT incorporó al período. Con fecEmisionIni y fecEmisionFin queda el mismo recorte que el filtro Fecha de emisión del portal. GET /sire/compras/{periodo}/comprobantes --- ## Iniciar conciliación URL: https://docs.facturalo.pe/sire/compras/conciliar Endpoint: POST https://api.facturalo.pe/api/v3/sire/compras/{periodo}/conciliar Compara los comprobantes de compras de SUNAT contra los registrados en Facturalo e identifica diferencias de estado y montos. Nota: No requiere body. Retorna de inmediato un conciliacionId — úsalo en el endpoint Consultar conciliación para obtener el resultado cuando el proceso termine. POST /sire/compras/{periodo}/conciliar --- ## Descargar propuesta URL: https://docs.facturalo.pe/sire/compras/descargar-ticket Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/tickets/{numTicket}/descargar Descarga el archivo de la propuesta generado con Exportar propuesta. Consulta el estado hasta que el archivo en Base64 esté disponible. Nota: Cuando expirado: true, vuelve a llamar GET /sire/compras/ {periodo} /exportar para obtener un nuevo numTicket. GET /sire/compras/tickets/{numTicket}/descargar --- ## Eliminar preliminar URL: https://docs.facturalo.pe/sire/compras/eliminar-preliminar Endpoint: PUT https://api.facturalo.pe/api/v3/sire/compras/{periodo}/eliminar-preliminar Revierte el período de estado Preliminar a Propuesta. PUT /sire/compras/{periodo}/eliminar-preliminar --- ## Eliminar preliminar registrado URL: https://docs.facturalo.pe/sire/compras/eliminar-preliminar-registrado Endpoint: PUT https://api.facturalo.pe/api/v3/sire/compras/{periodo}/eliminar-preliminar-registrado Deshace la acción de Aceptar propuesta y regresa el período al estado Propuesta. PUT /sire/compras/{periodo}/eliminar-preliminar-registrado --- ## Exportar propuesta URL: https://docs.facturalo.pe/sire/compras/exportar Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/exportar Genera un ticket para exportar la propuesta de compras. El archivo estará disponible en Base64 al consultar el ticket. Nota: Con el numTicket recibido, consulta el endpoint Descargar propuesta hasta que el archivo esté listo para descargar. GET /sire/compras/{periodo}/exportar --- ## Inconsistencias por comprobante URL: https://docs.facturalo.pe/sire/compras/inconsistencia-por-comprobante Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/inconsistencia-por-comprobante Detalle al hacer clic en el punto rojo (Inc.) de un comprobante en la propuesta RCE. Usa el codCar del listado de comprobantes. GET /sire/compras/{periodo}/inconsistencia-por-comprobante --- ## Inconsistencias del período URL: https://docs.facturalo.pe/sire/compras/inconsistencias Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/inconsistencias Lista paginada de comprobantes con inconsistencias SUNAT en el RCE. Equivale a la pestaña Inconsistencias del portal. GET /sire/compras/{periodo}/inconsistencias --- ## Periodos URL: https://docs.facturalo.pe/sire/compras/periodos Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/periodos Lista los períodos tributarios de compras disponibles y su estado ante SUNAT. Nota: Requisito previo: Para usar SIRE debes configurar las credenciales SOL de tu empresa: Client ID, Client Secret, Usuario SOL y Clave SOL. Puedes hacerlo en la sección de datos de tu empresa. Sin estas credenciales el endpoint retornará un error de autenticación. GET /sire/compras/periodos --- ## Preliminares registrados URL: https://docs.facturalo.pe/sire/compras/preliminares Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/preliminares Consulta si el período tiene un preliminar registrado. Úsalo para obtener el id necesario antes de revertir con Eliminar preliminar registrado. Nota: Usa el id y codTipoRegistro exactos de la respuesta al llamar Eliminar preliminar registrado. GET /sire/compras/{periodo}/preliminares --- ## Resumen de inconsistencias URL: https://docs.facturalo.pe/sire/compras/resumen Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/resumen Muestra el porcentaje de comprobantes con errores en la propuesta. Revísalo antes de aceptar para asegurarte de que la propuesta está limpia. GET /sire/compras/{periodo}/resumen --- ## Resumen de comprobantes URL: https://docs.facturalo.pe/sire/compras/resumen-comprobantes Endpoint: GET https://api.facturalo.pe/api/v3/sire/compras/{periodo}/resumen-comprobantes Desglose de la propuesta por tipo de comprobante (Facturas, Liquidaciones, NC, ND) con totales de base imponible, IGV y monto. GET /sire/compras/{periodo}/resumen-comprobantes --- ## Consultar conciliación URL: https://docs.facturalo.pe/sire/conciliacion Endpoint: GET https://api.facturalo.pe/api/v3/sire/conciliaciones/{conciliacionId} Consulta el estado de una conciliación SIRE iniciada previamente con POST /conciliar. Hacer polling cada 10-15 segundos hasta COMPLETADO o ERROR. Nota: Este endpoint sirve tanto para conciliaciones de ventas como de compras — el campo libro indica cuál es. GET /sire/conciliaciones/{conciliacionId} --- ## Aceptar propuesta URL: https://docs.facturalo.pe/sire/ventas/aceptar-propuesta Endpoint: POST https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/aceptar-propuesta Acepta la propuesta de ventas de SUNAT tal cual y avanza el período a Preliminar Registrado. Nota: ¡Atención! Esta acción se ejecuta directamente en SUNAT y mueve el período a Preliminar Registrado. Si necesitas revertirlo, usa el endpoint Eliminar preliminar registrado antes de que el período avance a un estado irreversible. POST /sire/ventas/{periodo}/aceptar-propuesta --- ## Comprobantes URL: https://docs.facturalo.pe/sire/ventas/comprobantes Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/comprobantes Lista paginada de los comprobantes de ventas incluidos en la propuesta SUNAT para el período. GET /sire/ventas/{periodo}/comprobantes --- ## Iniciar conciliación URL: https://docs.facturalo.pe/sire/ventas/conciliar Endpoint: POST https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/conciliar Compara los comprobantes de ventas de SUNAT contra los registrados en Facturalo e identifica diferencias de estado y montos. Nota: No requiere body. Retorna de inmediato un conciliacionId — úsalo en el endpoint Consultar conciliación para obtener el resultado cuando el proceso termine. POST /sire/ventas/{periodo}/conciliar --- ## Descargar propuesta URL: https://docs.facturalo.pe/sire/ventas/descargar-ticket Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/tickets/{numTicket}/descargar Descarga el archivo de la propuesta generado con Exportar propuesta. Consulta el estado hasta que el archivo en Base64 esté disponible. Nota: Cuando expirado: true, vuelve a llamar GET /sire/ventas/ {periodo} /exportar para obtener un nuevo numTicket. GET /sire/ventas/tickets/{numTicket}/descargar --- ## Eliminar preliminar URL: https://docs.facturalo.pe/sire/ventas/eliminar-preliminar Endpoint: PUT https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/eliminar-preliminar Revierte el período de estado Preliminar a Propuesta. PUT /sire/ventas/{periodo}/eliminar-preliminar --- ## Eliminar preliminar registrado URL: https://docs.facturalo.pe/sire/ventas/eliminar-preliminar-registrado Endpoint: PUT https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/eliminar-preliminar-registrado Deshace la acción de Aceptar propuesta y regresa el período al estado Propuesta. PUT /sire/ventas/{periodo}/eliminar-preliminar-registrado --- ## Exportar propuesta URL: https://docs.facturalo.pe/sire/ventas/exportar Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/exportar Genera un ticket para exportar la propuesta de ventas. El archivo estará disponible en Base64 al consultar el ticket. Nota: Con el numTicket recibido, consulta el endpoint Descargar propuesta hasta que el archivo esté listo para descargar. GET /sire/ventas/{periodo}/exportar --- ## Inconsistencias por comprobante URL: https://docs.facturalo.pe/sire/ventas/inconsistencia-por-comprobante Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/inconsistencia-por-comprobante Detalle al hacer clic en el punto rojo (Inc.) de un comprobante en la propuesta RVIE. Usa el codCar del listado de comprobantes. GET /sire/ventas/{periodo}/inconsistencia-por-comprobante --- ## Inconsistencias del período URL: https://docs.facturalo.pe/sire/ventas/inconsistencias Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/inconsistencias Lista paginada de comprobantes con inconsistencias SUNAT en el RVIE. Si el período no tiene fase o no hay inconsistencias (código SUNAT 2001), responde lista vacía. GET /sire/ventas/{periodo}/inconsistencias --- ## Periodos URL: https://docs.facturalo.pe/sire/ventas/periodos Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/periodos Lista los períodos tributarios de ventas disponibles y su estado ante SUNAT. Nota: Requisito previo: Para usar SIRE debes configurar las credenciales SOL de tu empresa: Client ID, Client Secret, Usuario SOL y Clave SOL. Puedes hacerlo en la sección de datos de tu empresa. Sin estas credenciales el endpoint retornará un error de autenticación. GET /sire/ventas/periodos --- ## Preliminares registrados URL: https://docs.facturalo.pe/sire/ventas/preliminares Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/preliminares Consulta si el período tiene un preliminar registrado. Úsalo para obtener el id necesario antes de revertir con Eliminar preliminar registrado. Nota: Usa el id y codTipoRegistro exactos de la respuesta al llamar Eliminar preliminar registrado. GET /sire/ventas/{periodo}/preliminares --- ## Resumen de inconsistencias URL: https://docs.facturalo.pe/sire/ventas/resumen Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/resumen Muestra el porcentaje de comprobantes con errores en la propuesta. Revísalo antes de aceptar para asegurarte de que la propuesta está limpia. GET /sire/ventas/{periodo}/resumen --- ## Resumen de comprobantes URL: https://docs.facturalo.pe/sire/ventas/resumen-comprobantes Endpoint: GET https://api.facturalo.pe/api/v3/sire/ventas/{periodo}/resumen-comprobantes Desglose de la propuesta por tipo de comprobante (Facturas, Boletas, NC, ND) con totales de base imponible, IGV y monto. Nota: Solo aparecen los tipos de comprobante que tienen datos en ese período. Las Notas de Crédito tienen montos negativos. GET /sire/ventas/{periodo}/resumen-comprobantes --- ## Bienes y servicios sujetos a detracción URL: https://docs.facturalo.pe/tablas/detracciones Catálogo 54 SUNAT. Tipo de bien o servicio sujeto a detracción. Se envía en el campo detraccion.tipo del documento. Campo en la API: `detraccion.tipo` Código | Nombre `001` | Azúcar y melaza de caña `002` | Arroz `003` | Alcohol etílico `004` | Recursos hidrobiológicos `005` | Maíz amarillo duro `007` | Caña de azúcar `008` | Madera `009` | Arena y piedra `010` | Residuos, subproductos, desechos, recortes y desperdicios `011` | Bienes gravados con el IGV, o renuncia a la exoneración `012` | Intermediación laboral y tercerización `013` | Animales vivos `014` | Carnes y despojos comestibles `015` | Abonos, cueros y pieles de origen animal `016` | Aceite de pescado `017` | Harina, polvo y pellets de pescado, crustáceos, moluscos y demás invertebrados acuáticos `019` | Arrendamiento de bienes muebles `020` | Mantenimiento y reparación de bienes muebles `021` | Movimiento de carga `022` | Otros servicios empresariales `023` | Leche `024` | Comisión mercantil `025` | Fabricación de bienes por encargo `026` | Servicio de transporte de personas `027` | Servicio de transporte de carga `028` | Transporte de pasajeros `030` | Contratos de construcción `031` | Oro gravado con el IGV `032` | Páprika y otros frutos de los géneros capsicum o pimienta `034` | Minerales metálicos no auríferos `035` | Bienes exonerados del IGV `036` | Oro y demás minerales metálicos exonerados del IGV `037` | Demás servicios gravados con el IGV `039` | Minerales no metálicos `040` | Bien inmueble gravado con IGV `041` | Plomo `099` | Ley 30737 --- ## Medios de pago URL: https://docs.facturalo.pe/tablas/medios-pago Catálogo 59 SUNAT. Medio de pago utilizado en la operación. Se envía en el campo medioPago de la detracción. Campo en la API: `detraccion.medioPago` Código | Nombre `001` | Depósito en cuenta `002` | Giro `003` | Transferencia de fondos `004` | Orden de pago `005` | Tarjeta de débito `006` | Tarjeta de crédito emitida en el país por empresa del sistema financiero `007` | Cheque con cláusula NO NEGOCIABLE / INTRANSFERIBLE `008` | Efectivo — sin obligación de usar medio de pago `009` | Efectivo — demás casos `010` | Medios de pago usados en comercio exterior `011` | Documentos emitidos por EDPYMES y cooperativas de ahorro `012` | Tarjeta de crédito emitida por empresa no perteneciente al sistema financiero `013` | Tarjetas de crédito emitidas en el exterior por empresas bancarias no domiciliadas `101` | Transferencias — Comercio exterior `102` | Cheques bancarios — Comercio exterior `103` | Orden de pago simple — Comercio exterior `104` | Orden de pago documentario — Comercio exterior `105` | Remesa simple — Comercio exterior `106` | Remesa documentaria — Comercio exterior `107` | Carta de crédito simple — Comercio exterior `108` | Carta de crédito documentario — Comercio exterior `999` | Otros medios de pago --- ## Modalidad de transporte URL: https://docs.facturalo.pe/tablas/modalidad-transporte Catálogo 18 SUNAT. Define si el traslado es en transporte público o privado. Se envía en el campo modalidadTransporte de la guía de remisión. Campo en la API: `guia.modalidadTransporte` Código | Nombre | Nota `01` | Transporte público | El transportista es una empresa de terceros. Se usa tipoComprobante: 09 (remitente). `02` | Transporte privado | El remitente traslada con sus propios vehículos. Se usa tipoComprobante: 09 con datosTransportista. --- ## Monedas URL: https://docs.facturalo.pe/tablas/monedas Monedas aceptadas por la API. Se envía en el campo moneda del documento. Campo en la API: `documento.moneda` Código | Nombre | Nota `PEN` | Sol peruano | Moneda por defecto. `USD` | Dólar americano | SUNAT requiere el tipo de cambio vigente del día de emisión. `EUR` | Euro | --- ## Motivo de traslado URL: https://docs.facturalo.pe/tablas/motivo-traslado Catálogo 20 SUNAT. Motivo por el que se realiza el traslado de bienes. Se envía en el campo motivoTraslado de la guía de remisión. Campo en la API: `guia.motivoTraslado` Código | Nombre `01` | Venta `02` | Compra `03` | Venta con entrega a terceros `04` | Traslado entre establecimientos de la misma empresa `05` | Consignación `06` | Devolución `07` | Recojo de bienes transformados `08` | Importación `09` | Exportación `13` | Otros `14` | Venta sujeta a confirmación del comprador `17` | Traslado de bienes para transformación `18` | Traslado emisor itinerante CP --- ## Tipos de nota de crédito URL: https://docs.facturalo.pe/tablas/notas-credito Motivos válidos para emitir una nota de crédito (tipoComprobante: 07). Se envía en el campo nota.tipo del documento. Campo en la API: `nota.tipo` Código | Nombre `01` | Anulación de la operación `02` | Anulación por error en el RUC `03` | Corrección por error en la descripción `04` | Descuento global `05` | Descuento por ítem `06` | Devolución total `07` | Devolución por ítem `08` | Bonificación `09` | Disminución en el valor `10` | Otros conceptos `11` | Ajustes de operaciones de exportación `12` | Ajustes afectos al IVAP `13` | Corrección o modificación del monto neto pendiente de pago y/o fechas de vencimiento --- ## Tipos de nota de débito URL: https://docs.facturalo.pe/tablas/notas-debito Motivos válidos para emitir una nota de débito (tipoComprobante: 08). Se envía en el campo nota.tipo del documento. Campo en la API: `nota.tipo` Código | Nombre `01` | Intereses por mora `02` | Aumento de valor `03` | Penalidades / otros conceptos `11` | Ajustes de operaciones de exportación `12` | Ajustes afectos al IVAP --- ## Tipos de comprobante URL: https://docs.facturalo.pe/tablas/tipos-comprobante Catálogo de tipos de comprobante electrónico SUNAT. Se envía en el campo tipoComprobante del documento. Campo en la API: `tipoComprobante` Código | Nombre `01` | Factura electrónica `03` | Boleta de venta electrónica `07` | Nota de crédito electrónica `08` | Nota de débito electrónica `09` | Guía de remisión remitente `31` | Guía de remisión transportista --- ## Tipos de documento del cliente URL: https://docs.facturalo.pe/tablas/tipos-documento Catálogo de tipos de documento de identidad del adquirente. Se envía en el campo tipoDocumento del objeto cliente. Campo en la API: `cliente.tipoDocumento` Código | Nombre | Nota `0` | Doc. tributario no domiciliado sin RUC | Para clientes extranjeros sin RUC. Máx. 15 caracteres. `1` | DNI | 8 dígitos exactos. `4` | Carnet de extranjería | Máx. 12 caracteres. `6` | RUC | 11 dígitos. Requerido para facturas. `7` | Pasaporte | Máx. 12 caracteres. `A` | Cédula diplomática de identidad | Máx. 15 caracteres. `B` | Doc. de identidad país de residencia (no domiciliado) | Máx. 15 caracteres. `C` | Tax ID / TIN (persona natural) | `D` | IN (persona jurídica) | `E` | TAM — Tarjeta andina de migración | `F` | PTP — Permiso temporal de permanencia | `G` | Salvoconducto | --- ## Tipos de IGV URL: https://docs.facturalo.pe/tablas/tipos-igv Catálogo de afectación al IGV por ítem. Se envía en el campo tipoIgv de cada elemento del array items. Campo en la API: `items[].tipoIgv` Código | Nombre | Nota `10` | Gravado — Operación onerosa | Tasa estándar 18%. El más común. `11` | Gravado — Retiro por premio | `12` | Gravado — Retiro por donación | `13` | Gravado — Retiro | `14` | Gravado — Retiro por publicidad | `15` | Gravado — Bonificaciones | `16` | Gravado — Retiro por entrega a trabajadores | `17` | Gravado — IVAP | `20` | Exonerado — Operación onerosa | Apéndice I de la Ley del IGV. `21` | Exonerado — Transferencia gratuita | `30` | Inafecto — Operación onerosa | No afecto al IGV por ley. `31` | Inafecto — Retiro por bonificación | `32` | Inafecto — Retiro | `33` | Inafecto — Retiro por muestras médicas | `34` | Inafecto — Retiro por convenio colectivo | `35` | Inafecto — Retiro por premio | `36` | Inafecto — Retiro por publicidad | `37` | Inafecto — Transferencia gratuita | `40` | Exportación de bienes o servicios | IGV 0%. Usar con sunatTransaccion: 0200. --- ## Tipos de operación SUNAT URL: https://docs.facturalo.pe/tablas/tipos-operacion Código de operación requerido por SUNAT. Se envía en el campo sunatTransaccion del documento. Campo en la API: `documento.sunatTransaccion` Código | Nombre | Nota `0101` | Venta interna | El más común. Facturas y boletas gravadas, exoneradas, inafectas. `0102` | Venta interna — anticipos | `0104` | Venta interna — anticipos (primer pago) | Usar para la primera factura/boleta de anticipo. `0200` | Exportación | Usar con tipoIgv: 40 y moneda: USD. `0401` | Ventas no domiciliados que no califican como exportación | `1001` | Operación sujeta a detracción | Requiere el objeto detraccion en el payload. `1002` | Detracción — Recursos hidrobiológicos | `1003` | Detracción — Servicios de transporte de pasajeros | `1004` | Detracción — Servicios de transporte de carga | `2001` | Operación sujeta a percepción | Requiere el objeto retencion en el payload. --- ## Unidades de medida URL: https://docs.facturalo.pe/tablas/unidades-medida Códigos de unidad de medida aceptados por SUNAT. Se envía en el campo unidadMedida de cada ítem. Campo en la API: `items[].unidadMedida` Código | Nombre | Nota `NIU` | Unidad | Para productos unitarios. `ZZ` | Unidad mutualmente definida | Para servicios. `BX` | Caja | `PK` | Paquete | `KT` | Kit | `KGM` | Kilogramo | También usado como unidad de peso en guías de remisión. `TNE` | Tonelada métrica | Usado en guías de remisión. `GLI` | Galón imperial | `LTR` | Litro | `MTR` | Metro | `MTQ` | Metro cúbico | `MTK` | Metro cuadrado | `HUR` | Hora | `DAY` | Día | --- ## Webhooks URL: https://docs.facturalo.pe/webhooks Facturalo puede notificar a tu servidor en tiempo real cuando ocurre un evento importante. Configura una URL por entorno y tu servidor recibirá un POST con el payload del evento. ¿Qué eventos envía Facturalo via webhook? Evento | Descripción | Activo por defecto [documento.sunat.respuesta](/webhooks/payload/sunat-respuesta) | SUNAT procesó el documento (aceptado o rechazado). | Activo [documento.anulado](/webhooks/payload/anulado) | La baja del documento fue aceptada por SUNAT. | Activo [documento.correo.enviado](/webhooks/payload/correo-enviado) | El PDF fue enviado al correo del cliente. | Inactivo [documento.correo.fallido](/webhooks/payload/correo-fallido) | El envío del correo al cliente falló. | Inactivo [guia.sunat.respuesta](/webhooks/payload/guia-respuesta) | SUNAT procesó la guía de remisión. | Activo [documento.error](/webhooks/payload/error) | Error interno al generar o enviar el documento. | Activo ¿Cómo verificar la firma HMAC de un webhook? Cada evento incluye el header `X-Facturalo-Firma` con un HMAC-SHA256 del body usando tu `webhookSecret`. Verifica siempre la firma antes de procesar el evento. X-Facturalo-Firma: {hmac-sha256} Ejemplos de verificación de firma en PHP y Node.js: ver [Webhooks](/webhooks). ¿Qué pasa si mi servidor no responde el webhook? Si tu servidor no responde con un código `2xx` (o hay timeout/error de red), Facturalo **reintenta automáticamente hasta 5 veces** con backoff: 30 s, 1 min, 2 min, 5 min y 10 min. El mismo `id` del evento se reutiliza en todos los intentos para que puedas deduplicar. Headers útiles: `X-Facturalo-Evento-Id` y `X-Facturalo-Intento`. Si tras los 5 intentos sigue fallando, el evento queda como fallido y puedes reenviarlo manualmente con [POST /webhooks/{eventoId}/reenviar](/webhooks/reenviar). El payload reenviado es el original guardado en base de datos. Estado del servicio La disponibilidad de la API, docs, web, cola de webhooks y SUNAT se publica en [status.facturalo.pe](https://status.facturalo.pe). --- ## Actualizar webhook URL: https://docs.facturalo.pe/webhooks/actualizar Endpoint: PATCH https://api.facturalo.pe/api/v3/empresas/{uuid}/webhook Configura las URLs de webhook para cada entorno. Los eventos se envían como `POST` con el body del documento procesado. Usa el `webhookSecret` para verificar la autenticidad del evento en tu servidor. PATCH /empresas/{uuid}/webhook --- ## Listar eventos webhook URL: https://docs.facturalo.pe/webhooks/eventos Endpoint: GET https://api.facturalo.pe/api/v3/empresas/{uuid}/webhook/eventos Retorna todos los eventos disponibles y su estado (activo/inactivo) por entorno. GET /empresas/{uuid}/webhook/eventos --- ## Activar / desactivar eventos URL: https://docs.facturalo.pe/webhooks/eventos/actualizar Endpoint: PATCH https://api.facturalo.pe/api/v3/empresas/{uuid}/webhook/eventos Activa o desactiva eventos webhook por entorno. Solo se modifican los eventos enviados en el payload — los demás permanecen igual. PATCH /empresas/{uuid}/webhook/eventos --- ## Listar webhooks enviados URL: https://docs.facturalo.pe/webhooks/listar Endpoint: GET https://api.facturalo.pe/api/v3/webhooks Retorna el historial de webhooks enviados. Filtra por estado o evento para encontrar envíos fallidos y reenviarlos. GET /webhooks --- ## Payload de eventos URL: https://docs.facturalo.pe/webhooks/payload Tu endpoint recibe un `POST` con `Content-Type: application/json` y el header de firma: X-Facturalo-Firma: {hmac-sha256} Estructura base Todos los eventos comparten estos campos raíz. El objeto principal (`documento` o `guia`) solo identifica el comprobante: `id`, `serie`, `correlativo` y `tipo`. Para el detalle completo usa `GET /documentos/{id}` o `GET /guias/{id}`. Estructura base ```json { "id": "uuid-unico-del-evento", "evento": "documento.sunat.respuesta", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento | guia": { "...": "objeto principal — depende del evento" }, "sunat | anulacion | correo | error": { "...": "datos adicionales — depende del evento" } } ``` Verificar firma PHP ```php $firma = hash_hmac('sha256', $rawBody, $webhookSecret); if (!hash_equals($firma, $request->header('X-Facturalo-Firma'))) { abort(401, 'Firma inválida'); } ``` Selecciona un evento en el sidebar para ver su payload completo. --- ## documento.anulado URL: https://docs.facturalo.pe/webhooks/payload/anulado SUNAT recibió la baja del documento. Se envía al anular con `POST /documentos/anular` y también cuando un resumen pendiente se confirma después. Campo | Descripción `anulacion.estado` | `ANULADA` si SUNAT ya confirmó la baja; `EN_PROCESO` si el ticket aún se está procesando. `anulacion.tipo` | `RA` (Comunicación de Baja, facturas) o `RC` (Resumen Diario, boletas). `anulacion.resumen` | Nombre del resumen enviado a SUNAT. `anulacion.ticket` | Ticket que SUNAT asignó al resumen. `anulacion.motivo` / `anulacion.fecha` | Motivo indicado al anular y fecha de la comunicación. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "documento.anulado", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "anulacion": { "estado": "ANULADA", "tipo": "RA", "resumen": "20601476551-RA-20260614-1", "ticket": "1781234567890", "motivo": "Error en el monto", "fecha": "2026-06-14" } } ``` --- ## documento.correo.enviado URL: https://docs.facturalo.pe/webhooks/payload/correo-enviado El PDF del comprobante se envió al correo del cliente. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "documento.correo.enviado", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "correo": { "email": "cliente@empresa.com", "estado": "enviado", "error": null } } ``` --- ## documento.correo.fallido URL: https://docs.facturalo.pe/webhooks/payload/correo-fallido No se pudo enviar el correo al cliente después de todos los reintentos. El motivo está en `correo.error`. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "documento.correo.fallido", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "correo": { "email": "cliente@empresa.com", "estado": "fallido", "error": "Connection could not be established with host smtp.empresa.com" } } ``` --- ## documento.error URL: https://docs.facturalo.pe/webhooks/payload/error El procesamiento en segundo plano falló después de todos los reintentos. Para guías, el bloque se llama `guia` y trae solo `serie` y `correlativo`. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "documento.error", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "error": { "mensaje": "No se pudo conectar con SUNAT." } } ``` --- ## guia.sunat.respuesta URL: https://docs.facturalo.pe/webhooks/payload/guia-respuesta SUNAT respondió una guía que enviaste con `webhook: true`. El contenido es el mismo que la respuesta síncrona de `POST /guias/enviar`. El bloque `guia` solo identifica la guía. El detalle completo (traslado, transportista, puntos de partida y llegada, ítems…) se obtiene con `GET /guias/{id}`. - `guia.tipo`: `GUIA_REMISION` (09) o `GUIA_TRANSPORTISTA` (31). - `enlaces.cdr` solo viene cuando la guía fue aceptada u observada. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "guia.sunat.respuesta", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "guia": { "id": "76198000-6805-11f1-8869-aba1fc00c9df", "estado": "ACEPTADA", "serie": "T001", "correlativo": "00000001", "tipo": "GUIA_REMISION" }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Guia de Remision ha sido aceptada.", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/guias/76198000-6805-11f1-8869-aba1fc00c9df.pdf", "xml": "https://api.facturalo.pe/api/v3/guias/76198000-6805-11f1-8869-aba1fc00c9df.xml", "cdr": "https://api.facturalo.pe/api/v3/guias/76198000-6805-11f1-8869-aba1fc00c9df.cdr" }, "hash": "MdDtBpTOHVP7B37uwiBvuaCG1H4=", "cadenaQr": "20601476551 | 09 | T001 | 00000001 | 14/06/2026 | 20100070970 | MdDtBpTOHVP7B37uwiBvuaCG1H4= |" } ``` --- ## documento.sunat.respuesta URL: https://docs.facturalo.pe/webhooks/payload/sunat-respuesta SUNAT respondió un documento que enviaste con `webhook: true`. El contenido es el mismo que la respuesta síncrona de `POST /documentos/enviar`. El bloque `documento` solo identifica el comprobante. El detalle completo (cliente, totales, ítems, `otrosCampos`…) se obtiene con `GET /documentos/{id}`. - `sunat.estado`: `ACEPTADA`, `OBSERVADA` o `RECHAZADA`. - `enlaces.cdr` solo viene cuando el documento fue aceptado. - `hash` y `cadenaQr` sirven para imprimir el QR del comprobante. - También se envía cuando una boleta queda aceptada a través de un Resumen Diario: en ese caso llega con `sunat.estado: ACEPTADA` cuando SUNAT confirma el resumen. Payload ```json { "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00", "evento": "documento.sunat.respuesta", "timestamp": "2026-06-14T10:30:00-05:00", "entorno": "demo", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "estado": "ACEPTADA", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Factura numero F001-00000001, ha sido aceptada", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr" }, "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=", "cadenaQr": "20601476551 | 01 | F001 | 00000001 | 720.00 | 4720.00 | 13/06/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |" } ``` --- ## Reenviar webhook fallido URL: https://docs.facturalo.pe/webhooks/reenviar Endpoint: POST https://api.facturalo.pe/api/v3/webhooks/{eventoId}/reenviar Reenvía el payload original de un webhook fallido. Solo acepta eventos con tipo `documento.webhook.fallido` o `documento.webhook.reintento`. Se reenvía el payload exacto guardado en base de datos. POST /webhooks/{eventoId}/reenviar --- ## Plugin Facturalo.pe para WooCommerce URL: https://docs.facturalo.pe/woocommerce **Facturalo.pe for WooCommerce** conecta tu tienda con Facturalo para emitir boletas y facturas electrónicas sin trabajo manual. Cuando un pedido llega al estado que elijas (por defecto, Completado), el plugin arma el comprobante con los datos del pedido y lo envía a `POST /documentos/enviar`. La respuesta de SUNAT y los enlaces a PDF y XML quedan guardados en el pedido. El plugin es gratuito y de código abierto (GPL). Los comprobantes se emiten con tu cuenta de Facturalo, según tu plan. Qué hace - **Emisión automática** de boleta (con DNI o sin documento) o factura (con RUC) cuando el pedido llega al estado configurado. Una sola vez por pedido. - **Campos en el checkout** (bloque de WooCommerce): el cliente elige el comprobante e ingresa DNI o RUC; para factura, también razón social y dirección fiscal. Validación en pantalla (DNI 8 dígitos, RUC 11). - **Demo y producción**, cada uno con su clave de API (`sk_test_…` / `sk_live_…`) y sus propias series. - **Correlativo por serie y entorno**, llevado dentro de WordPress. - **Pantalla Facturalo.pe** en el admin: comprobantes emitidos, estado en SUNAT, acción «Consultar estado» y botón «Emitir ahora» para reintentar. - **Enlace «Descargar comprobante (PDF)»** en Mi cuenta y en los correos del pedido. - El costo de envío va como ítem del comprobante. Soles y dólares. IGV 18% o 10% (régimen especial). Compatible con HPOS. Requisitos Requisito | Versión WordPress | 5.8 o superior WooCommerce | 6.0 o superior PHP | 7.4 o superior Checkout | Checkout en bloques de WooCommerce Descargar e instalar Descarga el plugin (ZIP instalable de WordPress): - [facturalo-pe-for-woocommerce-1.0.0.zip](/assets/facturalo/plugins/facturalo-pe-for-woocommerce-1.0.0.zip) — Versión 1.0.0 — boletas y facturas desde el checkout de WooCommerce. 1. Instala y activa: Sube el ZIP descargado en **Plugins > Añadir nuevo > Subir plugin** y activa **Facturalo.pe for WooCommerce**. 2. Abre los ajustes: Ve a **WooCommerce > Facturalo.pe > Ajustes**. 3. Configura la conexión: Elige el entorno e ingresa tu clave: `sk_test_…` para demo o `sk_live_…` para producción. La sacas de la consola al crear tu empresa. 4. Series y disparador: Define las series de boleta y factura (exclusivas para la tienda, por ejemplo `B900` / `F900`), el estado que dispara la emisión y activa la emisión automática. Ajustes Ajuste | Para qué sirve Entorno | «Prueba» mientras validas; en «Producción» los comprobantes van a SUNAT de verdad. Cada entorno usa su clave y su numeración. Clave de API (prueba / producción) | Token `sk_test_…` o `sk_live_…` de la empresa. Series | Serie de boleta y de factura por entorno. El plugin lleva el correlativo desde 1. Emitir cuando el pedido esté | Normalmente «Completado». El comprobante se genera una sola vez por pedido. Tipo de operación SUNAT | Casi siempre `0101` (Venta interna). Tipo de IGV y porcentaje | `10` (Gravado - Operación onerosa) y 18%, o 10% para el régimen especial. Enviar el PDF al cliente | Facturalo envía el comprobante al correo del pedido, además del enlace en Mi cuenta. Preguntas frecuentes - **¿Qué serie uso?** Una que solo emita WooCommerce. Si otro sistema usa la misma serie, SUNAT rechazará los correlativos repetidos. - **¿Qué pasa si la emisión falla?** El pedido queda con una nota del error, estado «error» y el botón «Emitir ahora» para reintentar. El detalle técnico de la solicitud y la respuesta se ve en el pedido. - **¿El cliente necesita cuenta para descargar el comprobante?** No. El enlace al PDF es público. - **¿Funciona con el checkout clásico?** Los campos fiscales están hechos para el checkout en bloques. Con el clásico (shortcode) no tendrás la experiencia completa. Aún no incluye - Nota de crédito automática al reembolsar un pedido. - Guías de remisión desde el pedido. ---