{ "openapi": "3.1.0", "info": { "title": "Facturalo API", "version": "3.0.0", "description": "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.\n\nEspecificación generada automáticamente desde la documentación (https://docs.facturalo.pe). Compatible con Postman, Insomnia y Bruno.\n\nVariables sugeridas:\n- `baseUrl`: https://api.facturalo.pe/api/v3\n- `bearerToken`: sk_test_… (reemplaza por tu secret key real)", "contact": { "name": "Consultia Digital S.A.C.", "email": "contacto@facturalo.pe", "url": "https://www.facturalo.pe" } }, "servers": [ { "url": "https://api.facturalo.pe/api/v3", "description": "api.facturalo.pe/api/v3" } ], "tags": [ { "name": "Consulta", "description": "Endpoints de /consulta" }, { "name": "Documentos", "description": "Endpoints de /documentos" }, { "name": "Empresas", "description": "Endpoints de /empresas" }, { "name": "Guias", "description": "Endpoints de /guias" }, { "name": "Sire", "description": "Endpoints de /sire" }, { "name": "Webhooks", "description": "Endpoints de /webhooks" } ], "paths": { "/consulta/dni/{dni}": { "get": { "operationId": "consultas-dni", "summary": "Consulta por DNI", "description": "Retorna los datos de una persona natural registrada en RENIEC a partir de su número de DNI.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "numero": "27427864", "nombres": "JOSE PEDRO", "apellido_paterno": "CASTILLO", "apellido_materno": "TERRONES", "nombre_completo": "CASTILLO TERRONES, JOSE PEDRO", "departamento": "CAJAMARCA", "provincia": "CHOTA", "distrito": "TACABAMBA", "direccion": "CASERIO PUÑA", "direccion_completa": "CASERIO PUÑA, CAJAMARCA - CHOTA - TACABAMBA", "ubigeo_reniec": "060615", "ubigeo_sunat": "060417", "ubigeo": [ "06", "0604", "060417" ], "fecha_nacimiento": "", "sexo": "" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "dni", "in": "query", "required": true, "description": "Número de DNI (8 dígitos).", "schema": { "description": "Número de DNI (8 dígitos).", "example": 27427864, "type": "string" }, "example": 27427864 }, { "name": "dni", "in": "path", "required": true, "description": "Parámetro de ruta dni", "schema": { "type": "string" } } ] } }, "/consulta/licencia/{dni}": { "get": { "operationId": "consultas-licencia", "summary": "Consulta de licencia de conducir", "description": "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.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "numero_documento": "10400310", "nombre_completo": "CARLOS EDGARDO DELGADO RIVERA", "licencia": { "numero": "Q10400310", "categoria": "A I", "fecha_expedicion": "", "fecha_vencimiento": "06/03/2027", "estado": "VIGENTE", "restricciones": "SIN RESTRICCIONES" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "dni", "in": "query", "required": true, "description": "Número de DNI del conductor (8 dígitos).", "schema": { "description": "Número de DNI del conductor (8 dígitos).", "example": 10400310, "type": "string" }, "example": 10400310 }, { "name": "dni", "in": "path", "required": true, "description": "Parámetro de ruta dni", "schema": { "type": "string" } } ] } }, "/consulta/placa/{placa}": { "get": { "operationId": "consultas-placa", "summary": "Consulta de vehículo por placa", "description": "Retorna los datos técnicos de un vehículo registrado en el Ministerio de Transportes a partir de su número de placa.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "placa": "F3H792", "marca": "FIAT", "modelo": "FIORINO", "serie": "9BD25521A98854312", "color": "BLANCO BANCHISA", "motor": "8632404", "vin": "9BD25521A98854312" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "placa", "in": "query", "required": true, "description": "Número de placa del vehículo.", "schema": { "description": "Número de placa del vehículo.", "example": "F3H792", "type": "string" }, "example": "F3H792" }, { "name": "placa", "in": "path", "required": true, "description": "Parámetro de ruta placa", "schema": { "type": "string" } } ] } }, "/consulta/placa/{placa}/soat": { "get": { "operationId": "consultas-placa-soat", "summary": "Consulta SOAT por placa", "description": "Retorna el estado del SOAT de un vehículo, incluyendo la compañía aseguradora, número de póliza y vigencia.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "placa": "F5U597", "nombre_compania": "Rimac Seguros", "fecha_inicio": "07/11/2023", "fecha_fin": "07/11/2024", "estado": "VENCIDO", "numero_poliza": "0000084606840000000000014", "codigo_sbs_aseguradora": "050", "codigo_unico_poliza": "0500000084606840000000000014" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "placa", "in": "query", "required": true, "description": "Número de placa del vehículo.", "schema": { "description": "Número de placa del vehículo.", "example": "F5U597", "type": "string" }, "example": "F5U597" }, { "name": "placa", "in": "path", "required": true, "description": "Parámetro de ruta placa", "schema": { "type": "string" } } ] } }, "/consulta/ruc/{ruc}": { "get": { "operationId": "consultas-ruc", "summary": "Consulta por RUC", "description": "Retorna los datos fiscales de una empresa o persona natural registrada en SUNAT a partir de su número de RUC.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "numero": "20552103816", "nombre_o_razon_social": "AGROLIGHT PERU S.A.C.", "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA", "estado": "SUSPENSION TEMPORAL", "condicion": "HABIDO", "departamento": "LIMA", "provincia": "LIMA", "distrito": "SANTA ANITA", "direccion": "PJ. JORGE BASADRE NRO. 158 URB. POP LA UNIVERSAL 2DA ET.", "direccion_completa": "PJ. JORGE BASADRE NRO. 158 URB. POP LA UNIVERSAL 2DA ET., LIMA - LIMA - SANTA ANITA", "ubigeo_sunat": "150137", "ubigeo": [ "15", "1501", "150137" ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "ruc", "in": "query", "required": true, "description": "Número de RUC (11 dígitos).", "schema": { "description": "Número de RUC (11 dígitos).", "example": 20552103816, "type": "string" }, "example": 20552103816 }, { "name": "ruc", "in": "path", "required": true, "description": "Parámetro de ruta ruc", "schema": { "type": "string" } } ] } }, "/consulta/ruc/{ruc}/anexos": { "get": { "operationId": "consultas-ruc-establecimientos", "summary": "RUC — Establecimientos anexos", "description": "Retorna la lista de establecimientos anexos (sucursales, depósitos, etc.) de un RUC registrados en SUNAT.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": [ { "codigo": "0003", "tipo_establecimiento": "DE. DEPOSITO", "actividad_economica": "-", "direccion": "MZA. E6 LOTE. 13 URB. PIT PARQUE INDUSTRIAL (MZ. E", "direccion_completa": "MZA. E6 LOTE. 13 URB. PIT PARQUE INDUSTRIAL (MZ. E, LA LIBERTAD - TRUJILLO - LA ESPERANZA", "departamento": "LA LIBERTAD", "provincia": "TRUJILLO", "distrito": "LA ESPERANZA", "ubigeo_sunat": "130105", "ubigeo": [ "13", "1301", "130105" ] }, { "codigo": "0002", "tipo_establecimiento": "SU. SUCURSAL", "actividad_economica": "-", "direccion": "AV. EL EJERCITO NRO. 1020 INT. A BARR. EL MOLINO", "direccion_completa": "AV. EL EJERCITO NRO. 1020 INT. A BARR. EL MOLINO, LA LIBERTAD - TRUJILLO - TRUJILLO", "departamento": "LA LIBERTAD", "provincia": "TRUJILLO", "distrito": "TRUJILLO", "ubigeo_sunat": "130101", "ubigeo": [ "13", "1301", "130101" ] } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "ruc", "in": "query", "required": true, "description": "Número de RUC (11 dígitos).", "schema": { "description": "Número de RUC (11 dígitos).", "example": 20552103816, "type": "string" }, "example": 20552103816 }, { "name": "ruc", "in": "path", "required": true, "description": "Parámetro de ruta ruc", "schema": { "type": "string" } } ] } }, "/consulta/ruc/{ruc}/representantes": { "get": { "operationId": "consultas-ruc-representantes", "summary": "RUC — Representantes legales", "description": "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.", "tags": [ "Consulta" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": [ { "tipo_de_documento": "DNI", "numero_de_documento": "1*****72", "nombre": "PAIMO *****O ***NA", "cargo": "GERENTE GENERAL", "fecha_desde": "30/09/2002" } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "ruc", "in": "query", "required": true, "description": "Número de RUC (11 dígitos).", "schema": { "description": "Número de RUC (11 dígitos).", "example": 20552103816, "type": "string" }, "example": 20552103816 }, { "name": "ruc", "in": "path", "required": true, "description": "Parámetro de ruta ruc", "schema": { "type": "string" } } ] } }, "/consulta/tipo-cambio": { "get": { "operationId": "consultas-tipo-cambio", "summary": "Tipo de cambio", "description": "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.", "tags": [ "Consulta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "fecha": "2024-01-01", "compra": 3.705, "venta": 3.71 } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "fecha", "in": "query", "required": false, "description": "Fecha a consultar en formato AAAA-MM-DD. Sin fecha retorna el tipo de cambio del día actual.", "schema": { "description": "Fecha a consultar en formato AAAA-MM-DD. Sin fecha retorna el tipo de cambio del día actual.", "example": "2024-01-01", "type": "string" }, "example": "2024-01-01" } ] } }, "/documentos/{id}": { "get": { "operationId": "documentos-consultar", "summary": "Consultar documento", "description": "Retorna el estado actual de un documento. El `{id}` es el ID retornado al emitir o anular el documento.", "tags": [ "Documentos" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Documento encontrado.", "data": { "estado": "ACEPTADA", "entorno": "demo", "documento": { "id": "b8731080-6723-11f1-89fc-7d6d1075fa47", "estado": "ACEPTADA", "serie": "B001", "correlativo": "00000001", "tipo": "BOLETA", "tipoCodigo": "03", "fechaEmision": "2026-06-13", "fechaVencimiento": "2026-06-13", "moneda": "PEN", "formaPago": "CONTADO", "cliente": { "direccion": null, "tipoDocumento": "1", "numeroDocumento": "12345678", "denominacion": "NOMBRES Y APELLIDOS" }, "totales": { "gravada": 300, "exonerada": 0, "inafecta": 0, "exportacion": 0, "gratuita": 0, "descuento": 0, "anticipo": 0, "isc": 0, "igv": 54, "impuestoBolsa": 0, "otrosCargos": 0, "total": 354 }, "items": [ { "codigo": "", "descripcion": "Producto con guía de remisión", "unidad": "NIU", "cantidad": 3, "valorUnitario": 100, "precioUnitario": 118, "descuento": 0, "subtotal": 300, "tipoIgv": "10", "tipoIgvDescripcion": "GRAVADO - OPERACIÓN ONEROSA", "igv": 54, "total": 354 } ], "guias": [ { "tipoDocumento": "09", "numeroDocumento": "T001-00000001" } ], "cuotas": [], "anticipos": [], "otrosCampos": [ { "label": "Cajero", "value": "Guillermo" }, { "label": "Método de pago", "value": "Yape" }, { "label": "Mesa", "value": "12" } ] }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Boleta numero B001-00000001, ha sido aceptada", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.cdr" }, "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=", "cadenaQr": "20601476551 | 03 | B001 | 00000001 | 54.00 | 354.00 | 13/06/2026 | 1 | 12345678 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |" } } } } }, "401": { "description": "No autorizado" }, "404": { "description": "No encontrado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "No se encontró el documento en el entorno DEMO.", "data": [] } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Parámetro de ruta id", "schema": { "type": "string" } } ] } }, "/documentos/{id}/eventos": { "get": { "operationId": "documentos-eventos", "summary": "Eventos del documento", "description": "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.", "tags": [ "Documentos" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Eventos del documento obtenidos correctamente.", "data": { "total": 5, "eventos": [ { "id": 1, "tipo": "documento.recibido", "estado": "OK", "duracion_ms": 2, "fecha": "2026-06-14T09:52:53-05:00" }, { "id": 2, "tipo": "documento.xml_generado", "estado": "OK", "duracion_ms": 340, "fecha": "2026-06-14T09:52:53-05:00" }, { "id": 3, "tipo": "documento.sunat.enviando", "estado": "OK", "duracion_ms": 0, "fecha": "2026-06-14T09:52:54-05:00" }, { "id": 4, "tipo": "documento.sunat.respuesta", "estado": "ACEPTADA", "duracion_ms": 1200, "sunat": { "codigo": "0", "mensaje": "La Factura numero F001-00000001 ha sido aceptada", "notas": [] }, "fecha": "2026-06-14T09:52:56-05:00" }, { "id": 5, "tipo": "WEBHOOK_ENVIADO", "estado": "OK", "http_status": 200, "duracion_ms": 85, "fecha": "2026-06-14T09:52:56-05:00" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Parámetro de ruta id", "schema": { "type": "string" } } ] } }, "/documentos/anular": { "post": { "operationId": "documento-anular-factura", "summary": "Anular Factura", "description": "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.\n\nSUNAT 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.", "tags": [ "Documentos" ], "responses": { "200": { "description": "Rechazada por SUNAT", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "Presentacion fuera de fecha", "data": { "estado": "RECHAZADA", "documento": { "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84", "tipo": "FACTURA", "serie": "F001", "correlativo": "00000001" }, "sunat": { "codigo": "2108", "mensaje": "Presentacion fuera de fecha", "notas": [], "ticket": "1781234567890", "hash": "kq1tB7d0n3Wf0yV2oQe9cM4sXaY=", "nombreArchivo": "20601476551-RA-20261030-1", "procesada": true } } } } } }, "401": { "description": "No autorizado" }, "422": { "description": "No existe en SUNAT (producción)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "No se puede anular: el documento figura como \"NO EXISTE\" en SUNAT.", "data": [] } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documento": { "description": "Datos del comprobante a anular.", "type": "object", "properties": { "tipoComprobante": { "description": "`01` para factura, o `07` / `08` para una nota de crédito o débito de factura.", "type": "string" }, "serie": { "description": "Serie de la factura.", "example": "F001", "type": "string" }, "correlativo": { "description": "Número correlativo (máximo 8 dígitos).", "example": 1, "type": "string" }, "motivo": { "description": "Razón de la anulación.", "example": "Error en los datos del cliente", "type": "string" } }, "required": [ "tipoComprobante", "serie", "correlativo", "motivo" ] } }, "required": [ "documento" ] }, "example": { "documento": { "tipoComprobante": "01", "serie": "F001", "correlativo": "1", "motivo": "Error en los datos del cliente" } } } } } } }, "/documentos/enviar": { "post": { "operationId": "documentos-factura-retencion", "summary": "Factura con retención", "description": "Factura sujeta a retención (sunatTransaccion: 2001). Incluye el objeto retencion con tipo y porcentaje.", "tags": [ "Documentos" ], "responses": { "200": { "description": "Rechazada por SUNAT", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "El número de RUC del emisor no existe.", "data": { "estado": "RECHAZADA", "entorno": "demo", "documento": { "id": "9c948140-674e-11f1-85b5-d764057e10c4", "estado": "RECHAZADA", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "sunat": { "estado": "RECHAZADA", "codigo": "2800", "mensaje": "El número de RUC del emisor no existe.", "notas": [] }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.xml" }, "hash": "" } } } } }, "202": { "description": "webhook: true (EN_PROCESO)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "El documento está siendo procesado por SUNAT. Recibirá una notificación en su webhook o puede consultar el estado en el enlace adjunto.", "data": { "estado": "EN_PROCESO", "entorno": "demo", "documento": { "id": "7111d8e0-6891-11f1-ab2a-23413cd2ac7c", "estado": "EN_PROCESO", "serie": "F001", "correlativo": "00000001", "tipo": "FACTURA" }, "enlaces": { "consulta": "https://api.facturalo.pe/api/v3/documentos/7111d8e0-6891-11f1-ab2a-23413cd2ac7c" } } } } } }, "401": { "description": "No autorizado" }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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." ] } } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "description": "Si es true, la respuesta es inmediata (EN_PROCESO) y el resultado llega al webhook configurado. Default: false (síncrono).", "example": false, "type": "boolean" }, "establecimiento": { "description": "UUID del establecimiento emisor. Si se omite, se usa el establecimiento principal de la empresa.", "type": "string" }, "documento": { "description": "Datos del comprobante electrónico.", "type": "object", "properties": { "sunatTransaccion": { "description": "2001 = Operación sujeta a retención. Obligatorio para este tipo.", "example": 2001, "type": "string" }, "tipoComprobante": { "description": "01 = Factura electrónica.", "example": "01", "type": "string" }, "serie": { "description": "Serie del comprobante. Facturas: F001–F999. Boletas: B001–B999. Exactamente 4 caracteres.", "example": "F001", "type": "string" }, "correlativo": { "description": "Correlativo numérico. Máximo 8 caracteres.", "example": 1, "type": "string" }, "fechaEmision": { "description": "Fecha de emisión en formato YYYY-MM-DD.", "example": "2026-06-13", "type": "string" }, "fechaVencimiento": { "description": "Fecha de vencimiento. Formato YYYY-MM-DD. Si no se envía, se toma la fechaEmision como fecha de vencimiento.", "type": "string" }, "formaPago": { "description": "\"CONTADO\" | \"CREDITO\". Si es CREDITO, se requiere el array cuotas.", "example": "CONTADO", "type": "string" }, "moneda": { "description": "\"PEN\" (Soles) | \"USD\" (Dólares).", "example": "PEN", "type": "string" }, "observaciones": { "description": "Texto libre que aparece en el comprobante.", "type": "string" }, "placaVehiculo": { "description": "Placa del vehículo asociado a la operación.", "type": "string" }, "ordenCompra": { "description": "Número de orden de compra del cliente.", "type": "string" }, "otrosCampos": { "description": "Campos libres solo locales (PDF, consulta y webhook). No se envían a SUNAT. Máximo 30 ítems. Cada ítem: { label, value }.", "example": [ { "label": "Cajero", "value": "Guillermo" } ], "type": "string" }, "descuentoGlobal": { "description": "Descuento global aplicado al total del documento (con IGV incluido).", "type": "string" }, "enviarCorreo": { "description": "Si es true, envía el PDF y XML al correo del cliente tras la aceptación. Default: false.", "example": true, "type": "boolean" }, "cliente": { "description": "Datos del adquirente.", "type": "object", "properties": { "tipoDocumento": { "description": "6 = RUC · 1 = DNI · 0 = Sin documento (clientes varios).", "example": 6, "type": "string" }, "numeroDocumento": { "description": "Número sin puntos ni guiones. RUC: 11 dígitos. DNI: 8 dígitos.", "example": 20609753413, "type": "string" }, "denominacion": { "description": "Razón social o nombre completo.", "example": "EMPRESA S.A.C.", "type": "string" }, "direccion": { "description": "Requerida si tipoDocumento = 6 (RUC).", "type": "string" }, "correo": { "description": "Correo del cliente para envío del PDF/XML.", "type": "string" }, "celular": { "description": "Número de celular. Exactamente 9 dígitos.", "type": "string" } }, "required": [ "tipoDocumento", "numeroDocumento", "denominacion" ] }, "items": { "description": "Líneas del comprobante. Mínimo 1 ítem.", "type": "array", "items": { "description": "Código SUNAT: NIU = unidad · ZZ = servicio · BX = caja · KGM = kilogramo · GLI = galón.", "example": "NIU", "type": "string" } } }, "required": [ "sunatTransaccion", "tipoComprobante", "serie", "correlativo", "fechaEmision", "formaPago", "moneda", "cliente", "items" ] } }, "required": [ "documento" ] }, "example": { "webhook": false, "documento": { "sunatTransaccion": "2001", "tipoComprobante": "01", "serie": "F001", "correlativo": "1", "fechaEmision": "2026-06-13", "formaPago": "CONTADO", "otrosCampos": [ { "label": "Cajero", "value": "Guillermo" }, { "label": "Método de pago", "value": "Yape" }, { "label": "Mesa", "value": "12" } ], "moneda": "PEN", "cliente": { "tipoDocumento": "6", "numeroDocumento": "20000000001", "denominacion": "EMPRESA S.A.C.", "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA", "correo": "cliente@empresa.com" }, "retencion": { "tipo": "01", "porcentaje": 3 }, "items": [ { "unidadMedida": "NIU", "descripcion": "Servicio profesional", "cantidad": 1, "precioUnitario": 2360, "tipoIgv": "10" } ] } } } } } } }, "/empresas": { "get": { "operationId": "empresas", "summary": "Listar empresas", "description": "Retorna todas las empresas asociadas al token de usuario autenticado. Incluye tokens y webhooks configurados por entorno.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Empresas obtenidas correctamente.", "data": { "total": 1, "empresas": [ { "id": "afcfac05-b5c2-45c4-90d9-7e6f03c9e863", "ruc": "20614694557", "nombre": "CONSULTIA DIGITAL S.A.C.", "direccion": "AV. PRINCIPAL 123, PISO 4", "departamento": "LAMBAYEQUE", "provincia": "LAMBAYEQUE", "distrito": "LAMBAYEQUE", "codigoPostal": "140301", "produccion": false, "claves": { "demo": { "token": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/demo", "webhookSecret": "whsec_test_xxxxxxxxxxxxxxxxxxx" }, "prod": { "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/prod", "webhookSecret": "whsec_live_xxxxxxxxxxxxxxxxxxx" } }, "creada": "2026-06-13" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "query", "required": true, "description": "Token de usuario (user_sk_...). No se acepta token de empresa.", "schema": { "description": "Token de usuario (user_sk_...). No se acepta token de empresa.", "example": "user_sk_...", "type": "string" }, "example": "user_sk_..." } ] }, "post": { "operationId": "empresas-crear", "summary": "Crear empresa", "description": "Registra una nueva empresa. Retorna los tokens de demo y producción junto con los webhookSecret. Guárdalos — no se pueden recuperar, solo regenerar.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Empresa creada exitosamente.", "data": { "empresa": { "id": "afcfac05-b5c2-45c4-90d9-7e6f03c9e863", "ruc": "20614694557", "nombre": "CONSULTIA DIGITAL S.A.C.", "direccion": "AV. PRINCIPAL 123, PISO 4", "departamento": "LAMBAYEQUE", "provincia": "LAMBAYEQUE", "distrito": "LAMBAYEQUE", "codigoPostal": "140301", "produccion": false, "sunat": { "solUsuario": "MODDATOS", "solClave": "moddatos", "clientId": "client-id-sunat-oauth2", "clientSecret": "client-secret-sunat-oauth2" }, "claves": { "demo": { "token": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/demo", "webhookSecret": "whsec_test_xxxxxxxxxxxxxxxxxxx" }, "prod": { "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/prod", "webhookSecret": "whsec_live_xxxxxxxxxxxxxxxxxxx" } }, "creada": "2026-06-14" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "empresa": { "description": "Datos de la empresa a registrar.", "type": "object", "properties": { "ruc": { "description": "RUC de 11 dígitos. Debe ser único en el sistema.", "example": 20614694557, "type": "string" }, "nombre": { "description": "Razón social de la empresa tal como figura en SUNAT.", "example": "CONSULTIA DIGITAL S.A.C.", "type": "string" }, "direccion": { "description": "Dirección fiscal completa.", "example": "AV. PRINCIPAL 123", "type": "string" }, "departamento": { "description": "Departamento según RENIEC.", "example": "LAMBAYEQUE", "type": "string" }, "provincia": { "description": "Provincia según RENIEC.", "example": "LAMBAYEQUE", "type": "string" }, "distrito": { "description": "Distrito según RENIEC.", "example": "LAMBAYEQUE", "type": "string" }, "codigoPostal": { "description": "Código postal INEI (6 dígitos).", "example": 140301, "type": "string" }, "sunat": { "description": "Credenciales de acceso al servicio SUNAT.", "type": "object", "properties": { "solUsuario": { "description": "Usuario secundario SOL de SUNAT (no el RUC principal).", "example": "MODDATOS", "type": "string" }, "solClave": { "description": "Clave del usuario secundario SOL de SUNAT.", "example": "moddatos", "type": "string" }, "clientId": { "description": "Client ID OAuth2 SUNAT (PASSWRD opcional).", "type": "string" }, "clientSecret": { "description": "Client Secret OAuth2 SUNAT.", "type": "string" } }, "required": [ "solUsuario", "solClave" ] }, "logo": { "description": "Imagen del logo en base64. Aparece en el PDF del comprobante.", "type": "string" }, "produccion": { "description": "Si es true, el token de producción queda activo al crear la empresa. Default: false.", "example": false, "type": "boolean" } }, "required": [ "ruc", "nombre", "direccion", "departamento", "provincia", "distrito", "codigoPostal", "sunat" ] } }, "required": [ "empresa" ] }, "example": { "empresa": { "ruc": "20614694557", "nombre": "CONSULTIA DIGITAL S.A.C.", "direccion": "AV. PRINCIPAL 123, PISO 4", "departamento": "LAMBAYEQUE", "provincia": "LAMBAYEQUE", "distrito": "LAMBAYEQUE", "codigoPostal": "140301", "sunat": { "solUsuario": "MODDATOS", "solClave": "moddatos", "clientId": null, "clientSecret": null } } } } } } } }, "/empresas/{empresaUuid}/establecimientos/{uuid}": { "patch": { "operationId": "empresas-establecimientos-actualizar", "summary": "Actualizar establecimiento", "description": "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`.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Establecimiento actualizado correctamente.", "data": { "establecimiento": { "id": "a9b8c7d6-eeee-ffff-0000-111122223333", "nombre": "SUCURSAL NORTE", "direccion": "Av. Los Pinos 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "SAN ISIDRO", "codigoPostal": "150027", "celular": "987654321", "correo": "sucursal@empresa.com", "logo": "https://api.facturalo.pe/images/establishments/a9b8c7d6-eeee-ffff-0000-111122223333.jpg", "esPrincipal": false, "creado": "2026-06-14" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "empresaUuid", "in": "path", "required": true, "description": "Parámetro de ruta empresaUuid", "schema": { "type": "string" } }, { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "establecimiento": { "description": "Campos a actualizar. Todos son opcionales — envía solo lo que quieres cambiar.", "type": "object", "properties": { "nombre": { "description": "Nuevo nombre del establecimiento.", "example": "SUCURSAL NORTE", "type": "string" }, "direccion": { "description": "Nueva dirección.", "example": "Av. Los Pinos 123", "type": "string" }, "departamento": { "description": "Departamento según RENIEC.", "example": "LIMA", "type": "string" }, "provincia": { "description": "Provincia según RENIEC.", "example": "LIMA", "type": "string" }, "distrito": { "description": "Distrito según RENIEC.", "example": "SAN ISIDRO", "type": "string" }, "codigoPostal": { "description": "Código postal INEI (6 dígitos).", "example": 150027, "type": "string" }, "celular": { "description": "Número de celular (9 dígitos).", "example": 987654321, "type": "string" }, "correo": { "description": "Correo electrónico del establecimiento.", "example": "sucursal@empresa.com", "type": "string" }, "logo": { "description": "Logo en base64. Acepta PNG, WEBP, BMP y otros formatos — se convierte automáticamente a JPEG con calidad 90 y sin metadatos EXIF. Envía null para eliminarlo.", "example": "data:image/png;base64,iVBORw0KGgo...", "type": "string" } } } }, "required": [ "establecimiento" ] }, "example": { "establecimiento": { "nombre": "SUCURSAL NORTE", "direccion": "Av. Los Pinos 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "SAN ISIDRO", "codigoPostal": "150027", "celular": "987654321", "correo": "sucursal@empresa.com", "logo": "data:image/png;base64,iVBORw0KGgo..." } } } } } } }, "/empresas/{uuid}": { "patch": { "operationId": "empresas-actualizar", "summary": "Actualizar empresa", "description": "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.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Empresa actualizada correctamente.", "data": { "empresa": { "id": "afcfac05-b5c2-45c4-90d9-7e6f03c9e863", "ruc": "20614694557", "nombre": "NUEVO NOMBRE S.A.C.", "direccion": "Nueva dirección 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "MIRAFLORES", "codigoPostal": "150048", "produccion": true, "sunat": { "solUsuario": "NUEVO_USER", "solClave": "nueva_clave", "clientId": "client_id_api", "clientSecret": "client_secret_api" }, "claves": { "demo": { "token": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/demo", "webhookSecret": "whsec_test_xxxxxxxxxxxxxxxxxxx" }, "prod": { "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/prod", "webhookSecret": "whsec_live_xxxxxxxxxxxxxxxxxxx" } }, "creada": "2026-06-14" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "empresa": { "description": "Campos a actualizar. Todos son opcionales — envía solo lo que quieres cambiar.", "type": "object", "properties": { "nombre": { "description": "Nueva razón social.", "example": "NUEVO NOMBRE S.A.C.", "type": "string" }, "direccion": { "description": "Nueva dirección fiscal.", "example": "Nueva dirección 123", "type": "string" }, "departamento": { "description": "Departamento según RENIEC.", "example": "LIMA", "type": "string" }, "provincia": { "description": "Provincia según RENIEC.", "example": "LIMA", "type": "string" }, "distrito": { "description": "Distrito según RENIEC.", "example": "MIRAFLORES", "type": "string" }, "codigoPostal": { "description": "Código postal INEI (6 dígitos).", "example": 150048, "type": "string" }, "logo": { "description": "Logo en base64. Envía null para eliminarlo.", "type": "string" }, "produccion": { "description": "Activa o desactiva el entorno de producción.", "example": true, "type": "boolean" }, "sunat": { "description": "Credenciales SOL a actualizar. Envía solo los campos que deseas cambiar.", "type": "object", "properties": { "solUsuario": { "description": "Nuevo usuario secundario SOL de SUNAT.", "example": "NUEVO_USER", "type": "string" }, "solClave": { "description": "Nueva clave del usuario secundario SOL.", "example": "nueva_clave", "type": "string" }, "clientId": { "description": "Client ID OAuth2 SUNAT. Envía null explícitamente para limpiar el valor.", "type": "string" }, "clientSecret": { "description": "Client Secret OAuth2 SUNAT. Envía null explícitamente para limpiar el valor.", "type": "string" } } } } } }, "required": [ "empresa" ] }, "example": { "empresa": { "nombre": "NUEVO NOMBRE S.A.C.", "direccion": "Nueva dirección 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "MIRAFLORES", "codigoPostal": "150048", "logo": "base64...", "produccion": true, "sunat": { "solUsuario": "NUEVO_USER", "solClave": "nueva_clave", "clientId": "client_id_api", "clientSecret": "client_secret_api" } } } } } } } }, "/empresas/{uuid}/establecimientos": { "get": { "operationId": "empresas-establecimientos", "summary": "Listar establecimientos", "description": "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.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Establecimientos obtenidos correctamente.", "data": { "total": 2, "establecimientos": [ { "id": "c1d2e3f4-0000-1111-2222-333344445555", "nombre": "SEDE PRINCIPAL", "direccion": "Av. Grau 123", "departamento": "LAMBAYEQUE", "provincia": "LAMBAYEQUE", "distrito": "LAMBAYEQUE", "codigoPostal": "140301", "celular": "979123456", "correo": "principal@empresa.com", "logo": "https://api.facturalo.pe/storage/images/establishments/c1d2e3f4-0000-1111-2222-333344445555.jpg", "esPrincipal": true, "creado": "2026-06-01" }, { "id": "a9b8c7d6-eeee-ffff-0000-111122223333", "nombre": "SUCURSAL NORTE", "direccion": "AV. INDUSTRIAL 456", "departamento": "LA LIBERTAD", "provincia": "TRUJILLO", "distrito": "TRUJILLO", "codigoPostal": "13001", "celular": null, "correo": null, "logo": null, "esPrincipal": false, "creado": "2026-06-10" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "query", "required": true, "description": "Token de empresa (sk_test_... o sk_live_...).", "schema": { "description": "Token de empresa (sk_test_... o sk_live_...).", "example": "sk_test_...", "type": "string" }, "example": "sk_test_..." }, { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ] }, "post": { "operationId": "empresas-establecimientos-crear", "summary": "Crear establecimiento", "description": "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.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Establecimiento creado exitosamente.", "data": { "establecimiento": { "id": "a9b8c7d6-eeee-ffff-0000-111122223333", "nombre": "SUCURSAL NORTE", "direccion": "AV. INDUSTRIAL 456", "departamento": "LA LIBERTAD", "provincia": "TRUJILLO", "distrito": "TRUJILLO", "codigoPostal": "13001", "celular": "987654321", "correo": "sucursal@empresa.com", "logo": "https://api.facturalo.pe/storage/images/establishments/a9b8c7d6-eeee-ffff-0000-111122223333.jpg", "esPrincipal": false, "creado": "2026-06-14" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "establecimiento": { "description": "Datos del establecimiento a crear.", "type": "object", "properties": { "nombre": { "description": "Nombre del establecimiento. Debe ser único dentro de la empresa.", "example": "SUCURSAL NORTE", "type": "string" }, "direccion": { "description": "Dirección del establecimiento.", "example": "AV. INDUSTRIAL 456", "type": "string" }, "departamento": { "description": "Departamento según RENIEC.", "example": "LA LIBERTAD", "type": "string" }, "provincia": { "description": "Provincia según RENIEC.", "example": "TRUJILLO", "type": "string" }, "distrito": { "description": "Distrito según RENIEC.", "example": "TRUJILLO", "type": "string" }, "codigoPostal": { "description": "Código postal INEI (6 dígitos).", "example": 13001, "type": "string" }, "celular": { "description": "Número de celular del establecimiento (9 dígitos).", "example": 987654321, "type": "string" }, "correo": { "description": "Correo electrónico del establecimiento.", "example": "sucursal@empresa.com", "type": "string" }, "logo": { "description": "Logo en base64 (PNG, WEBP, BMP, etc.). Se convierte automáticamente a JPEG con calidad 90 eliminando metadatos EXIF. Sobreescribe el logo de la empresa en el PDF. Envía null para no incluir logo.", "example": "data:image/png;base64,iVBORw0KGgo...", "type": "string" } }, "required": [ "nombre", "direccion", "departamento", "provincia", "distrito", "codigoPostal" ] } }, "required": [ "establecimiento" ] }, "example": { "establecimiento": { "nombre": "SUCURSAL NORTE", "direccion": "AV. INDUSTRIAL 456", "departamento": "LA LIBERTAD", "provincia": "TRUJILLO", "distrito": "TRUJILLO", "codigoPostal": "13001", "celular": "987654321", "correo": "sucursal@empresa.com", "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAABmJLR0QA/wD/AP+gvaeTAAAA..." } } } } } } }, "/empresas/{uuid}/regenerar-token": { "post": { "operationId": "empresas-regenerar-token", "summary": "Regenerar token de empresa", "description": "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.\n\nEsta acción es irreversible. El token anterior queda invalidado en el instante que se llama a este endpoint.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Token regenerado correctamente.", "data": { "empresa": { "id": "afcfac05-b5c2-45c4-90d9-7e6f03c9e863", "ruc": "20614694557", "nombre": "CONSULTIA DIGITAL S.A.C.", "direccion": "AV. PRINCIPAL 123, PISO 4", "departamento": "LAMBAYEQUE", "provincia": "LAMBAYEQUE", "distrito": "LAMBAYEQUE", "codigoPostal": "140301", "produccion": false, "claves": { "demo": { "token": "sk_test_nuevo_xxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/demo", "webhookSecret": "whsec_test_xxxxxxxxxxxxxxxxxxx" }, "prod": { "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://mi-sistema.com/webhooks/facturalo/prod", "webhookSecret": "whsec_live_xxxxxxxxxxxxxxxxxxx" } }, "creada": "2026-06-14" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entorno": { "description": "Entorno del token a regenerar. \"demo\" | \"prod\".", "example": "demo", "type": "string" } }, "required": [ "entorno" ] }, "example": { "entorno": "demo" } } } } } }, "/empresas/{uuid}/webhook": { "patch": { "operationId": "webhooks-actualizar", "summary": "Actualizar webhook", "description": "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.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Webhook actualizado correctamente.", "data": { "empresa": { "id": "afcfac05-b5c2-45c4-90d9-7e6f03c9e863", "ruc": "20614694557", "nombre": "CONSULTIA DIGITAL S.A.C.", "claves": { "demo": { "token": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://tuapp.com/webhook/facturalo", "webhookSecret": "whsec_test_xxxxxxxxxxxxxxxxxxx" }, "prod": { "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx", "webhookUrl": "https://tuapp.com/webhook/facturalo", "webhookSecret": "whsec_live_xxxxxxxxxxxxxxxxxxx" } } } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "description": "URLs de webhook por entorno. Ambos campos son opcionales — envía solo el que quieres actualizar. Pasa null para limpiar.", "type": "object", "properties": { "demo": { "description": "URL que recibirá los eventos del entorno demo. null para desactivar.", "example": "https://tuapp.com/webhook/facturalo", "type": "string" }, "prod": { "description": "URL que recibirá los eventos del entorno de producción. null para desactivar.", "example": "https://tuapp.com/webhook/facturalo", "type": "string" } } } }, "required": [ "webhook" ] }, "example": { "webhook": { "demo": "https://tuapp.com/webhook/facturalo", "prod": "https://tuapp.com/webhook/facturalo" } } } } } } }, "/empresas/{uuid}/webhook/eventos": { "get": { "operationId": "webhooks-eventos", "summary": "Listar eventos webhook", "description": "Retorna todos los eventos disponibles y su estado (activo/inactivo) por entorno.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Eventos webhook obtenidos correctamente.", "data": { "demo": [ { "evento": "documento.sunat.respuesta", "activo": true }, { "evento": "documento.anulado", "activo": true }, { "evento": "documento.correo.enviado", "activo": false }, { "evento": "documento.correo.fallido", "activo": false }, { "evento": "guia.sunat.respuesta", "activo": true }, { "evento": "documento.error", "activo": true } ], "prod": [ { "evento": "documento.sunat.respuesta", "activo": true }, { "evento": "documento.anulado", "activo": true }, { "evento": "documento.correo.enviado", "activo": false }, { "evento": "documento.correo.fallido", "activo": false }, { "evento": "guia.sunat.respuesta", "activo": true }, { "evento": "documento.error", "activo": true } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "query", "required": true, "description": "Token de empresa (sk_test_... o sk_live_...).", "schema": { "description": "Token de empresa (sk_test_... o sk_live_...).", "example": "sk_test_...", "type": "string" }, "example": "sk_test_..." }, { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ] }, "patch": { "operationId": "webhooks-eventos-actualizar", "summary": "Activar / desactivar eventos", "description": "Activa o desactiva eventos webhook por entorno. Solo se modifican los eventos enviados en el payload — los demás permanecen igual.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Eventos webhook actualizados correctamente.", "data": { "entorno": "demo", "eventos": [ { "evento": "documento.sunat.respuesta", "activo": true }, { "evento": "documento.anulado", "activo": true }, { "evento": "documento.correo.enviado", "activo": true }, { "evento": "documento.correo.fallido", "activo": true }, { "evento": "guia.sunat.respuesta", "activo": true }, { "evento": "documento.error", "activo": true } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Parámetro de ruta uuid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entorno": { "description": "Entorno a modificar. Valores: \"demo\" o \"prod\".", "example": "demo", "type": "string" }, "eventos": { "description": "Lista de eventos a activar o desactivar. Solo se modifican los enviados.", "type": "array", "items": { "description": "Nombre del evento (ej: documento.correo.enviado).", "type": "string" } } }, "required": [ "entorno", "eventos" ] }, "example": { "entorno": "demo", "eventos": [ { "evento": "documento.correo.enviado", "activo": true }, { "evento": "documento.correo.fallido", "activo": true } ] } } } } } }, "/empresas/documentos": { "get": { "operationId": "documentos-listar", "summary": "Listar documentos", "description": "Retorna los documentos de la empresa paginados. Soporta filtros por establecimiento, fecha, tipo y estado.", "tags": [ "Empresas" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Documentos obtenidos correctamente.", "data": { "entorno": "demo", "paginacion": { "total": 46, "limite": 20, "pagina": 1, "paginas": 3 }, "documentos": [ { "id": "9c948140-674e-11f1-85b5-d764057e10c4", "serie": "B001", "correlativo": "00000153", "tipo": "DOCUMENTO", "tipoCodigo": "03", "fechaEmision": "2026-06-13", "moneda": "PEN", "cliente": { "numeroDocumento": "20000000001", "denominacion": "EMPRESA CLIENTE SAC" }, "totales": { "gravada": 500, "igv": 90, "total": 590 }, "sunat": { "estado": "ACEPTADA", "codigo": "0" }, "anulado": false, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/9c948140-674e-11f1-85b5-d764057e10c4.cdr" } }, { "id": "b8731080-6723-11f1-89fc-7d6d1075fa47", "serie": "B001", "correlativo": "00000012", "tipo": "DOCUMENTO", "tipoCodigo": "03", "fechaEmision": "2026-06-13", "moneda": "PEN", "cliente": { "numeroDocumento": "20609753413", "denominacion": "TEC WORL S.A.C." }, "totales": { "gravada": 300, "igv": 54, "total": 354 }, "guias": [ { "tipoDocumento": "09", "numeroDocumento": "T001-00000001" } ], "sunat": { "estado": "ACEPTADA", "codigo": "0" }, "anulado": false, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.pdf", "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.ticket.pdf", "xml": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.xml", "cdr": "https://api.facturalo.pe/api/v3/documentos/b8731080-6723-11f1-89fc-7d6d1075fa47.cdr" } }, { "...": "// 18 documentos más en esta página" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ] } }, "/guias/{id}": { "get": { "operationId": "guias-consultar", "summary": "Consultar guía", "description": "Retorna el estado y datos de una guía de remisión. El `{id}` es el ID retornado al emitir la guía.", "tags": [ "Guias" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Guía encontrada.", "data": { "estado": "ACEPTADA", "entorno": "demo", "guia": { "id": "8b328c40-673d-11f1-b70c-456216ecc78b", "estado": "ACEPTADA", "serie": "T001", "correlativo": "00000001", "tipo": "GUIA_REMISION", "fechaEmision": "2026-06-14", "tipoTransporte": "PÚBLICO", "motivoTraslado": "01", "cliente": { "tipoDocumento": "6", "numeroDocumento": "20100070970", "denominacion": "EMPRESA DISTRIBUIDORA SAC", "correo": null }, "datosTraslado": { "fecha": "2026-06-14", "pesoBrutoTotal": 150.5, "pesoUnidadMedida": "KGM", "numeroBultos": 10, "indicadorDeEnvio": null }, "datosTransportista": { "tipoDocumento": "6", "numeroDocumento": "20415932376", "denominacion": "TRANSPORTES RÁPIDOS SAC", "numeroMTC": "MTC-123456" }, "puntoPartida": { "ubigeo": "150101", "direccion": "AV. INDUSTRIAL 123, LIMA" }, "puntoLlegada": { "ubigeo": "040101", "direccion": "JR. COMERCIO 456, AREQUIPA" }, "items": [ { "codigo": "PROD-001", "descripcion": "TELEVISOR LED 55 PULGADAS", "unidadMedida": "NIU", "cantidad": 5 } ], "documentosRelacionados": [ { "tipoDocumento": "01", "numeroDocumento": "F001-00000001" } ] }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Guia de Remision ha sido aceptada.", "notas": [], "ticket": "DEMO-20260613-043550", "nombreArchivo": "20601476551-09-T001-00000001" }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.pdf", "xml": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.xml", "cdr": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.cdr" }, "hash": "MdDtBpTOHVP7B37uwiBvuaCG1H4=", "cadenaQr": "20601476551 | 09 | T001 | 00000001 | 14/06/2026 | 20100070970 | MdDtBpTOHVP7B37uwiBvuaCG1H4= |" } } } } }, "401": { "description": "No autorizado" }, "404": { "description": "No encontrada", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "Guía no encontrada en el entorno DEMO.", "data": [] } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Parámetro de ruta id", "schema": { "type": "string" } } ] } }, "/guias/{id}/eventos": { "get": { "operationId": "guias-eventos", "summary": "Eventos de guía", "description": "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.", "tags": [ "Guias" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Eventos de la guía obtenidos correctamente.", "data": { "guia": { "id": "46ed7c66-2de8-450d-8a25-9fb2e9e09c41", "serie": "T001", "correlativo": "00000130", "tipo": "GUIA_REMISION", "estado": "ACEPTADA" }, "entorno": "demo", "total_eventos": 5, "eventos": [ { "id": "3ff0e8b0-4bf4-4241-9be7-bebb0c152c1f", "tipo": "guia.recibida", "estado": "ok", "duracion_ms": 0, "fecha": "2026-06-14T10:18:35-05:00" }, { "id": "2c71f525-10ca-49cc-9d5d-10202c91d962", "tipo": "guia.xml_generado", "estado": "ok", "duracion_ms": 0, "sunat": { "notas": [], "codigo": 0, "estado": "NO_ENVIADA", "mensaje": "XML generado y firmado correctamente." }, "fecha": "2026-06-14T10:18:35-05:00" }, { "id": "431f0253-8ce2-424f-ab73-49f20c726ad1", "tipo": "guia.sunat.enviando", "estado": "pendiente", "fecha": "2026-06-14T10:18:35-05:00" }, { "id": "8fad28f9-5dc5-421c-bd12-9f42b85a161b", "tipo": "guia.sunat.respuesta", "estado": "ok", "duracion_ms": 69, "sunat": { "notas": [], "codigo": "0", "estado": "ACEPTADA", "mensaje": "La Guia de Remision ha sido aceptada." }, "fecha": "2026-06-14T10:18:35-05:00" }, { "id": "6d6f4cea-0ad4-4a4b-9f15-e9ecd7865a41", "tipo": "documento.webhook.enviado", "estado": "ok", "duracion_ms": 14, "http_status": "200", "respuesta": { "url": "https://tuapp.com/webhooks/facturalo", "evento": "guia.sunat.respuesta", "body": { "success": true, "evento": "guia.sunat.respuesta", "message": "Webhook recibido correctamente.", "timestamp": "2026-06-14T10:18:35-05:00" } }, "fecha": "2026-06-14T10:18:35-05:00" } ], "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/guias/46ed7c66-2de8-450d-8a25-9fb2e9e09c41.pdf", "xml": "https://api.facturalo.pe/api/v3/guias/46ed7c66-2de8-450d-8a25-9fb2e9e09c41.xml", "cdr": "https://api.facturalo.pe/api/v3/guias/46ed7c66-2de8-450d-8a25-9fb2e9e09c41.cdr" } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "query", "required": true, "description": "Token de empresa (sk_test_... o sk_live_...).", "schema": { "description": "Token de empresa (sk_test_... o sk_live_...).", "example": "sk_test_...", "type": "string" }, "example": "sk_test_..." }, { "name": "id", "in": "path", "required": true, "description": "Parámetro de ruta id", "schema": { "type": "string" } } ] } }, "/guias/enviar": { "post": { "operationId": "guias-transportista", "summary": "Guía de remisión transportista", "description": "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.\n\nLa 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.", "tags": [ "Guias" ], "responses": { "200": { "description": "Rechazada por SUNAT", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "La Guía Transportista número V001-00000001, ha sido rechazada. El numero de documento de identidad del receptor debe ser RUC", "data": { "estado": "RECHAZADA", "entorno": "demo", "guia": { "id": "9c948140-674e-11f1-85b5-d764057e10c4", "estado": "RECHAZADA", "serie": "V001", "correlativo": "00000001", "tipo": "GUIA_TRANSPORTISTA" }, "sunat": { "estado": "RECHAZADA", "codigo": "2017", "mensaje": "El numero de documento de identidad del receptor debe ser RUC", "notas": [], "ticket": "a1b2c3d4-0000-4000-8000-000000000001", "nombreArchivo": "20601476551-31-V001-00000001" }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/guias/9c948140-674e-11f1-85b5-d764057e10c4.pdf", "xml": "https://api.facturalo.pe/api/v3/guias/9c948140-674e-11f1-85b5-d764057e10c4.xml" }, "hash": null, "cadenaQr": null } } } } }, "202": { "description": "webhook: true (EN_PROCESO)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "La Guía Transportista V001-00000001 está siendo procesada. Recibirá una notificación en su webhook cuando SUNAT responda.", "data": { "estado": "EN_PROCESO", "entorno": "demo", "guia": { "id": "46ed7c66-2de8-450d-8a25-9fb2e9e09c41", "estado": "EN_PROCESO", "serie": "V001", "correlativo": "00000001", "tipo": "GUIA_TRANSPORTISTA" }, "enlaces": { "consulta": "https://api.facturalo.pe/api/v3/guias/46ed7c66-2de8-450d-8a25-9fb2e9e09c41" } } } } } }, "401": { "description": "No autorizado" }, "422": { "description": "Error de validación", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "Los datos enviados no son válidos.", "errors": { "guia.cliente.numeroDocumento": [ "El campo Número de Documento del destinatario es requerido." ], "guia.datosTraslado.pesoUnidadMedida": { "mensaje": "El campo Unidad de Medida del Peso seleccionado es inválido.", "valoresValidos": [ { "codigo": "KGM", "nombre": "Kilogramos" }, { "codigo": "TNE", "nombre": "Toneladas" } ] } } } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "description": "Si es true, respuesta inmediata (EN_PROCESO) y resultado por webhook. Default: false (síncrono).", "example": false, "type": "boolean" }, "guia": { "description": "Datos de la guía de remisión transportista.", "type": "object", "properties": { "enviarCorreo": { "description": "Si es true, envía el PDF y XML al correo del destinatario tras la aceptación. Default: false.", "example": true, "type": "boolean" }, "fechaEmision": { "description": "Fecha de emisión.", "example": "2026-06-13", "type": "string" }, "serie": { "description": "Serie V001–V999. La serie V... activa automáticamente el modo transportista (tipo 31).", "example": "V001", "type": "string" }, "correlativo": { "description": "Número correlativo.", "example": 1, "type": "string" }, "motivoTraslado": { "description": "Código de motivo. Ver tabla Motivo de traslado.", "example": "01", "type": "string" }, "observaciones": { "description": "Texto libre que aparece en la guía.", "type": "string" }, "destinatario": { "description": "Empresa o persona que recibe la mercadería.", "type": "object", "properties": { "tipoDocumento": { "description": "6 = RUC · 1 = DNI.", "example": 6, "type": "string" }, "numeroDocumento": { "description": "RUC o DNI del destinatario.", "example": 20100070970, "type": "string" }, "denominacion": { "description": "Razón social o nombre.", "example": "EMPRESA DISTRIBUIDORA SAC", "type": "string" }, "correo": { "description": "Correo del destinatario.", "type": "string" } }, "required": [ "tipoDocumento", "numeroDocumento", "denominacion" ] }, "remitente": { "description": "Empresa o persona que envía la mercadería.", "type": "object", "properties": { "tipoDocumento": { "description": "6 = RUC · 1 = DNI.", "example": 6, "type": "string" }, "numeroDocumento": { "description": "RUC o DNI del remitente.", "example": 20601476551, "type": "string" }, "denominacion": { "description": "Razón social o nombre.", "example": "EMPRESA REMITENTE SAC", "type": "string" } }, "required": [ "tipoDocumento", "numeroDocumento", "denominacion" ] }, "datosTraslado": { "description": "Información del traslado.", "type": "object", "properties": { "fecha": { "description": "Fecha de inicio del traslado.", "example": "2026-06-14", "type": "string" }, "pesoBrutoTotal": { "description": "Peso bruto total de la carga.", "example": 150.5, "type": "number" }, "pesoUnidadMedida": { "description": "\"KGM\" = kilogramo · \"TNE\" = tonelada.", "example": "KGM", "type": "string" }, "numeroBultos": { "description": "Número de bultos.", "example": 10, "type": "number" } }, "required": [ "fecha", "pesoBrutoTotal", "pesoUnidadMedida" ] }, "datosVehiculo": { "description": "Datos del vehículo de transporte.", "type": "object", "properties": { "numeroPlaca": { "description": "Placa del vehículo.", "example": "ABC-123", "type": "string" } }, "required": [ "numeroPlaca" ] }, "datosChofer": { "description": "Datos del conductor del vehículo.", "type": "object", "properties": { "tipoDocumento": { "description": "\"1\" = DNI.", "example": 1, "type": "string" }, "numeroDocumento": { "description": "DNI del chofer.", "example": 45678901, "type": "string" }, "numeroLicencia": { "description": "Número de licencia de conducir.", "example": "Q45678901", "type": "string" }, "nombres": { "description": "Nombres del chofer.", "example": "JUAN CARLOS", "type": "string" }, "apellidos": { "description": "Apellidos del chofer.", "example": "PÉREZ LÓPEZ", "type": "string" } }, "required": [ "tipoDocumento", "numeroDocumento", "numeroLicencia", "nombres", "apellidos" ] }, "puntoPartida": { "description": "Dirección de origen de la carga.", "type": "object", "properties": { "ubigeo": { "description": "Código ubigeo INEI (6 dígitos).", "example": 150101, "type": "string" }, "direccion": { "description": "Dirección completa.", "example": "AV. INDUSTRIAL 123, LIMA", "type": "string" } }, "required": [ "ubigeo", "direccion" ] }, "puntoLlegada": { "description": "Dirección de destino de la carga.", "type": "object", "properties": { "ubigeo": { "description": "Código ubigeo INEI (6 dígitos).", "example": "040101", "type": "string" }, "direccion": { "description": "Dirección completa.", "example": "JR. COMERCIO 456, AREQUIPA", "type": "string" } }, "required": [ "ubigeo", "direccion" ] }, "items": { "description": "Bienes transportados. Mínimo 1 ítem.", "type": "array", "items": { "description": "Código interno del producto.", "type": "string" } }, "documentosRelacionados": { "description": "Guías de remisión remitente asociadas.", "type": "array", "items": { "description": "\"09\" = Guía de remisión remitente.", "example": "09", "type": "string" } } }, "required": [ "fechaEmision", "serie", "correlativo", "motivoTraslado", "destinatario", "remitente", "datosTraslado", "datosVehiculo", "datosChofer", "puntoPartida", "puntoLlegada", "items" ] } }, "required": [ "guia" ] }, "example": { "webhook": false, "guia": { "fechaEmision": "2026-06-13", "serie": "V001", "correlativo": "1", "motivoTraslado": "01", "observaciones": "TRANSPORTE DE MERCADERÍA", "destinatario": { "tipoDocumento": "6", "numeroDocumento": "20100070970", "denominacion": "EMPRESA DISTRIBUIDORA SAC" }, "remitente": { "tipoDocumento": "6", "numeroDocumento": "20601476551", "denominacion": "EMPRESA REMITENTE SAC" }, "datosTraslado": { "fecha": "2026-06-14", "pesoBrutoTotal": 150.5, "pesoUnidadMedida": "KGM", "numeroBultos": 10 }, "datosVehiculo": { "numeroPlaca": "ABC-123" }, "datosChofer": { "tipoDocumento": "1", "numeroDocumento": "45678901", "numeroLicencia": "Q45678901", "nombres": "JUAN CARLOS", "apellidos": "PÉREZ LÓPEZ" }, "puntoPartida": { "ubigeo": "150101", "direccion": "AV. INDUSTRIAL 123, LIMA" }, "puntoLlegada": { "ubigeo": "040101", "direccion": "JR. COMERCIO 456, AREQUIPA" }, "items": [ { "codigo": "PROD-001", "descripcion": "TELEVISOR LED 55 PULGADAS", "unidadMedida": "NIU", "cantidad": 5 } ], "documentosRelacionados": [ { "tipoDocumento": "09", "numeroDocumento": "T001-00000001" } ] } } } } } } }, "/guias/ticket": { "post": { "operationId": "guias-ticket", "summary": "Consultar ticket", "description": "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.", "tags": [ "Guias" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "La Guía de Remisión ha sido aceptada.", "data": { "estado": "ACEPTADA", "entorno": "demo", "guia": { "id": "8b328c40-673d-11f1-b70c-456216ecc78b", "estado": "ACEPTADA", "serie": "T001", "correlativo": "00000001", "tipo": "GUIA_REMISION", "fechaEmision": "2026-06-14", "tipoTransporte": "PÚBLICO", "motivoTraslado": "01", "cliente": { "tipoDocumento": "6", "numeroDocumento": "20100070970", "denominacion": "EMPRESA DISTRIBUIDORA SAC", "correo": null }, "datosTraslado": { "fecha": "2026-06-14", "pesoBrutoTotal": 150.5, "pesoUnidadMedida": "KGM", "numeroBultos": 10, "indicadorDeEnvio": null }, "datosTransportista": { "tipoDocumento": "6", "numeroDocumento": "20415932376", "denominacion": "TRANSPORTES RÁPIDOS SAC", "numeroMTC": "MTC-123456" }, "puntoPartida": { "ubigeo": "150101", "direccion": "AV. INDUSTRIAL 123, LIMA" }, "puntoLlegada": { "ubigeo": "040101", "direccion": "JR. COMERCIO 456, AREQUIPA" }, "items": [ { "codigo": "PROD-001", "descripcion": "TELEVISOR LED 55 PULGADAS", "unidadMedida": "NIU", "cantidad": 5 } ], "documentosRelacionados": [ { "tipoDocumento": "01", "numeroDocumento": "F001-00000001" } ] }, "sunat": { "estado": "ACEPTADA", "codigo": "0", "mensaje": "La Guia de Remision ha sido aceptada.", "notas": [], "ticket": "DEMO-20260613-043550", "nombreArchivo": "20601476551-09-T001-00000001" }, "enlaces": { "pdf": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.pdf", "xml": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.xml", "cdr": "https://api.facturalo.pe/api/v3/guias/8b328c40-673d-11f1-b70c-456216ecc78b.cdr" }, "hash": "MdDtBpTOHVP7B37uwiBvuaCG1H4=", "cadenaQr": "20601476551 | 09 | T001 | 00000001 | 14/06/2026 | 20100070970 | MdDtBpTOHVP7B37uwiBvuaCG1H4= |" } } } } }, "401": { "description": "No autorizado" }, "404": { "description": "Ticket no encontrado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "Ticket no encontrado.", "data": [] } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "description": "Ticket retornado por SUNAT al emitir la guía.", "example": "DEMO-20260613-043550", "type": "string" } }, "required": [ "ticket" ] }, "example": { "ticket": "DEMO-20260613-043550" } } } } } }, "/sire/compras/{periodo}/aceptar-propuesta": { "post": { "operationId": "sire-compras-aceptar-propuesta", "summary": "Aceptar propuesta", "description": "Acepta la propuesta de compras de SUNAT tal cual y avanza el período a Preliminar Registrado.\n\n¡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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Propuesta aceptada correctamente. Use el numTicket para consultar el estado.", "data": { "numTicket": "20260300000140" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/comprobantes": { "get": { "operationId": "sire-compras-comprobantes", "summary": "Comprobantes", "description": "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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Comprobantes obtenidos correctamente.", "data": { "paginacion": { "paginaActual": 1, "paginaAnterior": null, "paginaSiguiente": 2, "porPagina": 100, "totalRegistros": 245, "totalPaginas": 3 }, "registros": [ { "id": "abc123", "codTipoCDP": "01", "numSerieCDP": "F001", "numCDP": "1234", "fecEmision": "01/05/2026", "nomRazonSocialProveedor": "PROVEEDOR SAC", "mtoBIGravada": 500, "mtoIGV": 90, "mtoTotalCP": 590, "codMoneda": "PEN" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Máx: 100. Default: 100.", "schema": { "description": "Registros por página. Máx: 100. Default: 100.", "example": 100, "type": "number" }, "example": 100 }, { "name": "codTipoOpe", "in": "query", "required": false, "description": "Tipo de operación SUNAT en /busqueda. Default: 2 (mismo valor que el portal en Propuesta del RCE). Con 1 las fechas de emisión suelen ignorarse.", "schema": { "description": "Tipo de operación SUNAT en /busqueda. Default: 2 (mismo valor que el portal en Propuesta del RCE). Con 1 las fechas de emisión suelen ignorarse.", "example": 2, "type": "string" }, "example": 2 }, { "name": "fecEmisionIni", "in": "query", "required": false, "description": "Inicio del filtro de fecha de emisión (YYYY-MM-DD). Va junto con fecEmisionFin. Sin fechas, SUNAT devuelve todo el período, también comprobantes emitidos en meses anteriores.", "schema": { "description": "Inicio del filtro de fecha de emisión (YYYY-MM-DD). Va junto con fecEmisionFin. Sin fechas, SUNAT devuelve todo el período, también comprobantes emitidos en meses anteriores.", "example": "2026-10-01", "type": "string" }, "example": "2026-10-01" }, { "name": "fecEmisionFin", "in": "query", "required": false, "description": "Fin del filtro de fecha de emisión (YYYY-MM-DD). Va junto con fecEmisionIni. Si es posterior a hoy (América/Lima), la API lo recorta a hoy: SUNAT no filtra bien con fechas futuras.", "schema": { "description": "Fin del filtro de fecha de emisión (YYYY-MM-DD). Va junto con fecEmisionIni. Si es posterior a hoy (América/Lima), la API lo recorta a hoy: SUNAT no filtra bien con fechas futuras.", "example": "2026-10-26", "type": "string" }, "example": "2026-10-26" }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/conciliar": { "post": { "operationId": "sire-compras-conciliar", "summary": "Iniciar conciliación", "description": "Compara los comprobantes de compras de SUNAT contra los registrados en Facturalo e identifica diferencias de estado y montos.\n\nNo requiere body. Retorna de inmediato un conciliacionId — úsalo en el endpoint Consultar conciliación para obtener el resultado cuando el proceso termine.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Conciliación iniciada. Consulte el estado con el ID proporcionado.", "data": { "conciliacionId": "550e8400-e29b-41d4-a716-446655440000", "estado": "PENDIENTE" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/eliminar-preliminar": { "put": { "operationId": "sire-compras-eliminar-preliminar", "summary": "Eliminar preliminar", "description": "Revierte el período de estado Preliminar a Propuesta.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "El período ya se encuentra en etapa propuesta.", "data": { "numTicket": null } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/eliminar-preliminar-registrado": { "put": { "operationId": "sire-compras-eliminar-preliminar-registrado", "summary": "Eliminar preliminar registrado", "description": "Deshace la acción de Aceptar propuesta y regresa el período al estado Propuesta.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "El período ya se encuentra en etapa propuesta.", "data": { "numTicket": null } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/exportar": { "get": { "operationId": "sire-compras-exportar", "summary": "Exportar propuesta", "description": "Genera un ticket para exportar la propuesta de compras. El archivo estará disponible en Base64 al consultar el ticket.\n\nCon el numTicket recibido, consulta el endpoint Descargar propuesta hasta que el archivo esté listo para descargar.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Exportación iniciada. Consulte el estado con el numTicket.", "data": { "numTicket": "20260300000141" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/inconsistencia-por-comprobante": { "get": { "operationId": "sire-compras-inconsistencia-por-comprobante", "summary": "Inconsistencias por comprobante", "description": "Detalle al hacer clic en el punto rojo (Inc.) de un comprobante en la propuesta RCE. Usa el codCar del listado de comprobantes.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Inconsistencias del comprobante obtenidas correctamente.", "data": [ { "codInconsistencia": "346", "desInconsistencia": "La tasa del IGV aplicado al comprobante de pago no corresponde a lo aprobado por las normas legales.", "mtoValInconsistencia": 229.86 } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202610, "type": "string" }, "example": 202610 }, { "name": "codTipoCDP", "in": "query", "required": true, "description": "Tipo de comprobante.", "schema": { "description": "Tipo de comprobante.", "example": "01", "type": "string" }, "example": "01" }, { "name": "numSerieCDP", "in": "query", "required": true, "description": "Serie del comprobante.", "schema": { "description": "Serie del comprobante.", "example": "E001", "type": "string" }, "example": "E001" }, { "name": "numCDP", "in": "query", "required": true, "description": "Número del comprobante.", "schema": { "description": "Número del comprobante.", "example": 1720, "type": "string" }, "example": 1720 }, { "name": "codCar", "in": "query", "required": true, "description": "CAR SUNAT del comprobante (viene en el listado de comprobantes).", "schema": { "description": "CAR SUNAT del comprobante (viene en el listado de comprobantes).", "example": null, "type": "string" }, "example": null }, { "name": "codOrigen", "in": "query", "required": false, "description": "Origen en SUNAT. Default: 1 (propuesta).", "schema": { "description": "Origen en SUNAT. Default: 1 (propuesta).", "example": 1, "type": "string" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/inconsistencias": { "get": { "operationId": "sire-compras-inconsistencias", "summary": "Inconsistencias del período", "description": "Lista paginada de comprobantes con inconsistencias SUNAT en el RCE. Equivale a la pestaña Inconsistencias del portal.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Inconsistencias obtenidas correctamente.", "data": { "paginacion": { "paginaActual": 1, "paginaAnterior": null, "paginaSiguiente": null, "porPagina": 10, "totalRegistros": 1, "totalPaginas": 1 }, "registros": [ { "codTipoCDP": "01", "numSerieCDP": "E001", "numCDP": "1720", "fecEmision": "08-02-2026", "numDocIdentidadClienteProveedor": "10459387485", "nomRazonSocialClienteProveedor": "SOBRINO RONDA KAREN VANESA", "codMoneda": "PEN", "mtoTotalCP": 254, "codInconsistencia": "346", "desInconsistencia": "La tasa del IGV aplicado al comprobante de pago no corresponde a lo aprobado por las normas legales.", "mtoBIGravadaDG": 229.86, "mtoIGVDG": 24.14, "valInconsistencia": 229.86, "semaforoInconsistencia": "1" } ], "totales": { "mtoBIGravadaDG": 229.86, "mtoIGVDG": 24.14, "mtoTotalCp": 254, "mtoValInconsistencia": 229.86 } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202610, "type": "string" }, "example": 202610 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Máx: 100. Default: 10.", "schema": { "description": "Registros por página. Máx: 100. Default: 10.", "example": 10, "type": "number" }, "example": 10 }, { "name": "s", "in": "query", "required": false, "description": "Campo de orden. Default: fecEmision.", "schema": { "description": "Campo de orden. Default: fecEmision.", "example": "fecEmision", "type": "string" }, "example": "fecEmision" }, { "name": "ord", "in": "query", "required": false, "description": "asc o desc. Default: asc.", "schema": { "description": "asc o desc. Default: asc.", "example": "asc", "type": "string" }, "example": "asc" }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/preliminares": { "get": { "operationId": "sire-compras-preliminares", "summary": "Preliminares registrados", "description": "Consulta si el período tiene un preliminar registrado. Úsalo para obtener el id necesario antes de revertir con Eliminar preliminar registrado.\n\nUsa el id y codTipoRegistro exactos de la respuesta al llamar Eliminar preliminar registrado.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "No hay preliminares registrados en el período seleccionado.", "data": { "paginacion": { "totalRegistros": 0 }, "registros": [] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202605, "type": "string" }, "example": 202605 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Default: 100.", "schema": { "description": "Registros por página. Default: 100.", "example": 100, "type": "number" }, "example": 100 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/resumen": { "get": { "operationId": "sire-compras-resumen", "summary": "Resumen de inconsistencias", "description": "Muestra el porcentaje de comprobantes con errores en la propuesta. Revísalo antes de aceptar para asegurarte de que la propuesta está limpia.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Resumen obtenido correctamente.", "data": { "numRuc": "20609872277", "perPeriodoTributario": "202606", "codTipoResumen": "1", "cantidad": { "porcentajeRelFiscal": 0, "porcentajeNoRelFiscal": 0, "porcentajeSinValidaciones": 100, "total": 245 }, "monto": { "porcentajeRelFiscal": 0, "porcentajeNoRelFiscal": 0, "porcentajeSinValidaciones": 100, "total": 85430.2 } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario en formato YYYYMM.", "schema": { "description": "Período tributario en formato YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "tipo", "in": "query", "required": false, "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro generado. Default: 1.", "schema": { "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro generado. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/{periodo}/resumen-comprobantes": { "get": { "operationId": "sire-compras-resumen-comprobantes", "summary": "Resumen de comprobantes", "description": "Desglose de la propuesta por tipo de comprobante (Facturas, Liquidaciones, NC, ND) con totales de base imponible, IGV y monto.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Resumen de comprobantes obtenido correctamente.", "data": { "registros": [ { "codTipoCDP": "01", "desCodTipoCDP": "Factura", "cntDocumentos": 38, "mtoTotalBIGravada": 72500, "mtoTotalIGV": 13050, "mtoTotalCP": 85550 } ], "totales": { "cntDocumentos": 38, "mtoBIGravada": 72500, "mtoIGV": 13050, "mtoTotalCP": 85550 } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "tipo", "in": "query", "required": false, "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro. Default: 1.", "schema": { "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/compras/periodos": { "get": { "operationId": "sire-compras-periodos", "summary": "Periodos", "description": "Lista los períodos tributarios de compras disponibles y su estado ante SUNAT.\n\nRequisito 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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Periodos obtenidos correctamente.", "data": [ { "perTributario": "202606", "codEstado": "03", "desEstado": "No Presentado" }, { "perTributario": "202605", "codEstado": "02", "desEstado": "Presentado" } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ] } }, "/sire/compras/tickets/{numTicket}/descargar": { "get": { "operationId": "sire-compras-descargar-ticket", "summary": "Descargar propuesta", "description": "Descarga el archivo de la propuesta generado con Exportar propuesta. Consulta el estado hasta que el archivo en Base64 esté disponible.\n\nCuando expirado: true, vuelve a llamar GET /sire/compras/ {periodo} /exportar para obtener un nuevo numTicket.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Archivos disponibles.", "data": [ { "nombreZip": "LE2060987227720260600008040001EXP2.zip", "nombreTxt": "LE206098722772026060008040001EXP2.txt", "archivoBase64": "77u/UnVjfFJhem9uIFNv..." } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "numTicket", "in": "path", "required": true, "description": "Parámetro de ruta numTicket", "schema": { "type": "string" } } ] } }, "/sire/conciliaciones/{conciliacionId}": { "get": { "operationId": "sire-conciliacion", "summary": "Consultar conciliación", "description": "Consulta el estado de una conciliación SIRE iniciada previamente con POST /conciliar. Hacer polling cada 10-15 segundos hasta COMPLETADO o ERROR.\n\nEste endpoint sirve tanto para conciliaciones de ventas como de compras — el campo libro indica cuál es.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Estado de conciliación obtenido correctamente.", "data": { "conciliacionId": "550e8400-e29b-41d4-a716-446655440000", "periodo": "202605", "libro": "ventas", "estado": "ERROR", "createdAt": "2026-06-17T06:59:48.000000Z", "updatedAt": "2026-06-17T07:09:52.000000Z", "errorMensaje": "El ticket SIRE 20260300000145 no terminó en 10 minutos." } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "conciliacionId", "in": "path", "required": true, "description": "Parámetro de ruta conciliacionId", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/aceptar-propuesta": { "post": { "operationId": "sire-ventas-aceptar-propuesta", "summary": "Aceptar propuesta", "description": "Acepta la propuesta de ventas de SUNAT tal cual y avanza el período a Preliminar Registrado.\n\n¡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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Propuesta aceptada correctamente. Use el numTicket para consultar el estado.", "data": { "numTicket": "20260300000137" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/comprobantes": { "get": { "operationId": "sire-ventas-comprobantes", "summary": "Comprobantes", "description": "Lista paginada de los comprobantes de ventas incluidos en la propuesta SUNAT para el período.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Comprobantes obtenidos correctamente.", "data": { "paginacion": { "paginaActual": 1, "paginaAnterior": null, "paginaSiguiente": 2, "porPagina": 100, "totalRegistros": 701, "totalPaginas": 8 }, "registros": [ { "id": "69f4c039b15a15e4301c39f3", "codTipoCDP": "01", "numSerieCDP": "FE01", "numCDP": "4984", "fecEmision": "01/05/2026", "nomRazonSocialCliente": "EMPRESA SAC", "mtoBIGravada": 114.41, "mtoIGV": 20.59, "mtoTotalCP": 135, "codMoneda": "PEN", "codEstadoComprobante": "1", "desEstadoComprobante": "ACTIVO" } ] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Máx: 100. Default: 100.", "schema": { "description": "Registros por página. Máx: 100. Default: 100.", "example": 100, "type": "number" }, "example": 100 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/conciliar": { "post": { "operationId": "sire-ventas-conciliar", "summary": "Iniciar conciliación", "description": "Compara los comprobantes de ventas de SUNAT contra los registrados en Facturalo e identifica diferencias de estado y montos.\n\nNo requiere body. Retorna de inmediato un conciliacionId — úsalo en el endpoint Consultar conciliación para obtener el resultado cuando el proceso termine.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Conciliación iniciada. Consulte el estado con el ID proporcionado.", "data": { "conciliacionId": "550e8400-e29b-41d4-a716-446655440000", "estado": "PENDIENTE" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/eliminar-preliminar": { "put": { "operationId": "sire-ventas-eliminar-preliminar", "summary": "Eliminar preliminar", "description": "Revierte el período de estado Preliminar a Propuesta.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "El período ya se encuentra en etapa propuesta.", "data": { "numTicket": null } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/eliminar-preliminar-registrado": { "put": { "operationId": "sire-ventas-eliminar-preliminar-registrado", "summary": "Eliminar preliminar registrado", "description": "Deshace la acción de Aceptar propuesta y regresa el período al estado Propuesta.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "El período ya se encuentra en etapa propuesta.", "data": { "numTicket": null } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/exportar": { "get": { "operationId": "sire-ventas-exportar", "summary": "Exportar propuesta", "description": "Genera un ticket para exportar la propuesta de ventas. El archivo estará disponible en Base64 al consultar el ticket.\n\nCon el numTicket recibido, consulta el endpoint Descargar propuesta hasta que el archivo esté listo para descargar.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Exportación iniciada. Consulte el estado con el numTicket.", "data": { "numTicket": "20260300000133" } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/inconsistencia-por-comprobante": { "get": { "operationId": "sire-ventas-inconsistencia-por-comprobante", "summary": "Inconsistencias por comprobante", "description": "Detalle al hacer clic en el punto rojo (Inc.) de un comprobante en la propuesta RVIE. Usa el codCar del listado de comprobantes.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Inconsistencias del comprobante obtenidas correctamente.", "data": [ { "codInconsistencia": "301", "desInconsistencia": "Descripción de la inconsistencia reportada por SUNAT.", "mtoValInconsistencia": 100 } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202610, "type": "string" }, "example": 202610 }, { "name": "codTipoCDP", "in": "query", "required": true, "description": "Tipo de comprobante.", "schema": { "description": "Tipo de comprobante.", "example": "01", "type": "string" }, "example": "01" }, { "name": "numSerieCDP", "in": "query", "required": true, "description": "Serie del comprobante.", "schema": { "description": "Serie del comprobante.", "example": "F001", "type": "string" }, "example": "F001" }, { "name": "numCDP", "in": "query", "required": true, "description": "Número del comprobante.", "schema": { "description": "Número del comprobante.", "example": 123, "type": "string" }, "example": 123 }, { "name": "codCar", "in": "query", "required": true, "description": "CAR SUNAT del comprobante (viene en el listado de comprobantes).", "schema": { "description": "CAR SUNAT del comprobante (viene en el listado de comprobantes).", "example": "2010000000001F0010000000123", "type": "string" }, "example": "2010000000001F0010000000123" }, { "name": "codOrigen", "in": "query", "required": false, "description": "Origen en SUNAT. Default: 1 (propuesta).", "schema": { "description": "Origen en SUNAT. Default: 1 (propuesta).", "example": 1, "type": "string" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/inconsistencias": { "get": { "operationId": "sire-ventas-inconsistencias", "summary": "Inconsistencias del período", "description": "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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Inconsistencias obtenidas correctamente.", "data": { "paginacion": { "paginaActual": 1, "paginaAnterior": null, "paginaSiguiente": null, "porPagina": 10, "totalRegistros": 0, "totalPaginas": 0 }, "registros": [], "totales": null } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202610, "type": "string" }, "example": 202610 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Máx: 100. Default: 10.", "schema": { "description": "Registros por página. Máx: 100. Default: 10.", "example": 10, "type": "number" }, "example": 10 }, { "name": "s", "in": "query", "required": false, "description": "Campo de orden. Default: fecEmision.", "schema": { "description": "Campo de orden. Default: fecEmision.", "example": "fecEmision", "type": "string" }, "example": "fecEmision" }, { "name": "ord", "in": "query", "required": false, "description": "asc o desc. Default: asc.", "schema": { "description": "asc o desc. Default: asc.", "example": "asc", "type": "string" }, "example": "asc" }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/preliminares": { "get": { "operationId": "sire-ventas-preliminares", "summary": "Preliminares registrados", "description": "Consulta si el período tiene un preliminar registrado. Úsalo para obtener el id necesario antes de revertir con Eliminar preliminar registrado.\n\nUsa el id y codTipoRegistro exactos de la respuesta al llamar Eliminar preliminar registrado.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "No hay preliminares registrados en el período seleccionado.", "data": { "paginacion": { "totalRegistros": 0 }, "registros": [] } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202605, "type": "string" }, "example": 202605 }, { "name": "page", "in": "query", "required": false, "description": "Página. Default: 1.", "schema": { "description": "Página. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Registros por página. Default: 100.", "schema": { "description": "Registros por página. Default: 100.", "example": 100, "type": "number" }, "example": 100 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/resumen": { "get": { "operationId": "sire-ventas-resumen", "summary": "Resumen de inconsistencias", "description": "Muestra el porcentaje de comprobantes con errores en la propuesta. Revísalo antes de aceptar para asegurarte de que la propuesta está limpia.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Resumen obtenido correctamente.", "data": { "numRuc": "20609872277", "perPeriodoTributario": "202606", "codTipoResumen": "1", "cantidad": { "porcentajeRelFiscal": 0, "porcentajeNoRelFiscal": 0, "porcentajeSinValidaciones": 100, "total": 701 }, "monto": { "porcentajeRelFiscal": 0, "porcentajeNoRelFiscal": 0, "porcentajeSinValidaciones": 100, "total": 229810.6 } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario en formato YYYYMM.", "schema": { "description": "Período tributario en formato YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "tipo", "in": "query", "required": false, "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro generado. Default: 1.", "schema": { "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro generado. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/{periodo}/resumen-comprobantes": { "get": { "operationId": "sire-ventas-resumen-comprobantes", "summary": "Resumen de comprobantes", "description": "Desglose de la propuesta por tipo de comprobante (Facturas, Boletas, NC, ND) con totales de base imponible, IGV y monto.\n\nSolo aparecen los tipos de comprobante que tienen datos en ese período. Las Notas de Crédito tienen montos negativos.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Resumen de comprobantes obtenido correctamente.", "data": { "registros": [ { "codTipoCDP": "01", "desCodTipoCDP": "Factura", "cntDocumentos": 11, "mtoTotalBIGravada": 99745.79, "mtoTotalIGV": 17954.22, "mtoTotalCP": 117700 }, { "codTipoCDP": "07", "desCodTipoCDP": "Nota de Crédito", "cntDocumentos": 1, "mtoTotalBIGravada": -1694.92, "mtoTotalIGV": -305.08, "mtoTotalCP": -2000 } ], "totales": { "cntDocumentos": 12, "mtoBIGravada": 98050.87, "mtoIGV": 17649.14, "mtoTotalCP": 115700 } } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "periodo", "in": "query", "required": true, "description": "Período tributario YYYYMM.", "schema": { "description": "Período tributario YYYYMM.", "example": 202606, "type": "string" }, "example": 202606 }, { "name": "tipo", "in": "query", "required": false, "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro. Default: 1.", "schema": { "description": "1=propuesta, 2=preliminar, 3=no incluidos, 4=registro. Default: 1.", "example": 1, "type": "number" }, "example": 1 }, { "name": "periodo", "in": "path", "required": true, "description": "Parámetro de ruta periodo", "schema": { "type": "string" } } ] } }, "/sire/ventas/periodos": { "get": { "operationId": "sire-ventas-periodos", "summary": "Periodos", "description": "Lista los períodos tributarios de ventas disponibles y su estado ante SUNAT.\n\nRequisito 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.", "tags": [ "Sire" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Periodos obtenidos correctamente.", "data": [ { "perTributario": "202606", "codEstado": "03", "desEstado": "No Presentado" }, { "perTributario": "202605", "codEstado": "02", "desEstado": "Presentado" } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ] } }, "/sire/ventas/tickets/{numTicket}/descargar": { "get": { "operationId": "sire-ventas-descargar-ticket", "summary": "Descargar propuesta", "description": "Descarga el archivo de la propuesta generado con Exportar propuesta. Consulta el estado hasta que el archivo en Base64 esté disponible.\n\nCuando expirado: true, vuelve a llamar GET /sire/ventas/ {periodo} /exportar para obtener un nuevo numTicket.", "tags": [ "Sire" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Archivos disponibles.", "data": [ { "nombreZip": "LE2060987227720260600014040001EXP2.zip", "nombreTxt": "LE206098722772026060014040001EXP2.txt", "archivoBase64": "77u/UnVjfFJhem9uIFNv..." } ] } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "numTicket", "in": "path", "required": true, "description": "Parámetro de ruta numTicket", "schema": { "type": "string" } } ] } }, "/webhooks": { "get": { "operationId": "webhooks-listar", "summary": "Listar webhooks enviados", "description": "Retorna el historial de webhooks enviados. Filtra por estado o evento para encontrar envíos fallidos y reenviarlos.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "items": [ { "id": 42, "tipo": "WEBHOOK_ENVIADO", "estado": "OK", "evento": "documento.sunat.respuesta", "url": "https://tuapp.com/webhooks/facturalo", "httpStatus": 200, "error": null, "duracionMs": 85, "documento": { "id": "eb5e89d0-67d9-11f1-8bd0-5b2bb30404ab", "serie": "F001", "correlativo": "00000123" }, "fecha": "2026-06-14T09:52:56-05:00" } ], "total": 1, "per_page": 20, "current_page": 1 } } } } }, "401": { "description": "No autorizado" } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "Authorization", "in": "query", "required": true, "description": "Token de empresa (sk_test_... o sk_live_...).", "schema": { "description": "Token de empresa (sk_test_... o sk_live_...).", "example": "sk_test_...", "type": "string" }, "example": "sk_test_..." }, { "name": "estado", "in": "query", "required": false, "description": "Filtra por estado: \"FALLIDO\" · \"OK\".", "schema": { "description": "Filtra por estado: \"FALLIDO\" · \"OK\".", "example": "FALLIDO", "type": "string" }, "example": "FALLIDO" }, { "name": "evento", "in": "query", "required": false, "description": "Filtra por tipo de evento.", "schema": { "description": "Filtra por tipo de evento.", "example": "documento.sunat.respuesta", "type": "string" }, "example": "documento.sunat.respuesta" }, { "name": "per_page", "in": "query", "required": false, "description": "Registros por página. Default: 20.", "schema": { "description": "Registros por página. Default: 20.", "example": 20, "type": "string" }, "example": 20 }, { "name": "page", "in": "query", "required": false, "description": "Página a consultar. Default: 1.", "schema": { "description": "Página a consultar. Default: 1.", "example": 1, "type": "string" }, "example": 1 } ] } }, "/webhooks/{eventoId}/reenviar": { "post": { "operationId": "webhooks-reenviar", "summary": "Reenviar webhook fallido", "description": "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.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Webhook reenviado correctamente.", "data": { "evento": "documento.sunat.respuesta", "documentoId": "uuid-documento" } } } } }, "401": { "description": "No autorizado" }, "404": { "description": "Evento no encontrado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "Evento no encontrado o no es un webhook fallido." } } } }, "422": { "description": "Sin payload guardado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": false, "message": "No se puede reenviar: el evento no tiene payload guardado." } } } } }, "security": [ { "authorizationKeyAuth": [] } ], "parameters": [ { "name": "eventoId", "in": "path", "required": true, "description": "Parámetro de ruta eventoId", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Authorization": { "description": "Token de empresa (sk_test_... o sk_live_...).", "example": "sk_test_...", "type": "string" } }, "required": [ "Authorization" ] } } } } } } }, "components": { "securitySchemes": { "authorizationKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key en header Authorization, sin prefijo. Ejemplo: sk_test_…. Demo: sk_test_… · Producción: sk_live_… · Cuenta (empresas): user_sk_…" } } }, "x-collection-variables": [ { "key": "baseUrl", "value": "https://api.facturalo.pe/api/v3" }, { "key": "bearerToken", "value": "sk_test_…" } ] }