{ "openapi": "3.0.3", "info": { "title": "API del puente SUNAT de Aion Media", "version": "1.0", "description": "Tu sistema calcula y numera el comprobante y lo envía en JSON con el **formato de los modelos de Greenter**, el estándar abierto para SUNAT.\nLo firmamos con el certificado de tu empresa, lo mandamos a SUNAT y te devolvemos el XML y el CDR.\n**No guardamos los archivos**: conservarlos es obligación de tu empresa.\n\n## Cómo empezar\n\n1. Crea tu cuenta y registra tu empresa eligiendo **Puente, desde mi propio sistema**. Queda con el plan\n gratis: 200 comprobantes al mes en producción, sin vencimiento.\n2. En **Configuración → SUNAT y certificado** sube tu certificado digital. En beta sirve el de prueba; para\n producción registra también tu usuario SOL secundario.\n3. En **Integraciones → API** crea un token. Es permanente y pertenece a una empresa: si emites para varias,\n usa un token por empresa.\n4. Envía siempre estas cabeceras:\n\n```\nAuthorization: Bearer \nAccept: application/json\nContent-Type: application/json\n```\n\n## Si ya usas el formato de Greenter\n\nSi tu sistema ya arma los comprobantes con los modelos de Greenter, solo cambia la dirección base por\n`https://puente.aionstoreperu.com/api/v1/bridge` y usa tu token de Aion. El token es permanente: no tienes que renovarlo cada día.\n\n## Límites\n\n- 120 peticiones por minuto por token (429 si te pasas).\n- Cupo del plan: cuentan los comprobantes que SUNAT procesó en producción (aceptados, observados o\n rechazados); un resumen o una baja cuenta sus líneas. Firmar el XML o sacar el PDF sin enviar no cuenta.\n- En beta hay un tope aparte de 50 envíos al mes.\n\n## Consultas de RUC y DNI\n\nEl mismo token sirve para consultar RUC y DNI si las activas en **Servicios** (ver su documentación)." }, "servers": [ { "url": "https://puente.aionstoreperu.com/api/v1", "description": "Esta instalación" } ], "security": [ { "token": [] } ], "tags": [ { "name": "Modo puente", "description": "Para empresas en **modo puente** (se elige al registrar la empresa): tu sistema manda el comprobante **ya calculado y\nnumerado**, en JSON con el formato de los modelos de Greenter, y Aion lo firma con el certificado de tu empresa,\nlo envía a SUNAT y te devuelve el XML y el CDR. **Aion no guarda los archivos**: conservarlos es tu obligación.\nSi tu sistema ya usa el formato de Greenter, solo cambia la dirección base por `https://puente.aionstoreperu.com/api/v1/bridge` y usa tu token de Aion.\n\n- El emisor (`company.ruc`) debe ser la empresa del token; si no envías `company`, se completa con sus datos.\n- SUNAT valida los cálculos: un total mal sumado vuelve como error en `sunatResponse.error`.\n- Cuentan para el cupo los comprobantes que SUNAT procesa (aceptados o rechazados) y las líneas de cada resumen o baja.\n- Una empresa en modo puente no puede usar `/documents` ni `/despatches`, y una en modo completo no puede usar el puente.\n" } ], "paths": { "/bridge/invoice/send": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeInvoiceSend", "summary": "Enviar una factura o boleta ya calculada", "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST \"https://puente.aionstoreperu.com/api/v1/bridge/invoice/send\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Accept: application/json\" \\\n -H \"Content-Type: application/json\" \\\n -d @factura.json\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeInvoice" }, "examples": { "factura": { "summary": "Factura de S/ 118 al contado", "value": { "ublVersion": "2.1", "tipoOperacion": "0101", "tipoDoc": "01", "serie": "F001", "correlativo": "123", "fechaEmision": "2026-11-05T10:00:00-05:00", "formaPago": { "moneda": "PEN", "tipo": "Contado" }, "tipoMoneda": "PEN", "client": { "tipoDoc": "6", "numDoc": "20100070970", "rznSocial": "BOTICA CENTRAL S.A.C.", "address": { "direccion": "AV. LOS OLIVOS 123" } }, "mtoOperGravadas": 100, "mtoIGV": 18, "valorVenta": 100, "totalImpuestos": 18, "subTotal": 118, "mtoImpVenta": 118, "details": [ { "codProducto": "P001", "unidad": "NIU", "descripcion": "PRODUCTO 1", "cantidad": 2, "mtoValorUnitario": 50, "mtoValorVenta": 100, "mtoBaseIgv": 100, "porcentajeIgv": 18, "igv": 18, "tipAfeIgv": "10", "totalImpuestos": 18, "mtoPrecioUnitario": 59 } ], "legends": [ { "code": "1000", "value": "SON CIENTO DIECIOCHO CON 00/100 SOLES" } ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/BridgeBill" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/invoice/xml": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeInvoiceXml", "summary": "Generar el XML firmado de una factura o boleta (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeXml" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/invoice/pdf": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeInvoicePdf", "summary": "Generar el PDF de una factura o boleta (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgePdf" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/invoice/status": { "get": { "tags": [ "Modo puente" ], "operationId": "bridgeInvoiceStatus", "summary": "Consultar el CDR de un comprobante enviado (solo producción)", "parameters": [ { "name": "tipo", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "01", "03", "07", "08" ] } }, { "name": "serie", "in": "query", "required": true, "schema": { "type": "string", "example": "F001" } }, { "name": "numero", "in": "query", "required": true, "schema": { "type": "integer", "example": 123 } } ], "responses": { "200": { "$ref": "#/components/responses/BridgeStatus" } } } }, "/bridge/note/send": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeNoteSend", "summary": "Enviar una nota de crédito o débito ya calculada", "description": "Igual que la factura, con `tipoDoc` `07` u `08`, `codMotivo`, `desMotivo`, `tipDocAfectado` y `numDocfectado` (sin `formaPago`).", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeBill" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/note/xml": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeNoteXml", "summary": "Generar el XML firmado de una nota (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeXml" } } } }, "/bridge/note/pdf": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeNotePdf", "summary": "Generar el PDF de una nota (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgePdf" } } } }, "/bridge/summary/send": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeSummarySend", "summary": "Enviar un resumen diario de boletas (RC)", "description": "`fecGeneracion` (fecha de las boletas), `fecResumen`, `correlativo`, `moneda` y `details` (`tipoDoc`, `serieNro`, `estado` 1 adiciona / 2 modifica / 3 anula, `clienteTipo`, `clienteNro`, `total`, `mtoOperGravadas`, `mtoIGV`, `porcentajeIgv`…). Devuelve un ticket.", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeTicket" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/summary/xml": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeSummaryXml", "summary": "Generar el XML firmado de un resumen (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeXml" } } } }, "/bridge/summary/status": { "get": { "tags": [ "Modo puente" ], "operationId": "bridgeSummaryStatus", "summary": "Consultar el ticket de un resumen", "parameters": [ { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/BridgeStatus" } } } }, "/bridge/voided/send": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeVoidedSend", "summary": "Enviar una comunicación de baja (RA)", "description": "`fecGeneracion` (fecha de los comprobantes), `fecComunicacion`, `correlativo` y `details` (`tipoDoc`, `serie`, `correlativo`, `desMotivoBaja`). Devuelve un ticket.", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeTicket" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/bridge/voided/xml": { "post": { "tags": [ "Modo puente" ], "operationId": "bridgeVoidedXml", "summary": "Generar el XML firmado de una baja (sin enviar)", "requestBody": { "$ref": "#/components/requestBodies/BridgeInvoice" }, "responses": { "200": { "$ref": "#/components/responses/BridgeXml" } } } }, "/bridge/voided/status": { "get": { "tags": [ "Modo puente" ], "operationId": "bridgeVoidedStatus", "summary": "Consultar el ticket de una baja", "parameters": [ { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/BridgeStatus" } } } } }, "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "description": "Token de tipo «ERP (API completa)» creado en Integraciones → API y webhooks." } }, "responses": { "BridgeStatus": { "description": "Estado del ticket o del comprobante. `code` 98 = SUNAT aún lo procesa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "code": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "cdrZip": { "type": "string", "nullable": true }, "cdrResponse": { "type": "object", "nullable": true } } } } } }, "BridgeXml": { "description": "XML firmado.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "Unprocessable": { "description": "Datos incorrectos o regla de negocio (`errors` por campo), o la empresa no está lista para emitir\n(`missing_requirements`). Sin licencia vigente o sin cupo: `errors.license`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "datos": { "summary": "Datos incorrectos", "value": { "message": "La factura solo se emite a clientes con RUC.", "errors": { "customer.document_type": [ "La factura solo se emite a clientes con RUC." ] } } }, "empresa": { "summary": "Empresa sin terminar de configurar", "value": { "message": "La empresa aún no puede emitir.", "missing_requirements": [ "Falta una serie para el tipo de comprobante." ] } } } } } }, "BridgeTicket": { "description": "SUNAT recibió el resumen o la baja; consulta el ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string" }, "hash": { "type": "string", "nullable": true }, "sunatResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "ticket": { "type": "string", "nullable": true, "example": "1793906649895" }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "BridgePdf": { "description": "PDF con la plantilla de Greenter.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "BridgeBill": { "description": "Respuesta de SUNAT. Con CDR, `success` es true y `cdrResponse.accepted` dice si se aceptó.", "content": { "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string", "description": "XML firmado." }, "hash": { "type": "string", "nullable": true }, "sunatResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "cdrZip": { "type": "string", "nullable": true, "description": "ZIP del CDR en Base64." }, "cdrResponse": { "type": "object", "nullable": true, "properties": { "accepted": { "type": "boolean" }, "id": { "type": "string", "example": "F001-123" }, "code": { "type": "string", "example": "0" }, "description": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "Forbidden": { "description": "La empresa del token está deshabilitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } } }, "requestBodies": { "BridgeInvoice": { "required": true, "description": "El comprobante en el JSON de los modelos de Greenter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeInvoice" } } } } }, "schemas": { "BridgeInvoice": { "type": "object", "additionalProperties": true, "description": "Modelo `Invoice` o `Note` de Greenter: `ublVersion`, `tipoOperacion`, `tipoDoc`, `serie`, `correlativo`,\n`fechaEmision`, `formaPago`, `cuotas`, `tipoMoneda`, `client`, `company`, montos (`mtoOperGravadas`, `mtoIGV`,\n`valorVenta`, `subTotal`, `mtoImpVenta`…), `details`, `legends`, `detraccion`, `descuentos`, `anticipos`…\nLas claves desconocidas se ignoran. Las fechas van en ISO 8601.\n", "properties": { "tipoDoc": { "type": "string", "example": "01" }, "serie": { "type": "string", "example": "F001" }, "correlativo": { "type": "string", "example": "123" }, "fechaEmision": { "type": "string", "example": "2026-11-05T10:00:00-05:00" }, "tipoMoneda": { "type": "string", "example": "PEN" }, "mtoImpVenta": { "type": "number", "example": 118 }, "details": { "type": "array", "items": { "type": "object" } } } }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "missing_requirements": { "type": "array", "items": { "type": "string" } } } }, "Message": { "type": "object", "properties": { "message": { "type": "string" } } } } } }