DOCUMENTACIÓN TÉCNICA OFICIAL
FACTURACIÓN ELECTRÓNICA
Sistema completo de integración con SUNAT para Perú. Emite Boletas, Facturas, Notas de Crédito y Débito, Guías de Remisión (GRE) y Comunicaciones de Baja desde una sola API REST. Compatible con ambientes Beta y Producción.
REST · JSON
Beta + Producción
Bearer Token
Multi-empresa
CDR / XML / PDF
🧪 Beta · Pruebas
https://beta.tu-api.com/api
Credenciales beta de SUNAT. Sin validez legal. Ideal para desarrollo y QA.
✅ Producción
https://api.tu-api.com/api
Ambiente real. Requiere certificado digital y credenciales SUNAT vigentes.
Configuraciones
Setup, usuarios, empresas, sucursales y correlativos. Flujo de 10 fases paso a paso.
Autenticación
Login con Bearer Token JWT. Expira en 24h. Necesario para todos los endpoints protegidos.
Boletas
Consumidores finales (DNI). Resumen diario, múltiples tipos de IGV, PDF automático.
Facturas
Empresas con RUC. Envío directo a SUNAT, CDR inmediato, XML firmado, PDF descargable.
Notas de Crédito
13 motivos disponibles. Anula o reduce el valor de facturas y boletas ya emitidas.
Notas de Débito
Aumenta el valor de documentos emitidos. Mora, penalidades, ajustes de precio.
Guías de Remisión
GRE electrónicas. Transporte público y privado. Integración directa con el servicio GRE de SUNAT.
Comunicación de Baja
Anula documentos aceptados por SUNAT. Máximo 7 días. Ticket de seguimiento incluido.
MÓDULO
Configuraciones Generales
Flujo obligatorio de inicialización. Debe ejecutarse una sola vez, en orden, antes de emitir cualquier documento electrónico.
⚡ FLUJO DE INICIALIZACIÓN — 6 PASOS ESENCIALES
01
Verificar e Inicializar el Sistema
Consultar estado con GET /setup/status, ejecutar migraciones con POST /setup/migrate y seeders con POST /setup/seed.
02
Crear Usuario Administrador
Usar POST /auth/initialize con nombre, email y contraseña. Solo funciona si no existen usuarios previos.
03
Login y Obtener Token Bearer
Autenticar con POST /auth/login. El token recibido debe enviarse en el header de todas las peticiones siguientes.
04
Registrar Empresa
Crear empresa con RUC, razón social y credenciales SUNAT usando POST /v1/companies. Activar con /activate.
05
Crear Sucursal y Correlativos
Registrar la sucursal principal (POST /v1/branches) y configurar series F001, B001, FC01, FD01 con /correlatives/batch.
06
Sistema Listo — Emitir Documentos
Con empresa y sucursal activas, ya puedes emitir facturas, boletas, notas y guías de remisión en Beta o Producción.
FASE 1 — Inicialización del Sistema
GET
/setup/status
Estado del sistema
▶
Verifica el estado del sistema, la conexión a base de datos y las dependencias. Úsalo antes de cualquier otra acción.
GET BASE_URL/setup/status
Accept: application/json
POST
/setup/migrate
Ejecutar migraciones
▶
Ejecuta todas las migraciones pendientes de base de datos. Solo necesario en la instalación inicial o después de actualizaciones.
POST
/setup/seed
Ejecutar seeders
▶
Carga datos iniciales del sistema: roles, permisos, catálogos SUNAT y datos de ubigeo peruano (departamentos, provincias, distritos).
FASE 3 — Gestión de Empresas
POST
/v1/companies
Crear empresa
▶
Registra una nueva empresa en el sistema. Usa
modo_produccion: false para testing en el ambiente Beta de SUNAT.{
"ruc": "20123456789",
"razon_social": "MI EMPRESA SAC",
"nombre_comercial": "Mi Empresa",
"modo_produccion": false,
"sunat_user": "MODDATOS",
"sunat_password": "moddatos",
"direccion": "Av. Principal 123",
"ubigeo": "150101",
"distrito": "Lima",
"provincia": "Lima",
"departamento": "Lima"
}
POST
/v1/companies/{id}/activate
Activar empresa
▶
Activa la empresa para que pueda emitir documentos electrónicos. Sin este paso, las emisiones serán rechazadas.
FASE 4 — Sucursales y Correlativos
POST
/v1/branches/{id}/correlatives/batch
Crear correlativos
▶
Crea las series y correlativos necesarios para cada tipo de documento SUNAT. Hazlo una vez por sucursal.
{
"correlativos": [
{ "tipo_documento": "01", "serie": "F001", "numero_actual": 0 },
{ "tipo_documento": "03", "serie": "B001", "numero_actual": 0 },
{ "tipo_documento": "07", "serie": "FC01", "numero_actual": 0 },
{ "tipo_documento": "08", "serie": "FD01", "numero_actual": 0 }
]
}
FASE 5 — Gestión de Clientes
POST
/v1/clients
Crear cliente
▶
Registra un cliente. Usa
tipo_documento: "1" para DNI (persona natural) o "6" para RUC (empresa).
POST
/v1/clients/search-by-document
Buscar por documento
▶
Busca un cliente existente por tipo y número de documento. Ideal para autocompletar datos en el frontend.
MÓDULO
Autenticación
La API usa Bearer Token (JWT). Debes hacer login para obtener el token y enviarlo en el header Authorization de cada petición protegida.
🔑 HEADER REQUERIDO EN TODOS LOS ENDPOINTS
Authorization: Bearer TU_ACCESS_TOKEN_AQUI
Accept: application/json
Content-Type: application/json
POST
/auth/login
Login — Obtener Token
▶
Autentica al usuario y retorna el token de acceso. El token expira en 1440 minutos (24 horas). Guarda el
access_token para las siguientes peticiones.POST BASE_URL/auth/login
{
"email": "admin@tu-empresa.com",
"password": "TuPassword123!"
}
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
"token_type": "Bearer",
"expires_in": 1440,
"user": {
"id": 1,
"name": "Administrador del Sistema",
"email": "admin@tu-empresa.com"
}
}
POST
/auth/initialize
Crear admin inicial
▶
Crea el primer usuario administrador. Solo funciona si no existen usuarios en el sistema. Solo se ejecuta una vez.
{
"name": "Administrador del Sistema",
"email": "admin@sistema-sunat.com",
"password": "Admin123!@#",
"password_confirmation": "Admin123!@#"
}
GET
/v1/auth/me
Usuario autenticado
▶
Retorna los datos del usuario actualmente autenticado según el token enviado en el header.
POST
/auth/logout
Cerrar sesión
▶
Revoca el token actual. Después de esto, el token deja de funcionar y se deberá hacer login nuevamente.
MÓDULO
Boletas de Venta
Para consumidores finales con DNI. Las boletas se agrupan en un resumen diario que se envía a SUNAT al cierre del día. No requieren RUC del cliente.
📋 TIPOS DE AFECTACIÓN IGV
| Código | Tipo | Descripción |
|---|---|---|
| 10 | string | Gravado — operación onerosa (IGV 18% incluido) |
| 20 | string | Exonerado — operación onerosa sin IGV |
| 30 | string | Inafecto — operación onerosa sin IGV por ley |
| 40 | string | Exportación de bienes o servicios |
ENDPOINTS PRINCIPALES
POST
/api/v1/boletas
Crear boleta
▶
Emite una boleta electrónica. Por defecto usa
metodo_envio: "resumen_diario". El campo tipo_igv en cada línea determina el tratamiento tributario.{
"company_id": 1,
"branch_id": 1,
"serie": "B001",
"fecha_emision": "2025-06-09",
"moneda": "PEN",
"tipo_operacion": "0101",
"metodo_envio": "resumen_diario",
"forma_pago_tipo": "Contado",
"client": {
"tipo_documento": "1",
"numero_documento": "12345678",
"razon_social": "María Elena García Sánchez",
"email": "cliente@email.com"
},
"detalles": [
{
"codigo": "PROD001",
"descripcion": "Laptop HP Pavilion 15.6\"",
"unidad": "NIU",
"cantidad": 1,
"precio_unitario": 2118.64,
"tipo_igv": "10",
"igv": 381.36,
"total": 2500.00
}
],
"totales": {
"total_gravado": 2118.64,
"total_igv": 381.36,
"total_venta": 2500.00
}
}
POST
/api/v1/boletas/create-daily-summary
Crear resumen diario
▶
Agrupa todas las boletas del día en un resumen (RC) para enviar a SUNAT. Ejecutar al cierre del día.
POST
/api/v1/daily-summaries/{id}/send-sunat
Enviar resumen a SUNAT
▶
Envía el resumen diario a SUNAT. Retorna un ticket para verificar el estado posterior del procesamiento.
POST
/api/v1/boletas/{id}/generate-pdf
Generar PDF
▶
Genera el PDF de la boleta. Formatos disponibles: A4 (carta) o ticket de 80mm para impresoras térmicas.
GET
/api/v1/boletas?company_id={id}&branch_id={id}&per_page=20
Listar boletas
▶
Lista boletas con paginación. Filtros disponibles:
company_id, branch_id, estado_sunat, fecha_desde, fecha_hasta.MÓDULO
Facturas Electrónicas
Para empresas con RUC. A diferencia de las boletas, las facturas se envían directamente a SUNAT de forma individual y reciben una CDR inmediata con el resultado.
ENDPOINTS PRINCIPALES
POST
/api/v1/invoices
Crear factura
▶
Emite una factura electrónica. La serie debe ser F001. El cliente debe tener
tipo_documento: "6" (RUC). Si auto_send está activo, se envía a SUNAT automáticamente.{
"company_id": 1,
"branch_id": 1,
"serie": "F001",
"fecha_emision": "2025-09-15",
"fecha_vencimiento": "2025-10-04",
"moneda": "PEN",
"tipo_operacion": "0101",
"forma_pago_tipo": "Credito",
"client": {
"tipo_documento": "6",
"numero_documento": "20123456789",
"razon_social": "EMPRESA CLIENTE SAC",
"email": "cliente@empresa.com"
},
"detalles": [
{
"codigo": "PROD001",
"descripcion": "Laptop HP Pavilion 15.6\" Intel Core i5",
"unidad": "NIU",
"cantidad": 2,
"precio_unitario": 2118.64,
"tipo_igv": "10",
"igv": 762.71,
"total": 5000.00
}
],
"totales": {
"total_gravado": 4237.29,
"total_igv": 762.71,
"total_venta": 5000.00
}
}
POST
/api/v1/invoices/{id}/send-sunat
Enviar a SUNAT
▶
Envía la factura a SUNAT y retorna el CDR con el resultado del procesamiento. Puede configurarse para envío automático al crear.
POST
/v1/consulta-cpe-v2/factura/{id}/con-cdr
Consultar estado CDR
▶
Consulta el estado de procesamiento en SUNAT y descarga el CDR (Constancia de Recepción) si ya está disponible.
GET
/api/v1/invoices/{id}/download-pdf?format=A4
Descargar PDF
▶
Descarga el PDF generado de la factura. Parámetro
format: A4 o ticket. Requiere haber generado el PDF primero.MÓDULO
Notas de Crédito
Documentos que modifican o anulan facturas y boletas ya emitidas. Puedes anular, descontar, o devolver total o parcialmente. Existen 13 motivos válidos según catálogos SUNAT.
📋 CATÁLOGO COMPLETO DE MOTIVOS (01–13)
| Código | Tipo | Motivo |
|---|---|---|
| 01 | string | Anulación de la operación |
| 02 | string | Anulación por error en el RUC |
| 03 | string | Corrección por error en la descripción |
| 04 | string | Descuento global sobre el total |
| 05 | string | Descuento por ítem específico |
| 06 | string | Devolución total de bienes |
| 07 | string | Devolución por ítem específico |
| 08 | string | Bonificación |
| 09 | string | Disminución en el valor de la operación |
| 10 | string | Otros conceptos |
| 11 | string | Ajustes de operaciones de exportación |
| 12 | string | Ajustes afectos al IVAP |
| 13 | string | Ajustes de montos y tipos de cambio |
ENDPOINTS
GET
/api/v1/credit-notes/catalogs/motivos
Obtener catálogo
▶
Retorna el catálogo completo de motivos válidos para notas de crédito con códigos y descripciones.
POST
/api/v1/credit-notes
Crear nota de crédito
▶
Crea la nota de crédito referenciando el documento original.
tipo_doc_afectado: "01" para Facturas, "03" para Boletas. La serie: FC01 para facturas, BC01 para boletas.{
"company_id": 1,
"branch_id": 1,
"serie": "FC01",
"fecha_emision": "2025-09-15",
"tipo_doc_afectado": "01",
"serie_afectada": "F001",
"correlativo_afectado": "00000001",
"motivo_codigo": "01",
"motivo_descripcion": "Anulación de la operación",
"moneda": "PEN",
"client": {
"tipo_documento": "6",
"numero_documento": "20123456789",
"razon_social": "EMPRESA CLIENTE SAC"
},
"detalles": [
{
"descripcion": "Anulación total — Factura F001-1",
"cantidad": 1,
"precio_unitario": 2118.64,
"tipo_igv": "10",
"igv": 381.36,
"total": 2500.00
}
]
}
POST
/api/v1/credit-notes/{id}/send-sunat
Enviar a SUNAT
▶
Envía la nota de crédito a SUNAT para validación. Retorna CDR con el resultado.
GET
/api/v1/credit-notes?company_id={id}&per_page=15
Listar notas de crédito
▶
Lista con filtros:
estado_sunat, tipo_doc_afectado, fecha_desde, fecha_hasta. Paginado.
GET
/api/v1/credit-notes/{id}/download-xml
Descargar archivos
▶
Descarga el XML firmado. También disponibles:
/download-cdr y /download-pdf tras generar el PDF.MÓDULO
Notas de Débito
Aumentan el valor de documentos ya emitidos. Úsalas para cobrar intereses por mora, penalidades contractuales o ajustes de precio al alza. Compatible con facturas y boletas.
📋 MOTIVOS VÁLIDOS PARA NOTAS DE DÉBITO
| Código | Tipo | Motivo |
|---|---|---|
| 01 | string | Intereses por mora en el pago |
| 02 | string | Aumento en el valor de la operación |
| 03 | string | Penalidades y otros conceptos |
| 10 | string | Ajustes de operaciones de exportación |
| 11 | string | Ajustes afectos al IVAP |
ENDPOINTS
POST
/api/v1/debit-notes
Crear nota de débito
▶
Crea la nota de débito. Serie
FD01 para facturas, BD01 para boletas. El campo tipo_doc_afectado: "01" o "03".{
"company_id": 1,
"branch_id": 1,
"serie": "FD01",
"fecha_emision": "2025-09-30",
"tipo_doc_afectado": "01",
"serie_afectada": "F001",
"correlativo_afectado": "00000001",
"motivo_codigo": "01",
"motivo_descripcion": "Intereses por mora en el pago",
"moneda": "PEN",
"client": {
"tipo_documento": "6",
"numero_documento": "20123456789",
"razon_social": "EMPRESA CLIENTE SAC"
},
"detalles": [
{
"descripcion": "Intereses por mora — 30 días",
"cantidad": 1,
"precio_unitario": 84.75,
"tipo_igv": "10",
"igv": 15.25,
"total": 100.00
}
]
}
POST
/api/v1/debit-notes/{id}/send-sunat
Enviar a SUNAT
▶
Envía la nota de débito a SUNAT. Retorna CDR con resultado de procesamiento.
GET
/api/v1/debit-notes/{id}/download-cdr
Descargar archivos
▶
Descarga el CDR de SUNAT. Solo disponible tras envío exitoso. También:
/download-xml, /download-pdf.MÓDULO
Guías de Remisión (GRE)
Guías de Remisión Electrónicas para el traslado de mercancías. Se integran directamente con el servicio GRE de SUNAT. Requiere configuración previa de credenciales GRE en la empresa.
Antes de emitir guías debes configurar las credenciales GRE:
PUT /v1/companies/{id}/gre-credentials y luego validar la conexión con POST /gre-credentials/test-connection.
CATÁLOGOS
GET
/api/v1/dispatch-guides/catalogs/transfer-reasons
Motivos de traslado
▶
Lista los motivos de traslado SUNAT: venta, compra, traslado entre establecimientos, importación, exportación, etc.
GET
/api/v1/dispatch-guides/catalogs/transport-modes
Modos de transporte
▶
Lista los modos de traslado:
01 Transporte Público (transportista externo) y 02 Transporte Privado (vehículo propio).EMISIÓN Y ENVÍO
POST
/api/v1/dispatch-guides
Crear guía de remisión
▶
Crea la GRE. El campo
mod_traslado: "01" para transporte público, "02" para transporte privado.{
"company_id": 1,
"branch_id": 1,
"serie": "T001",
"fecha_traslado": "2025-09-15",
"motivo_traslado": "01",
"mod_traslado": "02",
"peso_total": 50.5,
"unidad_peso": "KGM",
"num_bultos": 3,
"partida": {
"ubigeo": "150101",
"direccion": "Av. Principal 123, Lima"
},
"llegada": {
"ubigeo": "040101",
"direccion": "Calle Comercio 456, Arequipa"
},
"vehiculo": { "placa": "ABC-123" },
"conductor": {
"tipo_documento": "1",
"numero_documento": "45678901",
"nombres": "Juan Carlos",
"apellidos": "Pérez García",
"licencia": "Q12345678"
},
"detalles": [
{
"codigo": "PROD001",
"descripcion": "Laptop HP Pavilion",
"cantidad": 3,
"unidad": "NIU"
}
]
}
POST
/api/v1/dispatch-guides/{id}/send-sunat
Enviar a SUNAT GRE
▶
Envía la guía al servicio GRE de SUNAT. Requiere credenciales GRE configuradas y conexión validada.
POST
/api/v1/dispatch-guides/{id}/check-status
Verificar estado
▶
Consulta el estado de procesamiento de la guía en SUNAT.
GET
/api/v1/dispatch-guides/{id}/download-xml
Descargar archivos
▶
Descarga el XML de la guía. También disponibles:
/download-cdr y /download-pdf.MÓDULO
Comunicación de Baja
Permite anular documentos electrónicos ya aceptados por SUNAT. Genera un documento RA (Resumen de Anulaciones) que se procesa de forma asíncrona mediante ticket.
Solo se pueden anular documentos con estado ACEPTADO por SUNAT, emitidos dentro de los últimos 7 días calendario. No se puede incluir el mismo documento dos veces en una misma comunicación.
📋 RESTRICCIONES TÉCNICAS
| Restricción | Valor |
|---|---|
| Plazo máximo | 7 días calendario desde la fecha de emisión |
| Estado requerido | ACEPTADO por SUNAT |
| Duplicados | No se puede incluir el mismo documento dos veces |
| Tipos válidos | Facturas (01), Boletas (03), NC (07), ND (08) |
FLUJO COMPLETO
GET
/api/v1/voided-documents/available-documents?company_id=1&fecha_referencia=2025-09-06
Documentos disponibles
▶
Lista los documentos aceptados por SUNAT que pueden anularse en la fecha indicada. Úsalo antes de crear la comunicación para verificar qué puede anularse.
POST
/api/v1/voided-documents
Crear comunicación de baja
▶
Crea el documento RA con los documentos a anular y el motivo de baja.
{
"company_id": 1,
"branch_id": 1,
"fecha_referencia": "2025-09-06",
"motivo": "Error en cálculo de IGV",
"documentos": [
{
"tipo_documento": "01",
"serie": "F001",
"correlativo": "00000001"
},
{
"tipo_documento": "01",
"serie": "F001",
"correlativo": "00000002"
}
]
}
POST
/api/v1/voided-documents/{id}/send-sunat
Enviar a SUNAT
▶
Envía la comunicación de baja a SUNAT. SUNAT retorna un ticket de seguimiento para consultar el resultado posterior.
POST
/api/v1/voided-documents/{id}/check-status
Consultar estado
▶
Consulta el resultado del procesamiento en SUNAT usando el ticket. El procesamiento puede tardar minutos. Llama este endpoint hasta que el estado sea ACEPTADO o RECHAZADO.
GET
/api/v1/voided-documents/{id}/download-xml
Descargar XML / CDR
▶
Descarga el XML de la baja. También disponible:
/download-cdr tras recibir respuesta de SUNAT.MÓDULO
Configuración Avanzada
Ajustes opcionales por empresa. Permite personalizar el comportamiento del sistema: tasas de impuestos, envío automático a SUNAT, generación de PDF, configuración de GRE y más.
TAX SETTINGS — IMPUESTOS
GET
/companies/{id}/config/tax_settings
Ver config. impuestos
▶
Obtiene la configuración actual de impuestos de la empresa (IGV, ISC, ICBP, retenciones).
PUT
/companies/{id}/config/tax_settings
Actualizar impuestos
▶
Actualiza tasas de impuestos. El estándar peruano es IGV al 18%.
{
"igv_rate": 18,
"isc_enabled": false,
"icbp_enabled": true,
"icbp_rate": 0.20,
"retencion_enabled": false
}
INVOICE SETTINGS — FACTURACIÓN
PUT
/companies/{id}/config/invoice_settings
Config. facturación
▶
Controla el comportamiento al emitir documentos: envío automático a SUNAT, generación de PDF, notificación por email al cliente.
{
"auto_send_sunat": true,
"auto_generate_pdf": true,
"send_email_client": true,
"pdf_format": "A4",
"include_logo": true
}
OPERACIONES GENERALES
POST
/companies/{id}/config/validate
Validar configuración
▶
Valida que todos los servicios SUNAT estén correctamente configurados. Ideal para diagnosticar problemas antes de emitir documentos.
DELETE
/companies/{id}/config/cache
Limpiar caché
▶
Limpia el caché de configuraciones de la empresa. Usar después de realizar cambios en la configuración para que surtan efecto de inmediato.
POST
/companies/{id}/config/reset
Reset a valores por defecto
▶
Resetea la configuración de la empresa a los valores por defecto del sistema. Se puede especificar un módulo específico o resetear todo.