{"openapi":"3.1.0","info":{"title":"API SUNAT para integradores","version":"1.0.0","description":"Emisión de facturas, boletas, notas, retenciones, bajas y guías de remisión electrónicas en Perú."},"servers":[{"url":"https://api.apisunat.net/api/v1"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Cuenta"},{"name":"Emisores"},{"name":"Series y establecimientos"},{"name":"Utilidades"},{"name":"Documentos"},{"name":"Anulaciones"},{"name":"GRE"},{"name":"Recursos"}],"paths":{"/issuer/ping":{"get":{"tags":["Cuenta"],"summary":"Comprobar la clave","operationId":"getPing","responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ping"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/account":{"get":{"tags":["Cuenta"],"summary":"Plan y consumo del mes","operationId":"getAccount","responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/issuers":{"get":{"tags":["Emisores"],"summary":"Listar RUC","description":"Lista solo los RUC del modo de la clave: `asu_test_` ve los RUC de prueba (`livemode: false`) y `asu_live_` los de producción (`livemode: true`).","operationId":"getIssuers","responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Emisores"],"summary":"Registrar un RUC","description":"Crea el RUC en el modo de la clave. El mismo RUC puede existir una vez en prueba y una vez en producción. El límite de RUC del plan solo cuenta los de producción.","operationId":"postIssuers","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssuerRequest"},"example":{"ruc":"20123456789","legalName":"Mi Empresa S.A.C.","tradeName":"Mi Empresa"}}}},"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.\n\n`ISSUER_LIMIT_REACHED`: El plan no permite más RUC de producción (los RUC de prueba no tienen límite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`ISSUER_ALREADY_EXISTS`: El RUC ya está registrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/issuers/{ruc}":{"get":{"tags":["Emisores"],"summary":"Consultar un RUC","operationId":"getIssuersRuc","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ISSUER_NOT_FOUND`: El RUC no está registrado en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Emisores"],"summary":"Activar o desactivar un RUC","operationId":"patchIssuersRuc","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIssuerRequest"},"example":{"active":true}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ISSUER_NOT_FOUND`: El RUC no está registrado en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`ISSUER_SELECTION_REQUIRED`: Tu plan ya tiene el máximo de RUC activos; desactiva el RUC activo antes de activar otro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/issuers/{ruc}/credentials":{"put":{"tags":["Emisores"],"summary":"Guardar credenciales SUNAT","description":"Con `asu_test_` configura el RUC de prueba: solo el certificado PFX/P12 y su contraseña (SUNAT beta firma con el usuario genérico MODDATOS; los campos SOL se ignoran). Con `asu_live_` configura el RUC de producción: usuario SOL secundario, clave, certificado y credenciales GRE reales. El campo `environment` es obsoleto y se ignora. Cambiar usuario, clave o certificado reinicia las validaciones del RUC (y deshabilita producción hasta repetir la prueba real).","operationId":"putIssuersRucCredentials","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerCredentialsRequest"},"example":{"solUser":"FACTURA1","solPassword":"clave-sol-secundaria","certificateBase64":"MIIK...","certificatePassword":"clave-del-pfx"}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ISSUER_NOT_FOUND`: El RUC no está registrado en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`INVALID_LOGO`: El logo debe ser PNG o JPEG en base64.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/issuers/{ruc}/validations/{environment}":{"post":{"tags":["Emisores"],"summary":"Validar el RUC con SUNAT","description":"`beta` (clave `asu_test_`, RUC de prueba) emite una boleta en SUNAT beta con MODDATOS y el certificado del RUC. `produccion` (clave `asu_live_`, RUC de producción) emite una factura real de S/ 1.18 y su baja con las credenciales reales; requiere `confirmation: \"EMITIR PRUEBA REAL\"`, no la validación beta. Con la otra clave responde `TEST_MODE_ISSUER` o `LIVE_MODE_ISSUER`.","operationId":"postIssuersRucValidationsEnvironment","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"}},{"name":"environment","in":"path","required":true,"schema":{"type":"string","enum":["beta","produccion"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateIssuerRequest"},"example":{"confirmation":"EMITIR PRUEBA REAL"}}}},"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerValidation"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ISSUER_NOT_FOUND`: El RUC no está registrado en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`ISSUER_NOT_CONFIGURED`: El RUC no tiene credenciales SUNAT listas: guarda el certificado y completa la validación beta (clave `asu_test_`) o la de producción (clave `asu_live_`).\n\n`PRODUCTION_CREDENTIALS_REQUIRED`: Guarda el usuario SOL secundario, su clave y el certificado reales del RUC antes de la prueba real.\n\n`PRODUCTION_INVOICE_PENDING`: La factura de validación de producción sigue pendiente.\n\n`VALIDATION_IN_PROGRESS`: Ya hay una validación del RUC en curso.\n\n`TEST_MODE_ISSUER`: El RUC es de modo prueba (clave `asu_test_`): la prueba real y la habilitación de producción se hacen en el RUC de producción con una clave `asu_live_`.\n\n`LIVE_MODE_ISSUER`: El RUC es de producción (clave `asu_live_`): la validación en SUNAT beta se hace con el RUC de modo prueba y una clave `asu_test_`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`CONFIRMATION_REQUIRED`: Falta la confirmación exacta para emitir en producción.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/issuers/{ruc}/production":{"post":{"tags":["Emisores"],"summary":"Pasar el RUC a producción","description":"Habilita el RUC de producción cuando la prueba real (factura y baja) está aceptada. Desde ese momento las claves `asu_live_` emiten con él en SUNAT producción. Con una clave `asu_test_` responde `TEST_MODE_ISSUER`.","operationId":"postIssuersRucProduction","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ISSUER_NOT_FOUND`: El RUC no está registrado en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`PRODUCTION_VALIDATION_REQUIRED`: El RUC necesita una validación de producción aceptada.\n\n`TEST_MODE_ISSUER`: El RUC es de modo prueba (clave `asu_test_`): la prueba real y la habilitación de producción se hacen en el RUC de producción con una clave `asu_live_`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/series":{"get":{"tags":["Series y establecimientos"],"summary":"Listar series","operationId":"getSeries","parameters":[{"name":"ruc","in":"query","required":false,"description":"RUC del emisor. Opcional si el workspace tiene un solo RUC activo.","schema":{"type":"string","pattern":"^\\d{11}$"}},{"name":"establishmentCode","in":"query","required":false,"description":"Código de 4 dígitos del establecimiento.","schema":{"type":"string","pattern":"^\\d{4}$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeriesList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`INVALID_ESTABLISHMENT`: El establecimiento no existe o no pertenece al RUC.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/establishments":{"get":{"tags":["Series y establecimientos"],"summary":"Listar establecimientos","operationId":"getEstablishments","parameters":[{"name":"ruc","in":"query","required":false,"description":"RUC del emisor. Opcional si el workspace tiene un solo RUC activo.","schema":{"type":"string","pattern":"^\\d{11}$"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstablishmentList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Series y establecimientos"],"summary":"Crear o actualizar un establecimiento","operationId":"postEstablishments","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEstablishmentRequest"},"example":{"ruc":"20123456789","code":"0001","name":"Tienda Miraflores","address":"Av. Larco 123","ubigeo":"150122","series":[{"documentType":"01","series":"F002","mode":"automatic"}]}}}},"responses":{"201":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Establishment"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`SERIES_DUPLICATED`: La serie ya existe en el RUC.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`SERIES_ESTABLISHMENT_MISMATCH`: La serie pertenece a otro establecimiento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/calculations":{"post":{"tags":["Utilidades"],"summary":"Calcular totales e IGV","operationId":"postCalculations","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculationRequest"},"example":{"items":[{"description":"Servicio","quantity":1,"unitPrice":118,"includesTax":true,"taxCode":"10"}]}}}},"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calculation"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/catalogs":{"get":{"tags":["Utilidades"],"summary":"Listar catálogos SUNAT","operationId":"getCatalogs","responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/catalogs/products":{"get":{"tags":["Utilidades"],"summary":"Buscar en el catálogo 25 (productos SUNAT)","operationId":"getCatalogsProducts","parameters":[{"name":"q","in":"query","required":false,"description":"Texto o código a buscar (mínimo 2 caracteres).","schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","required":false,"description":"Resultados por página (1 a 100, por defecto 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","required":false,"description":"Página, desde 1.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSearch"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/catalogs/{name}":{"get":{"tags":["Utilidades"],"summary":"Consultar un catálogo","operationId":"getCatalogsName","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","description":"Nombre (units) o número SUNAT (03)."}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents":{"get":{"tags":["Documentos"],"summary":"Listar documentos","operationId":"getDocuments","parameters":[{"name":"type","in":"query","required":false,"description":"Tipo SUNAT: 01, 03, 07, 08, 09 o 20.","schema":{"type":"string","enum":["01","03","07","08","09","20"]}},{"name":"status","in":"query","required":false,"description":"Estado del documento.","schema":{"type":"string","enum":["processing","accepted","accepted_with_observations","rejected","error","void_pending","voided"]}},{"name":"from","in":"query","required":false,"description":"Desde (AAAA-MM-DD, hora de Lima).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Hasta (AAAA-MM-DD, hora de Lima).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Resultados por página (1 a 100, por defecto 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Valor de `nextCursor` de la página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPage"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Documentos"],"summary":"Emitir factura, boleta, nota o retención","description":"La clave decide el ambiente y el RUC: `asu_test_` emite con el RUC de prueba en SUNAT beta (numeración propia, sin consumir el plan; requiere su validación beta); `asu_live_` emite con el RUC de producción en SUNAT producción y requiere que esté habilitado (`PRODUCTION_NOT_ENABLED` si no). Un RUC del otro modo responde `ISSUER_FORBIDDEN`.","operationId":"postDocuments","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve el mismo resultado durante 7 días.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentRequest"},"example":{"ruc":"20123456789","documentType":"01","series":"F001","currency":"PEN","issueDate":"2026-10-27","customer":{"documentType":"6","documentNumber":"20100066603","name":"Cliente S.A.C.","email":"facturas@cliente.pe"},"items":[{"code":"SERV-01","description":"Servicio de consultoría","quantity":1,"unitPrice":118,"includesTax":true,"taxCode":"10","unitCode":"ZZ"}],"paymentCondition":"cash"}}}},"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.\n\n`IDEMPOTENCY_REQUIRED`: Falta el header `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.\n\n`PLAN_REQUIRED`: El workspace no tiene una suscripción activa.\n\n`PLAN_LIMIT_REACHED`: Se consumieron las operaciones del plan en el mes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.\n\n`PRODUCTION_NOT_ENABLED`: Una clave `asu_live_` emite siempre en SUNAT producción y el RUC todavía no está habilitado. Usa una clave `asu_test_` para probar en beta o completa la validación de producción.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`ISSUER_NOT_CONFIGURED`: El RUC no tiene credenciales SUNAT listas: guarda el certificado y completa la validación beta (clave `asu_test_`) o la de producción (clave `asu_live_`).\n\n`SERIES_BUSY`: La serie está reservada por otra emisión; reintenta.\n\n`DOCUMENT_NUMBER_CONFLICT`: La serie y número ya fueron emitidos.\n\n`IDEMPOTENCY_CONFLICT`: La `Idempotency-Key` ya se usó con otro cuerpo.\n\n`REQUEST_IN_PROGRESS`: Otra petición con la misma `Idempotency-Key` sigue en proceso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`CUSTOMER_NOT_FOUND`: No se encontraron datos para el RUC o DNI del cliente; envía `customer.name`.\n\n`EXPORT_DATA_INCOMPLETE`: Faltan datos obligatorios de exportación (operación 0200).\n\n`NOTE_ISSUER_MISMATCH`: La nota y el documento afectado son de RUC distintos.\n\n`INVALID_SERIES`: La serie no existe o no corresponde al tipo de documento.\n\n`SERIES_INACTIVE`: La serie está inactiva.\n\n`NUMBER_REQUIRED`: La serie es manual y requiere `number`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}":{"get":{"tags":["Documentos"],"summary":"Consultar un documento","operationId":"getDocumentsId","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}/{file}":{"get":{"tags":["Documentos"],"summary":"Descargar PDF, XML, ZIP o CDR","description":"El PDF se devuelve directamente. XML, ZIP y CDR responden 302 hacia una URL firmada de corta duración.","operationId":"getDocumentsIdFile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file","in":"path","required":true,"schema":{"type":"string","enum":["pdf","xml","zip","cdr"]}},{"name":"format","in":"query","required":false,"description":"Solo PDF: a4 (por defecto), a5, ticket80, ticket58 o ticket50.","schema":{"type":"string","enum":["a4","a5","ticket80","ticket58","ticket50"]}}],"responses":{"200":{"description":"PDF (200) o redirección 302 a la URL firmada de XML, ZIP o CDR.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`FILES_NOT_AVAILABLE`: El XML, ZIP o PDF todavía no está disponible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}/resend":{"post":{"tags":["Documentos"],"summary":"Reenviar a SUNAT","operationId":"postDocumentsIdResend","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`TEST_KEY_IN_PRODUCTION`: La clave no corresponde: un documento emitido con `asu_live_` solo se opera con `asu_live_` (y uno de prueba con `asu_test_`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`FILES_NOT_AVAILABLE`: El XML, ZIP o PDF todavía no está disponible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}/query-sunat":{"post":{"tags":["Documentos"],"summary":"Consultar el ticket en SUNAT","operationId":"postDocumentsIdQuerySunat","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`TEST_KEY_IN_PRODUCTION`: La clave no corresponde: un documento emitido con `asu_live_` solo se opera con `asu_live_` (y uno de prueba con `asu_test_`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}/emails":{"get":{"tags":["Documentos"],"summary":"Historial de correos","operationId":"getDocumentsIdEmails","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDeliveryList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Documentos"],"summary":"Enviar por correo","operationId":"postDocumentsIdEmails","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"},"example":{"recipient":"cliente@empresa.pe","format":"a4"}}}},"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDelivery"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`TEST_KEY_IN_PRODUCTION`: La clave no corresponde: un documento emitido con `asu_live_` solo se opera con `asu_live_` (y uno de prueba con `asu_test_`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`FILES_NOT_AVAILABLE`: El XML, ZIP o PDF todavía no está disponible.\n\n`EMAIL_IN_PROGRESS`: Ya hay un envío de correo en curso para el documento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`INVALID_EMAIL`: El destinatario no es un correo válido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/documents/{id}/emails/{deliveryId}/retry":{"post":{"tags":["Documentos"],"summary":"Reintentar un correo","operationId":"postDocumentsIdEmailsDeliveryIdRetry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDelivery"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`TEST_KEY_IN_PRODUCTION`: La clave no corresponde: un documento emitido con `asu_live_` solo se opera con `asu_live_` (y uno de prueba con `asu_test_`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`EMAIL_IN_PROGRESS`: Ya hay un envío de correo en curso para el documento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/voids":{"post":{"tags":["Anulaciones"],"summary":"Anular documentos","description":"Facturas y notas se anulan con comunicación de baja (RA), una por documento. Las boletas se anulan juntas con un resumen diario (RC). No se mezclan en una misma petición.","operationId":"postVoids","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve el mismo resultado durante 7 días.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVoidRequest"},"example":{"ruc":"20123456789","documents":[{"documentId":"3f8c1d2e-0000-4000-8000-000000000001","reason":"Error en el monto"}]}}}},"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidList"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.\n\n`IDEMPOTENCY_REQUIRED`: Falta el header `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.\n\n`PLAN_LIMIT_REACHED`: Se consumieron las operaciones del plan en el mes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.\n\n`TEST_KEY_IN_PRODUCTION`: La clave no corresponde: un documento emitido con `asu_live_` solo se opera con `asu_live_` (y uno de prueba con `asu_test_`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`IDEMPOTENCY_CONFLICT`: La `Idempotency-Key` ya se usó con otro cuerpo.\n\n`REQUEST_IN_PROGRESS`: Otra petición con la misma `Idempotency-Key` sigue en proceso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`VOID_NOT_ALLOWED`: Solo se anulan documentos aceptados por SUNAT.\n\n`VOID_MIXED_DOCUMENTS`: Las boletas se anulan en una petición separada de facturas y notas.\n\n`VOID_SUMMARY_MISMATCH`: Las boletas de un resumen deben compartir RUC, fecha y moneda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/voids/{id}":{"get":{"tags":["Anulaciones"],"summary":"Consultar una anulación","operationId":"getVoidsId","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Void"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/guides":{"post":{"tags":["GRE"],"summary":"Emitir una guía de remisión (GRE)","description":"SUNAT no tiene beta para guías: requiere una clave `asu_live_` y un RUC habilitado para producción.","operationId":"postGuides","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave única por operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve el mismo resultado durante 7 días.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGuideRequest"},"example":{"ruc":"20123456789","issueDate":"2026-10-27","motiveCode":"01","transportMode":"02","customer":{"documentType":"6","documentNumber":"20100066603","name":"Destino S.A.C."},"startAddress":"Av. Partida 123","startUbigeo":"150101","arrivalAddress":"Av. Llegada 456","arrivalUbigeo":"150203","vehiclePlate":"ABC123","driverName":"Juan Pérez","driverDocument":"12345678","driverLicense":"Q12345678","weightKg":25,"packages":2,"items":[{"description":"Producto trasladado","quantity":2,"unitCode":"NIU"}]}}}},"responses":{"202":{"description":"Aceptado; SUNAT puede seguir procesando.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.\n\n`IDEMPOTENCY_REQUIRED`: Falta el header `Idempotency-Key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.\n\n`PLAN_LIMIT_REACHED`: Se consumieron las operaciones del plan en el mes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.\n\n`ISSUER_FORBIDDEN`: El RUC no pertenece al workspace de la clave.\n\n`LIVE_KEY_REQUIRED`: La operación requiere una clave `asu_live_` (guías de remisión, que no tienen beta en SUNAT).\n\n`PRODUCTION_NOT_ENABLED`: Una clave `asu_live_` emite siempre en SUNAT producción y el RUC todavía no está habilitado. Usa una clave `asu_test_` para probar en beta o completa la validación de producción.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`ISSUER_NOT_CONFIGURED`: El RUC no tiene credenciales SUNAT listas: guarda el certificado y completa la validación beta (clave `asu_test_`) o la de producción (clave `asu_live_`).\n\n`IDEMPOTENCY_CONFLICT`: La `Idempotency-Key` ya se usó con otro cuerpo.\n\n`REQUEST_IN_PROGRESS`: Otra petición con la misma `Idempotency-Key` sigue en proceso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`CUSTOMER_NOT_FOUND`: No se encontraron datos para el RUC o DNI del cliente; envía `customer.name`.\n\n`INVALID_EMAIL`: El destinatario no es un correo válido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/guides/{id}":{"get":{"tags":["GRE"],"summary":"Consultar una guía","operationId":"getGuidesId","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Correcto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`VALIDATION_ERROR`: El cuerpo, los parámetros o una regla del comprobante no son válidos. `fields` indica el campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHENTICATED`: Falta la clave API o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`TRIAL_EXPIRED`: La prueba gratuita venció.\n\n`TRIAL_EXHAUSTED`: La prueba gratuita consumió sus operaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`WORKSPACE_SUSPENDED`: El workspace está suspendido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND`: El recurso no existe en el workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`RATE_LIMITED`: Se superó el límite de peticiones. Respeta el header `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`INTERNAL_ERROR`: Error interno. Reintenta y comparte el `requestId` con soporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/issuer/openapi.json":{"get":{"tags":["Recursos"],"summary":"Especificación OpenAPI","operationId":"getOpenapiJson","security":[],"responses":{"200":{"description":"Recurso público."}}}},"/issuer/postman.json":{"get":{"tags":["Recursos"],"summary":"Colección Postman","operationId":"getPostmanJson","security":[],"responses":{"200":{"description":"Recurso público."}}}},"/issuer/llms.txt":{"get":{"tags":["Recursos"],"summary":"Resumen para asistentes de IA","operationId":"getLlmsTxt","security":[],"responses":{"200":{"description":"Recurso público."}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"asu_live_..."}},"schemas":{"ApiCargoTransport":{"additionalProperties":false,"description":"Servicio de transporte de carga sujeto a detracción (operación 1004).","properties":{"destination":{"$ref":"#/components/schemas/ApiTransportPoint"},"effectiveLoadReferenceValue":{"description":"Valor referencial sobre la carga efectiva (tipo 02).","type":"number"},"nominalLoadReferenceValue":{"description":"Valor referencial sobre la carga útil nominal (tipo 03).","type":"number"},"origin":{"$ref":"#/components/schemas/ApiTransportPoint"},"serviceReferenceValue":{"description":"Valor referencial del servicio de transporte (tipo 01).","type":"number"},"tripDetail":{"description":"Detalle del viaje (3120).","type":"string"}},"required":["origin","destination","tripDetail","serviceReferenceValue","effectiveLoadReferenceValue","nominalLoadReferenceValue"],"type":"object"},"ApiCharge":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"base":{"type":"number"},"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description","amount","base"],"type":"object"},"ApiCustomer":{"additionalProperties":false,"properties":{"address":{"type":"string"},"documentNumber":{"type":"string"},"documentType":{"enum":["0","1","4","6","7"],"type":"string"},"email":{"type":"string"},"name":{"type":"string"}},"required":["documentType","documentNumber"],"type":"object"},"ApiDetraction":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"bankAccount":{"type":"string"},"code":{"type":"string"},"paymentMethod":{"type":"string"},"percentage":{"type":"number"}},"required":["code","percentage","amount","paymentMethod","bankAccount"],"type":"object"},"ApiGuideActions":{"additionalProperties":false,"properties":{"pdfFormat":{"enum":["a4","a5","ticket80","ticket58","ticket50"],"type":"string"},"recipient":{"type":"string"},"sendEmail":{"type":"boolean"}},"type":"object"},"ApiGuideLegend":{"additionalProperties":false,"properties":{"code":{"type":"string"},"value":{"type":"string"}},"required":["code","value"],"type":"object"},"ApiGuideParty":{"additionalProperties":false,"properties":{"documentNumber":{"type":"string"},"documentType":{"type":"string"},"name":{"type":"string"}},"required":["documentType","documentNumber","name"],"type":"object"},"ApiGuideRelatedDocument":{"additionalProperties":false,"properties":{"documentType":{"type":"string"},"number":{"type":"string"}},"required":["documentType","number"],"type":"object"},"ApiGuideVehicle":{"additionalProperties":false,"properties":{"authorizationNumber":{"type":"string"},"brand":{"type":"string"},"circulationPermit":{"type":"string"},"model":{"type":"string"},"plate":{"type":"string"}},"required":["plate"],"type":"object"},"ApiInstallment":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"date":{"type":"string"}},"required":["date","amount"],"type":"object"},"ApiLegend":{"additionalProperties":false,"properties":{"code":{"type":"string"},"value":{"type":"string"}},"required":["code","value"],"type":"object"},"ApiLineIsc":{"additionalProperties":false,"description":"ISC: sistema 01 al valor (rate en %) o 02 específico (amountPerUnit por unidad).","properties":{"amountPerUnit":{"type":"number"},"rate":{"type":"number"},"system":{"enum":["01","02"],"type":"string"}},"required":["system"],"type":"object"},"ApiPayment":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"destinationCode":{"type":"string"},"methodCode":{"type":"string"},"methodName":{"type":"string"},"receivedAmount":{"type":"number"},"reference":{"type":"string"}},"required":["methodCode","amount"],"type":"object"},"ApiPerception":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"base":{"type":"number"},"code":{"type":"string"},"percentage":{"type":"number"},"total":{"description":"Base + percepción. Opcional: se calcula si no se envía.","type":"number"}},"required":["code","percentage","base","amount"],"type":"object"},"ApiPrepayment":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"documentType":{"description":"Comprobante del anticipo (catálogo 12): 02 factura o 03 boleta emitida por anticipos.","enum":["02","03"],"type":"string"},"number":{"type":"string"}},"required":["documentType","number","amount"],"type":"object"},"ApiPurchaseSettlement":{"additionalProperties":false,"description":"Liquidación de compra (04): domicilio del vendedor y lugar de la operación.","properties":{"operationPlace":{"$ref":"#/components/schemas/ApiSettlementPlace"},"sellerAddress":{"$ref":"#/components/schemas/ApiSettlementPlace"}},"required":["sellerAddress","operationPlace"],"type":"object"},"ApiRelatedDocument":{"additionalProperties":false,"properties":{"amount":{"description":"Importe total del documento relacionado.","type":"number"},"documentType":{"type":"string"},"issueDate":{"description":"Retención: fecha de emisión del comprobante del proveedor (AAAA-MM-DD).","type":"string"},"number":{"type":"string"},"paidAmount":{"description":"Retención: importe pagado sobre el que se retiene (por defecto, amount).","type":"number"},"paidDate":{"description":"Retención: fecha del pago (por defecto, la fecha de la retención).","type":"string"}},"required":["documentType","number"],"type":"object"},"ApiRetention":{"additionalProperties":false,"properties":{"amount":{"type":"number"},"base":{"type":"number"},"code":{"description":"Régimen de retención (catálogo 23): 01 = tasa 3 %, 02 = tasa 6 %.","enum":["01","02"],"type":"string"},"percentage":{"type":"number"}},"required":["code","percentage","base","amount"],"type":"object"},"ApiSecondaryDriver":{"additionalProperties":false,"properties":{"document":{"type":"string"},"license":{"type":"string"},"name":{"type":"string"}},"required":["name","document"],"type":"object"},"ApiSettlementPlace":{"additionalProperties":false,"properties":{"address":{"type":"string"},"typeCode":{"description":"Catálogo 60: 01 punto de venta, 02 producción, 03 extracción, 04 explotación, 05 otros.","type":"string"},"ubigeo":{"type":"string"}},"required":["ubigeo","address","typeCode"],"type":"object"},"ApiTransportPoint":{"additionalProperties":false,"properties":{"address":{"type":"string"},"ubigeo":{"description":"Ubigeo INEI de 6 dígitos.","type":"string"}},"required":["ubigeo","address"],"type":"object"},"CalculationItem":{"additionalProperties":false,"properties":{"code":{"type":"string"},"description":{"type":"string"},"discountAmount":{"type":"number"},"discountPercent":{"type":"number"},"icbper":{"description":"Bolsa plástica sujeta al ICBPER: quantity es el número de bolsas (entero).","type":"boolean"},"includesTax":{"type":"boolean"},"isc":{"$ref":"#/components/schemas/ApiLineIsc","description":"ISC (tributo 2000) de la línea; solo con taxCode 10."},"quantity":{"type":"number"},"sunatProductCode":{"description":"Código de producto SUNAT (catálogo 25), 8 dígitos. Obligatorio desde el 01/01/2027.","type":"string"},"taxCode":{"enum":["10","11","12","13","14","15","16","17","20","21","30","31","32","33","34","35","36","37","40"],"type":"string"},"unitCode":{"type":"string"},"unitPrice":{"type":"number"}},"required":["description","quantity","unitPrice"],"type":"object"},"GuideLine":{"additionalProperties":false,"properties":{"code":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCode":{"type":"string"}},"required":["description","quantity"],"type":"object"},"Account":{"additionalProperties":false,"properties":{"limits":{"additionalProperties":false,"properties":{"issuers":{"type":["number","null"]}},"required":["issuers"],"type":"object"},"mode":{"description":"Modo de la clave usada: `test` (asu_test_) o `live` (asu_live_). El plan y su consumo son los mismos en ambos.","enum":["test","live"],"type":"string"},"plan":{"type":["string","null"]},"subscriptionStatus":{"type":["string","null"]},"usage":{"additionalProperties":false,"properties":{"limit":{"type":["number","null"]},"period":{"type":"string"},"remaining":{"type":["number","null"]},"used":{"type":"number"}},"required":["used","limit","remaining","period"],"type":"object"},"workspace":{"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","slug","name"],"type":"object"}},"required":["workspace","mode","plan","subscriptionStatus","usage","limits"],"type":"object"},"CalculationRequest":{"additionalProperties":false,"properties":{"charges":{"items":{"$ref":"#/components/schemas/ApiCharge"},"type":"array"},"discountAmount":{"type":"number"},"discountPercent":{"type":"number"},"igvRate":{"description":"Tasa del IGV para las líneas gravadas (10): 18 general o 10.5 para restaurantes y hoteles MYPE.","enum":[18,10.5],"type":"number"},"items":{"items":{"$ref":"#/components/schemas/CalculationItem"},"type":"array"},"perception":{"$ref":"#/components/schemas/ApiPerception"},"prepayments":{"items":{"$ref":"#/components/schemas/ApiPrepayment"},"type":"array"}},"required":["items"],"type":"object"},"Calculation":{"additionalProperties":false,"properties":{"items":{"items":{"additionalProperties":false,"properties":{"base":{"description":"Valor de venta sin impuestos.","type":"number"},"code":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"taxCode":{"type":"string"},"total":{"type":"number"},"unitCode":{"type":"string"},"unitPrice":{"type":"number"}},"required":["code","description","quantity","unitCode","unitPrice","taxCode","base","tax","total"],"type":"object"},"type":"array"},"totals":{"additionalProperties":false,"properties":{"base":{"type":"number"},"charges":{"type":"number"},"icbper":{"type":"number"},"isc":{"type":"number"},"perception":{"type":"number"},"prepayments":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"}},"required":["base","tax","charges","prepayments","perception","icbper","isc","total"],"type":"object"}},"required":["items","totals"],"type":"object"},"Catalog":{"additionalProperties":false,"properties":{"description":{"type":"string"},"name":{"type":"string"},"rows":{"items":{"additionalProperties":false,"properties":{"code":{"type":"string"},"description":{"type":"string"},"percentage":{"type":["number","null"]},"supported":{"type":"boolean"}},"required":["code","description"],"type":"object"},"type":"array"},"sunatNumber":{"type":"string"}},"required":["description","name","rows","sunatNumber"],"type":"object"},"CatalogSummary":{"additionalProperties":false,"properties":{"description":{"type":"string"},"name":{"type":"string"},"sunatNumber":{"type":"string"}},"required":["name","sunatNumber","description"],"type":"object"},"CreateDocumentRequest":{"additionalProperties":false,"properties":{"additionalInformation":{"type":"string"},"affectedDocumentId":{"type":"string"},"cargoTransport":{"$ref":"#/components/schemas/ApiCargoTransport"},"charges":{"items":{"$ref":"#/components/schemas/ApiCharge"},"type":"array"},"currency":{"enum":["PEN","USD"],"type":"string"},"customer":{"$ref":"#/components/schemas/ApiCustomer"},"detraction":{"$ref":"#/components/schemas/ApiDetraction"},"discountAmount":{"type":"number"},"discountPercent":{"type":"number"},"documentType":{"enum":["01","03","04","07","08","20","40"],"type":"string"},"dueDate":{"type":"string"},"establishmentCode":{"type":"string"},"exchangeRate":{"type":"number"},"igvRate":{"description":"Tasa del IGV para las líneas gravadas (10): 18 general o 10.5 para restaurantes y hoteles MYPE.","enum":[18,10.5],"type":"number"},"installments":{"items":{"$ref":"#/components/schemas/ApiInstallment"},"type":"array"},"issueDate":{"type":"string"},"issueTime":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/CalculationItem"},"type":"array"},"legends":{"items":{"$ref":"#/components/schemas/ApiLegend"},"type":"array"},"noteReason":{"type":"string"},"noteReasonCode":{"type":"string"},"notes":{"type":"string"},"number":{"type":["number","null"]},"operationType":{"type":"string"},"paymentCondition":{"enum":["cash","credit"],"type":"string"},"payments":{"items":{"$ref":"#/components/schemas/ApiPayment"},"type":"array"},"perception":{"$ref":"#/components/schemas/ApiPerception"},"prepayments":{"items":{"$ref":"#/components/schemas/ApiPrepayment"},"type":"array"},"purchaseOrder":{"type":"string"},"purchaseSettlement":{"$ref":"#/components/schemas/ApiPurchaseSettlement"},"relatedDocuments":{"items":{"$ref":"#/components/schemas/ApiRelatedDocument"},"type":"array"},"retention":{"$ref":"#/components/schemas/ApiRetention"},"ruc":{"type":"string"},"series":{"type":["string","null"]},"vehiclePlate":{"type":"string"}},"required":["currency","customer","documentType","issueDate","items"],"type":"object"},"CreateEstablishmentRequest":{"additionalProperties":false,"properties":{"address":{"type":"string"},"code":{"description":"Código de 4 dígitos del local anexo (no puede ser 0000).","type":"string"},"email":{"type":"string"},"isDefault":{"type":"boolean"},"name":{"type":"string"},"phone":{"type":"string"},"ruc":{"type":"string"},"series":{"items":{"$ref":"#/components/schemas/EstablishmentSeries"},"type":"array"},"ubigeo":{"description":"Ubigeo INEI de 6 dígitos.","type":"string"}},"required":["code","name","address","ubigeo"],"type":"object"},"CreateGuideRequest":{"additionalProperties":false,"properties":{"actions":{"$ref":"#/components/schemas/ApiGuideActions"},"affectedDocument":{"$ref":"#/components/schemas/ApiGuideRelatedDocument"},"arrivalAddress":{"type":"string"},"arrivalEstablishmentCode":{"description":"Motivo 04: código de establecimiento SUNAT de llegada (4 dígitos).","type":"string"},"arrivalUbigeo":{"type":"string"},"carrierMtcNumber":{"type":"string"},"carrierName":{"type":"string"},"carrierRuc":{"type":"string"},"consignee":{"$ref":"#/components/schemas/ApiGuideParty"},"containerNumber":{"type":"string"},"customer":{"$ref":"#/components/schemas/ApiCustomer"},"driverDocument":{"type":"string"},"driverDocumentType":{"description":"Tipo de documento del conductor (catálogo 06): 1 DNI, 4 CE, 7 pasaporte.","type":"string"},"driverLastName":{"description":"Apellidos del conductor principal. Si se omite, se toman de driverName.","type":"string"},"driverLicense":{"type":"string"},"driverName":{"type":"string"},"establishmentCode":{"type":"string"},"issueDate":{"type":"string"},"issueTime":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/GuideLine"},"type":"array"},"legends":{"items":{"$ref":"#/components/schemas/ApiGuideLegend"},"type":"array"},"motiveCode":{"enum":["01","02","04","06","13"],"type":"string"},"motiveDescription":{"type":"string"},"notes":{"type":"string"},"number":{"type":["number","null"]},"packages":{"type":"number"},"portCode":{"type":"string"},"relatedDocument":{"$ref":"#/components/schemas/ApiGuideRelatedDocument"},"relatedDocuments":{"items":{"$ref":"#/components/schemas/ApiGuideRelatedDocument"},"type":"array"},"remitter":{"$ref":"#/components/schemas/ApiGuideParty"},"ruc":{"type":"string"},"secondaryDrivers":{"items":{"$ref":"#/components/schemas/ApiSecondaryDriver"},"type":"array"},"secondaryVehiclePlates":{"items":{"type":"string"},"type":"array"},"secondaryVehicles":{"items":{"$ref":"#/components/schemas/ApiGuideVehicle"},"type":"array"},"series":{"type":["string","null"]},"startAddress":{"type":"string"},"startEstablishmentCode":{"description":"Motivo 04: código de establecimiento SUNAT de partida (4 dígitos).","type":"string"},"startUbigeo":{"type":"string"},"transferDate":{"type":"string"},"transportMode":{"enum":["01","02"],"type":"string"},"transshipmentIndicator":{"type":"boolean"},"vehicleCategoryM1":{"type":"boolean"},"vehiclePlate":{"type":"string"},"weightKg":{"type":"number"}},"required":["arrivalAddress","arrivalUbigeo","customer","issueDate","items","motiveCode","startAddress","startUbigeo","transportMode"],"type":"object"},"CreateIssuerRequest":{"additionalProperties":false,"properties":{"fiscalAddress":{"type":"string"},"fiscalDepartment":{"type":"string"},"fiscalDistrict":{"type":"string"},"fiscalProvince":{"type":"string"},"fiscalUbigeo":{"type":"string"},"legalName":{"type":"string"},"ruc":{"type":"string"},"tradeName":{"type":"string"}},"required":["legalName","ruc"],"type":"object"},"CreateVoidRequest":{"additionalProperties":false,"properties":{"documents":{"items":{"$ref":"#/components/schemas/VoidItem"},"type":"array"},"ruc":{"type":"string"}},"required":["documents"],"type":"object"},"Document":{"additionalProperties":false,"properties":{"createdAt":{"type":["string","null"]},"currency":{"type":["string","null"]},"customer":{"anyOf":[{"additionalProperties":false,"properties":{"documentNumber":{"type":"string"},"documentType":{"type":"string"},"name":{"type":"string"}},"required":["documentType","documentNumber","name"],"type":"object"},{"type":"null"}]},"environment":{"type":"string"},"fullNumber":{"description":"Serie y número, por ejemplo F001-123.","type":["string","null"]},"id":{"description":"Identificador del documento en API SUNAT (UUID).","type":"string"},"issueDate":{"type":["string","null"]},"issuerRuc":{"type":["string","null"]},"links":{"additionalProperties":false,"properties":{"cdr":{"type":["string","null"]},"pdf":{"type":"string"},"self":{"type":"string"},"xml":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["self","pdf","xml","zip","cdr"],"type":"object"},"number":{"type":["number","null"]},"series":{"type":"string"},"status":{"type":"string"},"sunat":{"$ref":"#/components/schemas/SunatResult"},"test":{"description":"true si se emitió con una clave asu_test_ (sandbox en SUNAT beta).","type":"boolean"},"total":{"type":["number","null"]},"type":{"description":"Tipo SUNAT: 01, 03, 07, 08, 09, 20 o 40.","type":"string"},"updatedAt":{"type":["string","null"]}},"required":["id","type","series","number","fullNumber","status","environment","test","issuerRuc","issueDate","currency","total","customer","sunat","links","createdAt","updatedAt"],"type":"object"},"DocumentPage":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Document"},"type":"array"},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"type":"object"},"EmailDelivery":{"additionalProperties":false,"properties":{"attempts":{"type":"number"},"createdAt":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"id":{"type":"string"},"recipient":{"type":"string"},"sentAt":{"type":["string","null"]},"status":{"type":"string"}},"required":["id","recipient","status","attempts","errorMessage","sentAt","createdAt"],"type":"object"},"Error":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"fields":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},"message":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","retryable","fields","requestId"],"type":"object"}},"required":["error"],"type":"object"},"Establishment":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"address":{"type":"string"},"code":{"type":"string"},"email":{"type":"string"},"isDefault":{"type":"boolean"},"name":{"type":"string"},"phone":{"type":"string"},"series":{"items":{"$ref":"#/components/schemas/Series"},"type":"array"},"ubigeo":{"type":"string"}},"required":["code","name","address","ubigeo","phone","email","isDefault","active"],"type":"object"},"EstablishmentSeries":{"additionalProperties":false,"properties":{"documentType":{"enum":["01","03","07","08","09","20"],"type":"string"},"mode":{"enum":["automatic","manual"],"type":"string"},"nextNumber":{"description":"Obligatorio en series manuales.","type":"number"},"series":{"description":"Serie de 4 caracteres, por ejemplo F002.","type":"string"}},"required":["documentType","series"],"type":"object"},"Issuer":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"address":{"additionalProperties":false,"properties":{"department":{"type":"string"},"district":{"type":"string"},"line":{"type":"string"},"province":{"type":"string"},"ubigeo":{"type":"string"}},"required":["line","ubigeo","department","province","district"],"type":"object"},"createdAt":{"type":["string","null"]},"credentials":{"additionalProperties":false,"properties":{"beta":{"$ref":"#/components/schemas/IssuerCredential","description":"Derivada: usuario MODDATOS con el certificado real del RUC. `validatedAt` es la última validación beta aceptada."},"produccion":{"$ref":"#/components/schemas/IssuerCredential","description":"El único juego guardado: usuario SOL secundario, clave y certificado reales. `validatedAt` es la prueba real aceptada."}},"required":["beta","produccion"],"type":"object"},"environment":{"description":"Solo informativo: `produccion` si el RUC está habilitado, si no `beta`. El ambiente de cada emisión lo decide la clave.","type":"string"},"isDefault":{"type":"boolean"},"legalName":{"type":"string"},"livemode":{"description":"Modo del RUC: `true` = producción (claves `asu_live_`), `false` = prueba (claves `asu_test_`, SUNAT beta). El mismo RUC puede existir una vez en cada modo.","type":"boolean"},"productionEnabled":{"description":"true cuando las claves `asu_live_` ya pueden emitir en SUNAT producción.","type":"boolean"},"ruc":{"type":"string"},"status":{"description":"Estado de la validación beta del RUC.","type":"string"},"tradeName":{"type":"string"},"updatedAt":{"type":["string","null"]}},"required":["ruc","livemode","legalName","tradeName","address","active","isDefault","environment","productionEnabled","status","credentials","createdAt","updatedAt"],"type":"object"},"IssuerCredential":{"additionalProperties":false,"properties":{"certificateExpiresAt":{"type":["string","null"]},"configured":{"type":"boolean"},"hasCertificate":{"type":"boolean"},"hasSolPassword":{"type":"boolean"},"lastError":{"type":["string","null"]},"solUser":{"type":"string"},"validatedAt":{"type":["string","null"]}},"required":["configured","solUser","hasSolPassword","hasCertificate","certificateExpiresAt","validatedAt","lastError"],"type":"object"},"IssuerCredentialsRequest":{"additionalProperties":false,"properties":{"certificateBase64":{"description":"Certificado PFX o P12 en base64.","type":"string"},"certificatePassword":{"type":"string"},"environment":{"description":"Obsoleto: se ignora. La clave decide el RUC: `asu_test_` configura el RUC de prueba (solo certificado; SUNAT beta firma con el usuario genérico MODDATOS) y `asu_live_` el RUC de producción (usuario SOL secundario, clave, certificado y GRE reales).","enum":["beta","produccion"],"type":"string"},"fiscalAddress":{"type":"string"},"fiscalDepartment":{"type":"string"},"fiscalDistrict":{"type":"string"},"fiscalProvince":{"type":"string"},"fiscalUbigeo":{"type":"string"},"greClientId":{"description":"Credenciales de la API de guías (GRE) de SUNAT.","type":"string"},"greClientSecret":{"type":"string"},"logoBase64":{"description":"Logo para el PDF: data:image/png;base64,... o data:image/jpeg;base64,...","type":"string"},"solPassword":{"type":"string"},"solUser":{"description":"Usuario SOL secundario real del RUC. Obligatorio con `asu_live_`; con `asu_test_` se ignora.","type":"string"}},"type":"object"},"IssuerValidation":{"additionalProperties":false,"properties":{"documentNumber":{"type":["string","null"]},"environment":{"enum":["beta","produccion"],"type":"string"},"message":{"type":["string","null"]},"status":{"type":["string","null"]},"voidNumber":{"type":["string","null"]}},"required":["environment","status","documentNumber","voidNumber","message"],"type":"object"},"CatalogList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/CatalogSummary"},"type":"array"}},"required":["data"],"type":"object"},"EmailDeliveryList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/EmailDelivery"},"type":"array"}},"required":["data"],"type":"object"},"EstablishmentList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Establishment"},"type":"array"}},"required":["data"],"type":"object"},"IssuerList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Issuer"},"type":"array"}},"required":["data"],"type":"object"},"SeriesList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Series"},"type":"array"}},"required":["data"],"type":"object"},"VoidList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Void"},"type":"array"}},"required":["data"],"type":"object"},"Ping":{"additionalProperties":false,"properties":{"keyType":{"type":"string"},"plan":{"type":["string","null"]},"workspace":{"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"}},"required":["workspace","keyType","plan"],"type":"object"},"ProductSearch":{"additionalProperties":false,"properties":{"data":{"items":{"additionalProperties":false,"properties":{"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description"],"type":"object"},"type":"array"},"hasMore":{"type":"boolean"},"limit":{"type":"number"},"page":{"type":"number"},"total":{"type":"number"},"version":{"type":"string"}},"required":["data","total","page","limit","hasMore","version"],"type":"object"},"SendEmailRequest":{"additionalProperties":false,"properties":{"format":{"enum":["a4","a5","ticket80","ticket58","ticket50"],"type":"string"},"recipient":{"type":"string"}},"type":"object"},"Series":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"documentType":{"type":"string"},"establishmentCode":{"type":"string"},"mode":{"type":"string"},"nextNumber":{"type":"number"},"series":{"type":"string"}},"required":["documentType","series","nextNumber","mode","active","establishmentCode"],"type":"object"},"SunatResult":{"additionalProperties":false,"properties":{"attempts":{"type":"number"},"description":{"type":["string","null"]},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"responseCode":{"description":"Código de respuesta del CDR. 0 = aceptado.","type":["string","null"]},"ticket":{"description":"Ticket de SUNAT cuando el envío es asíncrono (resúmenes, bajas, GRE).","type":["string","null"]}},"required":["ticket","responseCode","description","errorCode","errorMessage","attempts"],"type":"object"},"UpdateIssuerRequest":{"additionalProperties":false,"properties":{"active":{"type":"boolean"}},"required":["active"],"type":"object"},"ValidateIssuerRequest":{"additionalProperties":false,"properties":{"confirmation":{"type":"string"}},"type":"object"},"Void":{"additionalProperties":false,"properties":{"createdAt":{"type":["string","null"]},"documents":{"items":{"additionalProperties":false,"properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"],"type":"object"},"type":"array"},"environment":{"type":"string"},"id":{"type":"string"},"identifier":{"type":"string"},"issuerRuc":{"type":["string","null"]},"links":{"additionalProperties":false,"properties":{"self":{"type":"string"}},"required":["self"],"type":"object"},"status":{"type":"string"},"sunat":{"$ref":"#/components/schemas/SunatResult"},"type":{"description":"RA = comunicación de baja (facturas y notas); RC = resumen diario (boletas); RR = reversión (retenciones y percepciones).","enum":["RA","RC","RR"],"type":"string"},"updatedAt":{"type":["string","null"]}},"required":["id","type","identifier","status","environment","issuerRuc","sunat","documents","links","createdAt","updatedAt"],"type":"object"},"VoidItem":{"additionalProperties":false,"properties":{"documentId":{"type":"string"},"reason":{"type":"string"}},"required":["documentId","reason"],"type":"object"},"WebhookEvent":{"additionalProperties":false,"properties":{"createdAt":{"type":"string"},"data":{"$ref":"#/components/schemas/Document"},"id":{"type":"string"},"livemode":{"description":"true si el evento viene de producción (asu_live_); false en modo prueba (asu_test_).","type":"boolean"},"type":{"enum":["document.accepted","document.observed","document.rejected","document.failed","document.voided","webhook.test"],"type":"string"}},"required":["id","type","createdAt","livemode","data"],"type":"object"}}}}