{"openapi":"3.1.0","info":{"title":"GCContable - API SUNAT","description":"\n## GCContable - API SUNAT\n\nGateway multi-tenant para integrar los servicios de SUNAT Perú en tu aplicación.\n\n---\n\n### Autenticación\n\nTodas las peticiones requieren el header:\n\n```\nX-API-Key: tu_api_key\n```\n\n> Contacta a GCContable en [gccontable.es/acceso](https://gccontable.es/acceso) para obtener tu API Key.\n\n---\n\n### Credenciales SUNAT requeridas\n\nAlgunos servicios requieren que configures tus propias credenciales SUNAT:\n\n| Tipo | Servicios | Cómo configurar |\n|------|-----------|-----------------|\n| **SUNAT** (client_id + secret) | Validar comprobante, SIRE | `PUT /admin/clientes/{id}/credenciales` |\n| **SOL** (usuario + clave SOL) | GRE, SSPP, Documentos aduaneros | `PUT /admin/clientes/{id}/credenciales-sol` |\n\n---\n\n### Límites de uso\n\n| Plan | Requests/día |\n|------|-------------|\n| Básico | 100 |\n| Pro | 1,000 |\n| Enterprise | 10,000 |\n\n---\n\n### Respuesta estándar\n\n```json\n{ \"success\": true, \"data\": { ... } }\n```\n\nEn caso de error:\n\n```json\n{ \"success\": false, \"error\": \"Descripción del problema\", \"sunat\": { \"codigo\": \"...\", \"mensaje\": \"...\" } }\n```\n","contact":{"name":"GCContable","url":"https://gccontable.es/"},"version":"1.0.0"},"paths":{"/contribuyente/ruc/{ruc}":{"get":{"tags":["Contribuyente"],"summary":"Consultar datos básicos de un RUC","description":"Retorna razón social, estado (ACTIVO/BAJA), condición (HABIDO/NO HABIDO) y dirección fiscal de un RUC. No requiere credenciales SUNAT propias.","operationId":"get_ruc_contribuyente_ruc__ruc__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/ruc/{ruc}/full":{"get":{"tags":["Contribuyente"],"summary":"Consultar datos completos de un RUC","description":"Retorna todos los datos disponibles del contribuyente: razón social, estado, condición, dirección, actividad económica (CIIU), tipo de contribuyente, sistema de contabilidad y más. No requiere credenciales SUNAT propias.","operationId":"get_ruc_full_contribuyente_ruc__ruc__full_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/ruc/lote":{"post":{"tags":["Contribuyente"],"summary":"Consultar hasta 20 RUCs en paralelo","description":"Consulta múltiples RUCs de forma simultánea. Máximo 20 por petición. Útil para validar proveedores o clientes en lote. No requiere credenciales SUNAT propias.\n\n**Body:** `{ \"rucs\": [\"20603408161\", \"10456789012\"] }`","operationId":"post_ruc_lote_contribuyente_ruc_lote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RucLoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/contribuyente/dni/{dni}":{"get":{"tags":["Contribuyente"],"summary":"Consultar datos de una persona por DNI","description":"Retorna nombres, apellidos y datos del titular del DNI según el padrón RENIEC.\n\n**`dni`:** 8 dígitos numéricos.\n\nNo requiere credenciales SUNAT propias.","operationId":"get_dni_contribuyente_dni__dni__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dni","in":"path","required":true,"schema":{"type":"string","title":"Dni"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/uit":{"get":{"tags":["Contribuyente"],"summary":"Valor de la UIT por año","description":"Retorna el valor oficial de la Unidad Impositiva Tributaria (UIT) publicado por SUNAT.\n\n**Parámetro opcional `anio`:** año de consulta (ej: `2025`). Si se omite, retorna el del año actual.\n\nNo requiere credenciales SUNAT propias.","operationId":"get_uit_contribuyente_uit_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"anio","in":"query","required":false,"schema":{"type":"integer","title":"Anio"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/uit/historico":{"get":{"tags":["Contribuyente"],"summary":"Histórico de la UIT (rango de años)","description":"Retorna los valores de la UIT para un rango de años.\n\n**Parámetros:** `anio_desde` y `anio_hasta` (máximo 25 años de diferencia).\n\nNo requiere credenciales SUNAT propias.","operationId":"get_uit_historico_contribuyente_uit_historico_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"anio_desde","in":"query","required":true,"schema":{"type":"integer","title":"Anio Desde"}},{"name":"anio_hasta","in":"query","required":true,"schema":{"type":"integer","title":"Anio Hasta"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/calendario/{ruc}":{"get":{"tags":["Contribuyente"],"summary":"Calendario de vencimientos tributarios por RUC","description":"Retorna las fechas de vencimiento de obligaciones tributarias mensuales (PDT 621 - IGV/Renta) según el último dígito del RUC y el cronograma oficial SUNAT.\n\n**Parámetro opcional `periodo`:** formato `YYYYMM` (ej: `202501`). Si se omite, retorna los próximos meses desde el actual.\n\nNo requiere credenciales SUNAT propias.","operationId":"get_calendario_contribuyente_calendario__ruc__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":false,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/controlcpe":{"get":{"tags":["Contribuyente"],"summary":"CONTROLCPE - Consultar estado de CPE (Factoring)","description":"Consulta el estado de Comprobantes de Pago Electrónicos (CPE) en el sistema MIGE Gestión Factoring de SUNAT. Permite verificar si una factura está disponible para cesión al sistema financiero (factoring).\n\n**Requiere:** credenciales SUNAT configuradas (`PUT /admin/clientes/{id}/credenciales`)","operationId":"get_controlcpe_contribuyente_controlcpe_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":false,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/periodos":{"get":{"tags":["Contribuyente"],"summary":"SIRE - Listar periodos disponibles","description":"Lista los periodos con registros omisos (sin presentar) en el SIRE para el RUC indicado.\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol` y `/credenciales-gre`)","operationId":"get_sire_periodos_contribuyente_sire_periodos_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/ventas":{"get":{"tags":["Contribuyente"],"summary":"SIRE - Registro de Ventas paginado (desde BD)","description":"Devuelve los comprobantes del RVIE paginados desde la BD local.\n\n**Requiere** haber ejecutado primero `POST /{ruc}/sire/ventas/sincronizar` y esperar que el job quede en `status: completado`.\n\n**`periodo`:** formato `YYYYMM` (ej: `202601`)\n\n**`page`** y **`per_page`** (max 500) controlan la pagina a retornar.\n\nPara 2M registros con per_page=100: total_paginas=20,000.","operationId":"get_sire_ventas_contribuyente_sire_ventas_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":true,"schema":{"type":"string","title":"Periodo"}},{"name":"after_id","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"After Id"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Per Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/compras":{"get":{"tags":["Contribuyente"],"summary":"SIRE - Registro de Compras paginado (desde BD)","description":"Devuelve los comprobantes del RCE paginados desde la BD local.\n\n**Requiere** haber ejecutado primero `POST /{ruc}/sire/compras/sincronizar` y esperar que el job quede en `status: completado`.\n\n**`periodo`:** formato `YYYYMM` (ej: `202501`)\n\n**`page`** y **`per_page`** (max 500) controlan la pagina a retornar.","operationId":"get_sire_compras_contribuyente_sire_compras_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":true,"schema":{"type":"string","title":"Periodo"}},{"name":"after_id","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"After Id"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Per Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/compras/sincronizar":{"post":{"tags":["Contribuyente"],"summary":"SIRE - Iniciar sincronizacion de Compras en background","description":"Inicia la descarga del Registro de Compras de SUNAT en segundo plano y retorna un `job_id` de inmediato.\n\nConsulta el progreso con `GET /{ruc}/sire/jobs/{job_id}` hasta que `status` sea `completado` o `error`.\n\nLuego lee los datos con `GET /{ruc}/sire/compras?periodo=YYYYMM&page=1`.\n\n**`periodo`:** formato `YYYYMM` (ej: `202501`)","operationId":"sincronizar_sire_compras_contribuyente_sire_compras_sincronizar_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":true,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/jobs/{job_id}":{"get":{"tags":["Contribuyente"],"summary":"SIRE - Estado de un job de sincronizacion","description":"Consulta el estado de un job iniciado con `POST /{ruc}/sire/compras/sincronizar`.\n\n**`status`:** `procesando` | `completado` | `error`\n\n**`progreso`:** texto descriptivo del paso actual (actualizado en tiempo real).","operationId":"get_sire_job_contribuyente_sire_jobs__job_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sire/ventas/sincronizar":{"post":{"tags":["Contribuyente"],"summary":"SIRE - Iniciar sincronizacion de Ventas en background (streaming)","description":"Inicia la descarga del Registro de Ventas (RVIE) de SUNAT en segundo plano con soporte streaming para 2M+ registros.\n\nRetorna un `job_id` de inmediato. Consulta el progreso con `GET /{ruc}/sire/jobs/{job_id}` cada 15-30 segundos.\n\nEl progreso muestra: `450,000 registros procesados...`\n\nUna vez `completado`, usa `GET /{ruc}/sire/ventas?periodo=YYYYMM&page=1`.\n\n**Tiempo estimado:** 2-15 minutos segun el volumen del periodo.","operationId":"sincronizar_sire_ventas_contribuyente_sire_ventas_sincronizar_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"query","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"periodo","in":"query","required":true,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/gre/emitir":{"post":{"tags":["Contribuyente"],"summary":"GRE - Emitir Guía de Remisión Electrónica","description":"Emite una Guía de Remisión Electrónica (GRE) a través del portal SOL de SUNAT.\n\n**Requiere:** credenciales SOL configuradas (`PUT /admin/clientes/{id}/credenciales-sol`)\n\nEl body debe seguir el formato JSON de GRE definido por SUNAT.","operationId":"post_gre_emitir_contribuyente_gre_emitir_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/contribuyente/gre/consultar":{"get":{"tags":["Contribuyente"],"summary":"GRE - Consultar estado de una Guía de Remisión","description":"Consulta el estado de procesamiento de una GRE emitida.\n\n**Parámetros:** `serie` (ej: `T001`) y `numero` (ej: `1`)\n\n**Requiere:** credenciales SOL configuradas.","operationId":"get_gre_consultar_contribuyente_gre_consultar_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"numero","in":"query","required":true,"schema":{"type":"string","title":"Numero"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/gre/confirmar":{"post":{"tags":["Contribuyente"],"summary":"GRE - Confirmar recepción de una Guía de Remisión","description":"El transportista o destinatario confirma la recepción de una GRE.\n\n**Requiere:** credenciales SOL configuradas.","operationId":"post_gre_confirmar_contribuyente_gre_confirmar_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/contribuyente/tipo-cambio/sunat":{"get":{"tags":["Contribuyente"],"summary":"Tipo de cambio SUNAT (USD/PEN)","description":"Retorna el tipo de cambio oficial publicado por SUNAT para el dólar americano.\n\n**Parámetro opcional `fecha`:** formato `YYYY-MM-DD`. Si se omite, retorna el del día de hoy.\n\nNo requiere credenciales SUNAT propias.","operationId":"get_tipo_cambio_sunat_contribuyente_tipo_cambio_sunat_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"fecha","in":"query","required":false,"schema":{"type":"string","title":"Fecha"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/tipo-cambio/sbs":{"get":{"tags":["Contribuyente"],"summary":"Tipo de cambio SBS promedio","description":"Retorna el tipo de cambio promedio publicado por la SBS (Superintendencia de Banca y Seguros).\n\n**Parámetro `moneda`:** código de moneda ISO 4217 (ej: `USD`, `EUR`). Por defecto: `USD`.\n\n**Parámetro opcional `fecha`:** formato `YYYY-MM-DD`. Si se omite, retorna el del día de hoy.\n\nNo requiere credenciales SUNAT propias.","operationId":"get_tipo_cambio_sbs_contribuyente_tipo_cambio_sbs_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"moneda","in":"query","required":false,"schema":{"type":"string","default":"USD","title":"Moneda"}},{"name":"fecha","in":"query","required":false,"schema":{"type":"string","title":"Fecha"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/sspp/enviar":{"post":{"tags":["Contribuyente"],"summary":"SSPP - Enviar comprobante XML (ZIP en Base64)","description":"Envía un comprobante electrónico en formato XML (empaquetado en ZIP) a SUNAT a través del servicio SSPP Receptor XML.\n\n**`nombreArchivo`:** nombre del ZIP con formato `{ruc}-{tipoComp}-{serie}-{numero}.zip` (ej: `20603408161-01-F001-1234.zip`)\n\n**`archivo`:** contenido del ZIP codificado en Base64.\n\n**Requiere:** credenciales SOL configuradas (`PUT /admin/clientes/{id}/credenciales-sol`)","operationId":"post_sspp_enviar_contribuyente_sspp_enviar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsppEnviarRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/contribuyente/sspp/{identificador}/estado":{"get":{"tags":["Contribuyente"],"summary":"SSPP - Consultar estado/CDR de un comprobante","description":"Consulta el estado de procesamiento y el CDR (Constancia de Recepción) de un comprobante previamente enviado por SSPP.\n\n**`identificador`:** formato `{ruc}-{tipoComp}-{serie}-{numero}` (ej: `20603408161-01-F001-1234`)\n\n**Requiere:** credenciales SOL configuradas.","operationId":"get_sspp_estado_contribuyente_sspp__identificador__estado_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"identificador","in":"path","required":true,"schema":{"type":"string","title":"Identificador"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/validarcomprobante":{"post":{"tags":["Contribuyente"],"summary":"Validar comprobante de pago","description":"Verifica si un comprobante de pago (factura, boleta, etc.) es válido en SUNAT.\n\n**`codComp`:** tipo de comprobante — `01` Factura, `03` Boleta, `07` Nota de Crédito, `08` Nota de Débito\n\n**`fechaEmision`:** formato `YYYY-MM-DD`\n\n**`monto`:** importe total del comprobante (opcional pero recomendado)\n\n**Requiere:** credenciales SUNAT configuradas (`PUT /admin/clientes/{id}/credenciales`)","operationId":"post_validar_comprobante_contribuyente__ruc__validarcomprobante_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidarComprobanteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/tipo-cambio/bcr":{"get":{"tags":["Contribuyente"],"summary":"Tipo de cambio histórico BCR (Banco Central de Reserva)","description":"Retorna el tipo de cambio histórico diario publicado por el BCRP.\n\n**`moneda`:** `USD` o `EUR` (por defecto `USD`).\n\n**`fecha_desde` / `fecha_hasta`:** rango en formato `YYYY-MM-DD`. Máximo 366 días por consulta. Por defecto: últimos 30 días.\n\nNo requiere credenciales SUNAT.","operationId":"get_tc_bcr_contribuyente_tipo_cambio_bcr_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"moneda","in":"query","required":false,"schema":{"type":"string","default":"USD","title":"Moneda"}},{"name":"fecha_desde","in":"query","required":false,"schema":{"type":"string","title":"Fecha Desde"}},{"name":"fecha_hasta","in":"query","required":false,"schema":{"type":"string","title":"Fecha Hasta"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/tipo-cambio/bcr/fecha":{"get":{"tags":["Contribuyente"],"summary":"Tipo de cambio BCR para una fecha específica","description":"Retorna el tipo de cambio del BCRP para una fecha exacta.\n\nSi la fecha es fin de semana o feriado, retorna el último día hábil anterior.\n\n**`fecha`:** formato `YYYY-MM-DD`. Si se omite, retorna el de hoy.\n\nNo requiere credenciales SUNAT.","operationId":"get_tc_bcr_fecha_contribuyente_tipo_cambio_bcr_fecha_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"moneda","in":"query","required":false,"schema":{"type":"string","default":"USD","title":"Moneda"}},{"name":"fecha","in":"query","required":false,"schema":{"type":"string","title":"Fecha"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/padron/{ruc}/buen-contribuyente":{"get":{"tags":["Contribuyente"],"summary":"Verificar si un RUC es Buen Contribuyente","description":"Verifica si el RUC está en el Padrón de Buenos Contribuyentes de SUNAT.\n\nLos buenos contribuyentes tienen **5 días adicionales** para pagar el IGV mensual.\n\nDato actualizado diariamente. No requiere credenciales SUNAT.","operationId":"get_buen_contribuyente_contribuyente_padron__ruc__buen_contribuyente_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/padron/{ruc}/agente-retencion":{"get":{"tags":["Contribuyente"],"summary":"Verificar si un RUC es Agente de Retención","description":"Verifica si el RUC está designado como Agente de Retención por SUNAT.\n\nSi lo es, este proveedor **retendrá el 3%** sobre el valor neto de tus facturas.\n\nNo requiere credenciales SUNAT.","operationId":"get_agente_retencion_contribuyente_padron__ruc__agente_retencion_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/padron/{ruc}/agente-percepcion":{"get":{"tags":["Contribuyente"],"summary":"Verificar si un RUC es Agente de Percepción","description":"Verifica si el RUC está designado como Agente de Percepción por SUNAT.\n\nSi lo es, este proveedor **cobrará un 2% adicional** sobre el precio de venta. Este importe es un crédito para tu IGV.\n\nNo requiere credenciales SUNAT.","operationId":"get_agente_percepcion_contribuyente_padron__ruc__agente_percepcion_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/padron/{ruc}/perfil-tributario":{"get":{"tags":["Contribuyente"],"summary":"Perfil tributario completo de un RUC","description":"Consulta en paralelo el perfil tributario completo de un RUC:\n\n- ¿Es Buen Contribuyente?\n- ¿Es Agente de Retención?\n- ¿Es Agente de Percepción?\n\nÚtil antes de registrar un nuevo proveedor o cliente. No requiere credenciales SUNAT.","operationId":"get_perfil_tributario_contribuyente_padron__ruc__perfil_tributario_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/detracciones":{"get":{"tags":["Contribuyente"],"summary":"SPOT - Consultar pagos de detracciones","description":"Consulta los pagos de detracciones (SPOT) depositados en el Banco de la Nación para el RUC del cliente, según los registros del portal SUNAT.\n\n**`ruc`:** debe coincidir con el RUC configurado en las credenciales SOL del cliente.\n\n**`fecha_inicio` / `fecha_fin`:** rango de fechas en formato `DD/MM/YYYY` (ej: `01/04/2026` a `30/04/2026`).\n\n**`tipo_cuenta`:** `1` Convencional (default), `2` IVAP, `3` Ley 30737.\n\n**`tipo_consulta`:** `pagosIndividuales` (default), `pagosMasivos`, `pagosTransportePasajeros`.\n\n**`periodo`:** periodo tributario opcional, formato `YYYYMM` (ej: `202604`).\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol`). No requiere client_id/secret adicional.","operationId":"get_detracciones_contribuyente__ruc__detracciones_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":true,"schema":{"type":"string","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":true,"schema":{"type":"string","title":"Fecha Fin"}},{"name":"tipo_cuenta","in":"query","required":false,"schema":{"type":"string","default":"1","title":"Tipo Cuenta"}},{"name":"tipo_consulta","in":"query","required":false,"schema":{"type":"string","default":"pagosIndividuales","title":"Tipo Consulta"}},{"name":"periodo","in":"query","required":false,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/retenciones":{"get":{"tags":["Contribuyente"],"summary":"IGV - Consultar retenciones del sujeto retenido","description":"Consulta las retenciones del IGV aplicadas al RUC del cliente como sujeto retenido, segun el Regimen de Retenciones del IGV del portal SUNAT.\n\n**`fecha_inicio` / `fecha_fin`:** rango en formato `DD/MM/YYYY` (ej: `01/04/2026` a `30/04/2026`).\n\n**`periodo`:** periodo tributario opcional, formato `YYYYMM` (ej: `202604`).\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol`). No requiere client_id/secret adicional.","operationId":"get_retenciones_contribuyente__ruc__retenciones_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":true,"schema":{"type":"string","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":true,"schema":{"type":"string","title":"Fecha Fin"}},{"name":"periodo","in":"query","required":false,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/percepciones":{"get":{"tags":["Contribuyente"],"summary":"IGV - Consultar percepciones del sujeto percibido","description":"Consulta las percepciones del IGV aplicadas al RUC del cliente como sujeto percibido, segun el Regimen de Percepciones del IGV del portal SUNAT.\n\n**`fecha_inicio` / `fecha_fin`:** rango en formato `DD/MM/YYYY` (ej: `01/04/2026` a `30/04/2026`).\n\n**`periodo`:** periodo tributario opcional, formato `YYYYMM` (ej: `202604`).\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol`). No requiere client_id/secret adicional.","operationId":"get_percepciones_contribuyente__ruc__percepciones_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":true,"schema":{"type":"string","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":true,"schema":{"type":"string","title":"Fecha Fin"}},{"name":"periodo","in":"query","required":false,"schema":{"type":"string","title":"Periodo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/declaraciones-y-pagos":{"get":{"tags":["Contribuyente"],"summary":"Consultar declaraciones y pagos presentados a SUNAT","description":"Consulta el historial de declaraciones y pagos del portal SUNAT (modulo Consulta General, codigo 12.8.1.1.2).\n\n**Busqueda por fecha** (use `fecha_inicio` + `fecha_fin`):\n- Formato `DD/MM/YYYY`. Rango maximo 6 meses.\n\n**Busqueda por periodo** (use `periodo_desde` + `periodo_hasta`):\n- Formato `YYYYMM` (ej: `202601`). Alternativa a fechas.\n\n**`tipo`:** `1` Declaraciones determinativas (IGV/Renta/ISC/Boletas - default), `2` Declaraciones informativas (DAOT/Predios/etc).\n\n**`formulario`:** codigo de formulario (ej: `0621`) o `TODOS` (default). Ej: `0621` PDT IGV-Renta, `1662` Boleta de Pago Virtual, `0601` Planilla Electronica.\n\n**`importe`:** `1` Importe >= 0 (default), `2` Importe > 0, `3` Importe = 0.\n\n**Columnas retornadas:** periodo, num_formulario, num_orden, desc_formulario, fecha_presentacion, banco_receptor, cod_tributo, importe_pagado.\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol`).","operationId":"get_declaraciones_y_pagos_contribuyente__ruc__declaraciones_y_pagos_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":false,"schema":{"type":"string","default":"","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":false,"schema":{"type":"string","default":"","title":"Fecha Fin"}},{"name":"tipo","in":"query","required":false,"schema":{"type":"string","default":"1","title":"Tipo"}},{"name":"formulario","in":"query","required":false,"schema":{"type":"string","default":"TODOS","title":"Formulario"}},{"name":"importe","in":"query","required":false,"schema":{"type":"string","default":"1","title":"Importe"}},{"name":"periodo_desde","in":"query","required":false,"schema":{"type":"string","default":"","title":"Periodo Desde"}},{"name":"periodo_hasta","in":"query","required":false,"schema":{"type":"string","default":"","title":"Periodo Hasta"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/padron/{ruc}/ssco":{"get":{"tags":["Contribuyente"],"summary":"Verificar si un RUC es Sujeto Sin Capacidad Operativa (SSCO)","description":"Verifica si el RUC esta calificado como Sujeto Sin Capacidad Operativa (SSCO) segun el padron SUNAT.\n\n**Impacto:** Las facturas emitidas por un SSCO **no generan credito fiscal del IGV** ni son gasto deducible para el Impuesto a la Renta. El efecto es retroactivo desde el 20/03/2022.\n\nRetorna la resolucion de atribucion, fecha en que quedo firme y fecha de publicacion.\n\nNo requiere credenciales SUNAT.","operationId":"get_ssco_contribuyente_padron__ruc__ssco_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/monitor/batch":{"post":{"tags":["Contribuyente"],"summary":"Monitorear estado de múltiples RUCs (portfolio)","description":"Consulta el estado tributario de hasta 50 RUCs en paralelo.\n\nRetorna estado (ACTIVO/BAJA), condición (HABIDO/NO HABIDO) y **alertas automáticas** para RUCs con situaciones críticas.\n\nIdeal para contadores que gestionan múltiples clientes. No requiere credenciales SUNAT.","operationId":"post_monitor_batch_contribuyente_monitor_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorBatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/contribuyente/{ruc}/cpe/recibidos/xml":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar XML de comprobante recibido","description":"Descarga el XML de un Comprobante de Pago Electrónico (CPE) recibido, directamente desde SUNAT.\n\n**`ruc`:** RUC del receptor (tu empresa).\n\n**`emisor`:** RUC del emisor (proveedor que emitió el comprobante).\n\n**`tipo`:** código de tipo de comprobante — `01` Factura, `03` Boleta, `07` Nota de Crédito, `08` Nota de Débito.\n\n**`serie`:** serie del comprobante (ej: `F001`, `B001`).\n\n**`num`:** número correlativo del comprobante (ej: `1234`).\n\nRetorna el archivo XML directamente para descarga.\n\n**Requiere:** credenciales SUNAT configuradas (`PUT /admin/clientes/{id}/credenciales`).","operationId":"get_cpe_xml_recibido_contribuyente__ruc__cpe_recibidos_xml_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"emisor","in":"query","required":true,"schema":{"type":"string","title":"Emisor"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"Archivo XML del comprobante","content":{"application/xml":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/cpe/emitidos/xml":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar XML de comprobante emitido","description":"Descarga el XML de un Comprobante de Pago Electrónico (CPE) emitido por tu empresa, directamente desde SUNAT.\n\n**`ruc`:** RUC del emisor (tu empresa).\n\n**`tipo`:** código de tipo de comprobante — `01` Factura, `03` Boleta, `07` Nota de Crédito, `08` Nota de Débito.\n\n**`serie`:** serie del comprobante (ej: `F001`, `B001`).\n\n**`num`:** número correlativo del comprobante (ej: `1234`).\n\nRetorna el archivo XML directamente para descarga.\n\n**Requiere:** credenciales SUNAT configuradas (`PUT /admin/clientes/{id}/credenciales`).","operationId":"get_cpe_xml_emitido_contribuyente__ruc__cpe_emitidos_xml_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"Archivo XML del comprobante","content":{"application/xml":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/cpe/recibidos/pdf":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar PDF de comprobante recibido","description":"Descarga el PDF de un Comprobante de Pago Electrónico (CPE) recibido por tu empresa, directamente desde SUNAT.\n\n**`ruc`:** RUC del receptor (tu empresa).\n\n**`emisor`:** RUC del emisor del comprobante.\n\n**`tipo`:** código de tipo — `01` Factura, `03` Boleta, `07` NC, `08` ND.\n\n**`serie`:** serie del comprobante (ej: `F001`).\n\n**`num`:** número correlativo (ej: `1234`).\n\nRetorna el archivo PDF directamente para descarga.","operationId":"get_cpe_pdf_recibido_contribuyente__ruc__cpe_recibidos_pdf_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"emisor","in":"query","required":true,"schema":{"type":"string","title":"Emisor"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"Archivo PDF del comprobante","content":{"application/pdf":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/cpe/emitidos/pdf":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar PDF de comprobante emitido","description":"Descarga el PDF de un Comprobante de Pago Electrónico (CPE) emitido por tu empresa, directamente desde SUNAT.\n\n**`ruc`:** RUC del emisor (tu empresa).\n\n**`tipo`:** código de tipo — `01` Factura, `03` Boleta, `07` NC, `08` ND.\n\n**`serie`:** serie del comprobante (ej: `F001`).\n\n**`num`:** número correlativo (ej: `1234`).\n\nRetorna el archivo PDF directamente para descarga.","operationId":"get_cpe_pdf_emitido_contribuyente__ruc__cpe_emitidos_pdf_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"Archivo PDF del comprobante","content":{"application/pdf":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/cpe/recibidos/cdr":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar CDR de comprobante recibido","description":"Descarga el CDR (Constancia de Recepción) de un CPE recibido por tu empresa, directamente desde SUNAT.\n\n**`ruc`:** RUC del receptor (tu empresa).\n\n**`emisor`:** RUC del emisor del comprobante.\n\n**`tipo`:** código de tipo — `01` Factura, `03` Boleta, `07` NC, `08` ND.\n\n**`serie`:** serie del comprobante (ej: `F001`).\n\n**`num`:** número correlativo (ej: `1234`).\n\nRetorna el archivo XML del CDR directamente para descarga.","operationId":"get_cpe_cdr_recibido_contribuyente__ruc__cpe_recibidos_cdr_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"emisor","in":"query","required":true,"schema":{"type":"string","title":"Emisor"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"CDR XML del comprobante","content":{"application/xml":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/cpe/emitidos/cdr":{"get":{"tags":["Contribuyente"],"summary":"CPE - Descargar CDR de comprobante emitido","description":"Descarga el CDR (Constancia de Recepción) de un CPE emitido por tu empresa, directamente desde SUNAT.\n\n**`ruc`:** RUC del emisor (tu empresa).\n\n**`tipo`:** código de tipo — `01` Factura, `03` Boleta, `07` NC, `08` ND.\n\n**`serie`:** serie del comprobante (ej: `F001`).\n\n**`num`:** número correlativo (ej: `1234`).\n\nRetorna el archivo XML del CDR directamente para descarga.","operationId":"get_cpe_cdr_emitido_contribuyente__ruc__cpe_emitidos_cdr_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"tipo","in":"query","required":true,"schema":{"type":"string","title":"Tipo"}},{"name":"serie","in":"query","required":true,"schema":{"type":"string","title":"Serie"}},{"name":"num","in":"query","required":true,"schema":{"type":"string","title":"Num"}}],"responses":{"200":{"description":"CDR XML del comprobante","content":{"application/xml":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/conformidad/listado":{"get":{"tags":["Contribuyente"],"summary":"Conformidad CPE - Listado de comprobantes recibidos","description":"Lista los comprobantes de compra (facturas/RHE) recibidos por tu empresa con su estado de conformidad, directamente desde la Plataforma de Confirmación de SUNAT.\n\n**`ruc`:** RUC del adquirente (tu empresa).\n\n**`fecha_inicio` / `fecha_fin`:** rango por Fecha de Puesta a Disposición en la Plataforma (ej: `2026-01-01`). Acepta formato `DD/MM/YYYY`.\n\n**`tipo`:** tipo de comprobante — `01` Factura (default), `02` RHE, `00` Todos.\n\n**`estado`:** `04` Conformes, `01` Pendientes, `02` Disconformes, `03` Subsanados, vacío para todos los estados.\n\nRetorna el listado completo incluyendo: RUC emisor, razón social, serie, número, fecha de emisión, estado, condición de conformidad, monto, moneda y fechas clave.\n\n**Requiere:** credenciales SUNAT configuradas.","operationId":"get_conformidad_listado_contribuyente__ruc__conformidad_listado_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":true,"schema":{"type":"string","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":true,"schema":{"type":"string","title":"Fecha Fin"}},{"name":"tipo","in":"query","required":false,"schema":{"type":"string","default":"01","title":"Tipo"}},{"name":"estado","in":"query","required":false,"schema":{"type":"string","default":"","title":"Estado"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/conformidad/comprobantes":{"get":{"tags":["Contribuyente"],"summary":"Conformidad CPE - Listar comprobantes emitidos","description":"Lista los comprobantes emitidos por el RUC en la Plataforma de Confirmación de SUNAT, con filtros por fecha, tipo y estado.\n\n**Estados:** `01` Pendiente, `02` Disconforme, `03` Subsanado, `04` Conforme. Dejar vacío para todos.\n\n**Tipos:** `00` Todos, `01` Factura, `02` RHE.\n\nLa conformidad aplica a facturas al crédito recibidas por el RUC adquiriente.","operationId":"get_conformidad_comprobantes_contribuyente__ruc__conformidad_comprobantes_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"fecha_inicio","in":"query","required":true,"schema":{"type":"string","title":"Fecha Inicio"}},{"name":"fecha_fin","in":"query","required":true,"schema":{"type":"string","title":"Fecha Fin"}},{"name":"tipo","in":"query","required":false,"schema":{"type":"string","default":"00","title":"Tipo"}},{"name":"estado","in":"query","required":false,"schema":{"type":"string","default":"","title":"Estado"}},{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Pagina"}},{"name":"por_pagina","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Por Pagina"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/conformidad":{"post":{"tags":["Contribuyente"],"summary":"Conformidad CPE - Dar conformidad a comprobantes","description":"Da conformidad a uno o más comprobantes recibidos (facturas al crédito) en la Plataforma de Confirmación de SUNAT.\n\n**Flujo:** SUNAT requiere que el adquiriente (comprador) confirme las facturas recibidas para que el proveedor pueda usarlas en factoring.\n\n**Body:** lista de comprobantes a confirmar:\n```json\n[{\n  \"emisor\": \"20100127670\",\n  \"tipo\": \"01\",\n  \"serie\": \"F001\",\n  \"num\": \"1234\"\n}]\n```\n\nSolo aplica a comprobantes en estado **Pendiente** (01) o **Subsanado** (03).","operationId":"post_conformidad_contribuyente__ruc__conformidad_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{},"title":"Body"},"example":[{"emisor":"20517448371","tipo":"01","serie":"F001","num":"8282"}]}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/pdt/{formulario}":{"get":{"tags":["Contribuyente"],"summary":"PDT - Consulta de Declaraciones y Pagos","description":"Consulta las declaraciones presentadas en un formulario PDT para un periodo determinado, directamente desde la Plataforma Unica de SUNAT.\n\n**`ruc`:** RUC del contribuyente.\n\n**`formulario`:** codigo del formulario PDT — `0621` PDT IGV-RENTA MENSUAL.\n\n**`mes`:** mes de la declaracion (1-12).\n\n**`anio`:** año de la declaracion (ej: 2026).\n\nRetorna JSON con la informacion de la declaracion incluyendo fecha de presentacion, numero de orden, medio de presentacion y todas las **casillas** del formulario.\n\n**Requiere:** credenciales SUNAT configuradas (`PUT /admin/clientes/{id}/credenciales`).","operationId":"get_pdt_declaracion_contribuyente__ruc__pdt__formulario__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"formulario","in":"path","required":true,"schema":{"type":"string","title":"Formulario"}},{"name":"mes","in":"query","required":true,"schema":{"type":"integer","title":"Mes"}},{"name":"anio","in":"query","required":true,"schema":{"type":"integer","title":"Anio"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/dam":{"get":{"tags":["Contribuyente"],"summary":"DAM - Consultar Declaracion Aduanera de Mercancias","description":"Consulta una Declaracion Aduanera de Mercancias (DAM) en el portal publico de SUNAT Aduanas.\n\n**`aduana`:** codigo de aduana (ej: `118` para Maritima del Callao, `235` para Aerea del Callao).\n\n**`anio`:** anio de la declaracion (ej: `2024`).\n\n**`numero`:** numero correlativo de la declaracion.\n\n**`regimen`:** codigo de regimen aduanero (default `10` = Importacion Definitiva). Otros: `40`/`41` Exportacion, `21` Admision Temporal, `18` Importacion Simplificada, etc.\n\nRetorna datos completos: importador, canal, valores FOB/CIF/flete/seguro, tributos y agente de aduanas.\n\n**No requiere credenciales SUNAT** — informacion publica.","operationId":"get_dam_contribuyente_dam_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"aduana","in":"query","required":true,"schema":{"type":"string","title":"Aduana"}},{"name":"anio","in":"query","required":true,"schema":{"type":"string","title":"Anio"}},{"name":"numero","in":"query","required":true,"schema":{"type":"string","title":"Numero"}},{"name":"regimen","in":"query","required":false,"schema":{"type":"string","default":"10","title":"Regimen"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/buzon/notificaciones":{"get":{"tags":["Contribuyente"],"summary":"Buzon SOL - Listar notificaciones y mensajes","description":"Lista las notificaciones o mensajes del Buzon Electronico SOL del RUC configurado.\n\n**`tipo_msj`:** `2` Notificaciones SUNAT (default), `1` Mensajes.\n\n**`page`:** numero de pagina (default `1`).\n\n**`cod_carpeta`:** `00` Bandeja de entrada (default), o codigo de carpeta personalizada.\n\n**`des_asunto`:** filtro opcional por texto en el asunto.\n\n**`tipo_orden`:** `NADA` sin orden especifico (default).\n\nRetorna: `total`, `page`, `notificaciones` con campos `codMensaje`, `desAsunto`, `fecEnvio`, `fecPublica`, `indEstado`, `cantidadArchAdj`.\n\n**Requiere:** credenciales SOL configuradas (`PUT /mi-cuenta/credenciales-sol`).","operationId":"get_buzon_notificaciones_contribuyente__ruc__buzon_notificaciones_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"tipo_msj","in":"query","required":false,"schema":{"type":"integer","default":2,"title":"Tipo Msj"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}},{"name":"cod_carpeta","in":"query","required":false,"schema":{"type":"string","default":"00","title":"Cod Carpeta"}},{"name":"des_asunto","in":"query","required":false,"schema":{"type":"string","default":"","title":"Des Asunto"}},{"name":"tipo_orden","in":"query","required":false,"schema":{"type":"string","default":"NADA","title":"Tipo Orden"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/buzon/notificaciones/{cod_mensaje}":{"get":{"tags":["Contribuyente"],"summary":"Buzon SOL - Obtener detalle de una notificacion","description":"Obtiene el contenido completo y la lista de adjuntos de una notificacion o mensaje.\n\n**`cod_mensaje`:** codigo de la notificacion (campo `codMensaje` del listado).\n\n**`tipo_msj`:** `2` Notificacion (default), `1` Mensaje.\n\nRetorna: `mensaje` (HTML/texto del contenido), `adjuntos` con `codArchivo`, `nomArchivo`, `cntTamarch`, y `url_html` del documento.\n\n**Requiere:** credenciales SOL configuradas.","operationId":"get_buzon_detalle_contribuyente__ruc__buzon_notificaciones__cod_mensaje__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"cod_mensaje","in":"path","required":true,"schema":{"type":"integer","title":"Cod Mensaje"}},{"name":"tipo_msj","in":"query","required":false,"schema":{"type":"integer","default":2,"title":"Tipo Msj"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/buzon/notificaciones/{cod_mensaje}/contenido":{"get":{"tags":["Contribuyente"],"summary":"Buzon SOL - Obtener cuerpo HTML de una notificacion","description":"Obtiene el contenido completo (cuerpo HTML) de una notificacion o mensaje del Buzon SOL.\n\n**`cod_mensaje`:** codigo de la notificacion (campo `codMensaje` del listado).\n\n**`tipo_msj`:** `2` Notificacion (default), `1` Mensaje.\n\nRetorna el campo `contenido` con el HTML del cuerpo del documento tal como lo muestra el portal SUNAT, incluyendo el texto del requerimiento, fechas, articulos de ley citados, etc.\n\n**Requiere:** credenciales SOL configuradas.","operationId":"get_buzon_contenido_contribuyente__ruc__buzon_notificaciones__cod_mensaje__contenido_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"cod_mensaje","in":"path","required":true,"schema":{"type":"integer","title":"Cod Mensaje"}},{"name":"tipo_msj","in":"query","required":false,"schema":{"type":"integer","default":2,"title":"Tipo Msj"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/contribuyente/{ruc}/buzon/notificaciones/{cod_mensaje}/adjunto/{cod_archivo}":{"get":{"tags":["Contribuyente"],"summary":"Buzon SOL - Descargar adjunto (PDF) de una notificacion","description":"Descarga el archivo adjunto (tipicamente PDF) de una notificacion del Buzon SOL.\n\n**`cod_mensaje`:** codigo de la notificacion.\n\n**`cod_archivo`:** codigo del archivo adjunto (campo `codArchivo` del detalle).\n\nRetorna el archivo PDF directamente para descarga.\n\n**Requiere:** credenciales SOL configuradas.","operationId":"get_buzon_adjunto_contribuyente__ruc__buzon_notificaciones__cod_mensaje__adjunto__cod_archivo__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","title":"Ruc"}},{"name":"cod_mensaje","in":"path","required":true,"schema":{"type":"integer","title":"Cod Mensaje"}},{"name":"cod_archivo","in":"path","required":true,"schema":{"type":"string","title":"Cod Archivo"}}],"responses":{"200":{"description":"Archivo PDF adjunto","content":{"application/pdf":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/aduanero/documentossustentatorios":{"post":{"tags":["Control Aduanero"],"summary":"Transmisión de Documentos Digitalizados (PDF en Base64)","description":"Transmite documentos sustentatorios digitalizados (PDF en Base64) a SUNAT Aduanas. Permite adjuntar documentos de soporte a una Declaración de Importación al Consumo (DAM).\n\n**Requiere:** credenciales SOL configuradas (`PUT /admin/clientes/{id}/credenciales-sol`)\n\nEl body debe seguir la estructura definida por SUNAT para transmisión de documentos aduaneros.","operationId":"post_documentos_aduanero_documentossustentatorios_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/uso":{"get":{"tags":["Mi Cuenta"],"summary":"Ver mi historial de uso","operationId":"mi_uso_mi_cuenta_uso_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/perfil":{"get":{"tags":["Mi Cuenta"],"summary":"Ver mi perfil","operationId":"mi_perfil_mi_cuenta_perfil_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/ruc":{"put":{"tags":["Mi Cuenta"],"summary":"Configurar mi RUC","description":"Guarda el RUC del contribuyente asociado a esta API Key.\n\n**Necesario para:** consulta de detracciones SPOT y cualquier endpoint que requiera identificar al contribuyente por RUC.\n\n**Formato:** 11 dígitos numéricos (ej: `20100190797`).\n\n**Requiere:** tu API Key en el header `X-API-Key`.","operationId":"actualizar_mi_ruc_mi_cuenta_ruc_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RucCliente"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/credenciales-validar":{"put":{"tags":["Mi Cuenta"],"summary":"Configurar mis credenciales SUNAT","operationId":"actualizar_mis_credenciales_mi_cuenta_credenciales_validar_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredencialesSunatCliente"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/credenciales-sol":{"put":{"tags":["Mi Cuenta"],"summary":"Configurar usuario y clave SOL","description":"Configura tu usuario y clave SOL.\n\n**Necesario para:** detracciones SPOT, GRE, SSPP, Documentos Aduaneros.\n\n**Formato usuario SOL:** solo el usuario, **sin RUC** — ejemplo: `BHIVPCGY`.\n\nEl RUC se configura por separado en `PUT /mi-cuenta/ruc`.\n\n**Requiere:** tu API Key en el header `X-API-Key`.","operationId":"actualizar_mis_credenciales_sol_mi_cuenta_credenciales_sol_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredencialesSOLCliente"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/credenciales-sire":{"put":{"tags":["Mi Cuenta"],"summary":"Configurar credenciales GRE / SSPP / Aduanas","description":"Configura el `client_id` y `client_secret` para servicios con scope `api-cpe.sunat.gob.pe`.\n\n**Necesario para:** GRE, SSPP (Receptor XML), Documentos Aduaneros.\n\n**Cómo obtenerlas:** Portal SUNAT → Operaciones en Línea → Configuración de aplicaciones → Nueva aplicación → scope `https://api-cpe.sunat.gob.pe`.\n\n**Requiere:** tu API Key en el header `X-API-Key`.","operationId":"actualizar_mis_credenciales_gre_mi_cuenta_credenciales_sire_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredencialesGRECliente"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/clientes":{"get":{"tags":["Mi Cuenta"],"summary":"Listar mis clientes","description":"Devuelve todos los clientes creados bajo tu cuenta, con su API Key y RUC.\n\n**Requiere:** tu API Key maestra en el header `X-API-Key`.","operationId":"listar_mis_clientes_mi_cuenta_clientes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]},"post":{"tags":["Mi Cuenta"],"summary":"Agregar un cliente","description":"Crea un nuevo cliente bajo tu cuenta y devuelve su API Key exclusiva.\n\nCada cliente tiene su propio espacio aislado: solo puede acceder a sus propios datos.\n\n**`ruc`:** RUC de 11 dígitos del contribuyente.\n\n**`email`:** opcional. Si no se envía, se asigna uno interno automáticamente.\n\n**Requiere:** tu API Key maestra en el header `X-API-Key`.","operationId":"crear_mi_cliente_mi_cuenta_clientes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NuevoSubcliente"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/mi-cuenta/clientes/{cliente_id}":{"delete":{"tags":["Mi Cuenta"],"summary":"Eliminar un cliente","description":"Desactiva un cliente de tu cuenta. La API Key del cliente deja de funcionar.\n\n**Requiere:** tu API Key maestra en el header `X-API-Key`.","operationId":"eliminar_mi_cliente_mi_cuenta_clientes__cliente_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"cliente_id","in":"path","required":true,"schema":{"type":"string","title":"Cliente Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/igv/calcular":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calculadora de IGV","description":"Calcula el IGV (18%) de un monto dado.\n\n- Si `incluye_igv: false` → el monto es la **base imponible**, calcula IGV y total.\n- Si `incluye_igv: true` → el monto ya **incluye IGV**, descompone base e IGV.\n\nNo requiere credenciales SUNAT.","operationId":"post_igv_calcular_utils_igv_calcular_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IgvRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/igv/calcular/lote":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calculadora de IGV - Múltiples montos","description":"Calcula el IGV para una lista de montos en una sola petición.\n\nÚtil para procesar múltiples líneas de una factura.\n\nNo requiere credenciales SUNAT.","operationId":"post_igv_calcular_lote_utils_igv_calcular_lote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IgvLoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/codigos/comprobantes":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla de tipos de comprobante de pago","description":"Retorna todos los tipos de comprobante de pago reconocidos por SUNAT (Tabla 10 del PDT).\n\nIncluye código, nombre, si es electrónico y si aplica detracción.\n\nNo requiere credenciales SUNAT.","operationId":"get_codigos_comprobantes_utils_codigos_comprobantes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/codigos/comprobantes/{codigo}":{"get":{"tags":["Utilidades Tributarias"],"summary":"Consultar tipo de comprobante por código","description":"Retorna el nombre y atributos de un tipo de comprobante. Ej: `01` → Factura.","operationId":"get_codigo_comprobante_utils_codigos_comprobantes__codigo__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","title":"Codigo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/codigos/monedas":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla de monedas (Tabla 4 SUNAT)","description":"Retorna los códigos ISO de monedas aceptados por SUNAT con su símbolo.","operationId":"get_codigos_monedas_utils_codigos_monedas_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/codigos/documentos-identidad":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla de tipos de documento de identidad","description":"Retorna los códigos de documento de identidad aceptados por SUNAT (DNI, RUC, pasaporte, etc.).","operationId":"get_documentos_identidad_utils_codigos_documentos_identidad_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/codigos/regimenes":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla de regímenes tributarios","description":"Retorna los regímenes tributarios vigentes en Perú: RUS, RER, Régimen MYPE, Régimen General.","operationId":"get_regimenes_utils_codigos_regimenes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/codigos/serie/{serie}":{"get":{"tags":["Utilidades Tributarias"],"summary":"Identificar tipo de documento por serie","description":"Identifica el tipo de comprobante según el prefijo de la serie.\n\nEjemplos: `F001` → Factura física | `E001` → Factura electrónica | `B001` → Boleta | `T001` → Guía de Remisión\n\nNo requiere credenciales SUNAT.","operationId":"get_identificar_serie_utils_codigos_serie__serie__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"serie","in":"path","required":true,"schema":{"type":"string","title":"Serie"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/detracciones":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla completa de detracciones SUNAT (SPOT)","description":"Retorna todos los bienes y servicios sujetos al Sistema de Pago de Obligaciones Tributarias (SPOT) con su tasa de detracción.\n\nIncluye Anexo 1 (bienes) y Anexo 2 (servicios).\n\nNo requiere credenciales SUNAT.","operationId":"get_detracciones_utils_detracciones_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/detracciones/{codigo}":{"get":{"tags":["Utilidades Tributarias"],"summary":"Consultar tasa de detracción por código","description":"Retorna la tasa de detracción para un código específico.\n\nEjemplos: `024` → Contratos de Construcción (4%) | `037` → Demás Servicios IGV (12%)","operationId":"get_detraccion_utils_detracciones__codigo__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","title":"Codigo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/detracciones/calcular":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular monto de detracción","description":"Calcula el monto de detracción a depositar en el Banco de la Nación según el código SUNAT y el importe de la factura.\n\n**Regla:** solo aplica detracción si el monto supera S/ 700.\n\nNo requiere credenciales SUNAT.","operationId":"post_detraccion_calcular_utils_detracciones_calcular_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeduccionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/tim/intereses":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular intereses moratorios TIM","description":"Calcula los intereses por mora tributaria usando la Tasa de Interés Moratorio (TIM) oficial de SUNAT (1.2% mensual vigente desde noviembre 2010).\n\n**Fórmula:** Monto × (TIM_diaria × días de mora)\n\nSi se omite `fecha_pago`, se usa la fecha de hoy.\n\nNo requiere credenciales SUNAT.","operationId":"post_tim_intereses_utils_tim_intereses_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/tim/multa/art178":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular multa Art. 178-1 (tributo omitido / datos falsos)","description":"Calcula la multa por declarar datos falsos o tributo omitido (Art. 178 numeral 1).\n\n**Multa base:** 50% del tributo omitido (mínimo 5% UIT).\n\n**`subsanacion`** — momento de corrección (afecta el % de rebaja):\n- `voluntaria_con_pago` — antes de notificación SUNAT, pagando el tributo (rebaja 95%)\n- `voluntaria_sin_pago` — antes de notificación, sin pagar (rebaja 95%)\n- `inducida_antes_valor` — después de notificación, dentro del plazo (rebaja 70%)\n- `inducida_con_pago` — después de notificación, con pago (rebaja 60%)\n- `inducida_despues_valor` — fuera del plazo (rebaja 50%)\n- `sin_subsanacion` — sin corrección (sin rebaja)\n\nNo requiere credenciales SUNAT.","operationId":"post_multa_178_utils_tim_multa_art178_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Multa178Request"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/tim/multa/art176":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular multa Art. 176-1 (declaración fuera de plazo)","description":"Calcula la multa por no presentar la declaración dentro del plazo (Art. 176 numeral 1).\n\nLa multa varía según el régimen tributario:\n- `general` / `mype` → 1 UIT\n- `rer` → 50% UIT\n- `rus` → 0.6% UIT\n\n**`subsanacion`:** `voluntaria` (rebaja 90%) o `inducida` (rebaja 60%).\n\nNo requiere credenciales SUNAT.","operationId":"post_multa_176_utils_tim_multa_art176_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Multa176Request"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/tim/deuda-total":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular deuda tributaria total (tributo + intereses + multa)","description":"Calcula la deuda tributaria completa: tributo original + intereses TIM + multa opcional.\n\nÚtil para saber exactamente cuánto pagar antes de ir al banco.\n\nSi `incluir_multa_178: true`, agrega la multa por tributo omitido con gradualidad de subsanación voluntaria con pago (rebaja 95%).\n\nNo requiere credenciales SUNAT.","operationId":"post_deuda_total_utils_tim_deuda_total_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeudaTotalRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/renta4ta/calcular":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular retención de Renta 4ta Categoría","description":"Calcula si corresponde retener el 8% de Renta de 4ta Categoría al pagar honorarios a un trabajador independiente (recibo por honorarios).\n\n**Regla:** retener solo si el pago individual o el acumulado del mes supera S/ 1,500.\n\nSi el trabajador tiene **certificado de suspensión** vigente, no se retiene.\n\nNo requiere credenciales SUNAT.","operationId":"post_renta4ta_utils_renta4ta_calcular_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Renta4taRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/renta4ta/suspension":{"post":{"tags":["Utilidades Tributarias"],"summary":"Verificar si un independiente puede solicitar suspensión de retenciones","description":"Determina si un trabajador independiente puede solicitar el **certificado de suspensión de retenciones** en SUNAT.\n\n**Condición:** sus ingresos anuales proyectados no deben superar 7 UIT (equivalente a S/ 38,500 en 2026 con UIT = S/ 5,500).\n\nNo requiere credenciales SUNAT.","operationId":"post_renta4ta_suspension_utils_renta4ta_suspension_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Renta4taExoneracionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/utils/infracciones":{"get":{"tags":["Utilidades Tributarias"],"summary":"Tabla de infracciones y sanciones tributarias","description":"Retorna la tabla de infracciones del Código Tributario Peruano (Art. 173 al 178) con sus sanciones y porcentajes de gradualidad.\n\n**Parámetro opcional `categoria`:** filtra por categoría (Inscripción y actualización, Comprobantes de pago, Declaraciones, etc.)\n\nNo requiere credenciales SUNAT.","operationId":"get_infracciones_utils_infracciones_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"categoria","in":"query","required":false,"schema":{"type":"string","title":"Categoria"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/infracciones/{codigo}":{"get":{"tags":["Utilidades Tributarias"],"summary":"Consultar una infracción específica","description":"Retorna los detalles de una infracción por código.\n\n**Ejemplos de código:** `176-1` (declaración tardía), `178-1` (tributo omitido), `174-1` (no emitir comprobante)\n\nNo requiere credenciales SUNAT.","operationId":"get_infraccion_utils_infracciones__codigo__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","title":"Codigo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/utils/infracciones/calcular-sancion":{"post":{"tags":["Utilidades Tributarias"],"summary":"Calcular monto de sanción con gradualidad","description":"Calcula el monto exacto de una sanción tributaria aplicando el régimen de gradualidad.\n\nLa gradualidad reduce la multa si el contribuyente se subsana voluntariamente (antes de notificación SUNAT) o de forma inducida (después de notificación).\n\n**`regimen`:** `general`, `mype`, `rer`, `rus`\n\n**`tributo_base`:** requerido solo para infracciones Art. 178 (% del tributo omitido).\n\nNo requiere credenciales SUNAT.","operationId":"post_calcular_sancion_utils_infracciones_calcular_sancion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SancionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/acceso/recuperar":{"post":{"tags":["Acceso"],"summary":"Recuperar Api Key","operationId":"recuperar_api_key_acceso_recuperar_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/acceso/gratis":{"post":{"tags":["Acceso"],"summary":"Registrar Gratis","operationId":"registrar_gratis_acceso_gratis_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/acceso/pagar":{"post":{"tags":["Acceso"],"summary":"Procesar Pago","operationId":"procesar_pago_acceso_pagar_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/acceso/cancelar":{"post":{"tags":["Acceso"],"summary":"Cancelar Suscripcion","operationId":"cancelar_suscripcion_acceso_cancelar_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Data"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"tags":["Health"],"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Estado de todos los servicios","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/guia":{"get":{"tags":["Health"],"summary":"Guía rápida de uso de la API","operationId":"guia_guia_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"CredencialesGRECliente":{"properties":{"sol_client_id":{"type":"string","title":"Sol Client Id"},"sol_client_secret":{"type":"string","title":"Sol Client Secret"}},"type":"object","required":["sol_client_id","sol_client_secret"],"title":"CredencialesGRECliente"},"CredencialesSOLCliente":{"properties":{"sol_usuario":{"type":"string","title":"Sol Usuario"},"sol_clave":{"type":"string","title":"Sol Clave"}},"type":"object","required":["sol_usuario","sol_clave"],"title":"CredencialesSOLCliente"},"CredencialesSunatCliente":{"properties":{"sunat_client_id":{"type":"string","title":"Sunat Client Id"},"sunat_client_secret":{"type":"string","title":"Sunat Client Secret"},"ruc":{"type":"string","title":"Ruc"}},"type":"object","required":["sunat_client_id","sunat_client_secret","ruc"],"title":"CredencialesSunatCliente"},"DeduccionRequest":{"properties":{"codigo":{"type":"string","title":"Codigo"},"monto_factura":{"type":"number","title":"Monto Factura"}},"type":"object","required":["codigo","monto_factura"],"title":"DeduccionRequest","example":{"codigo":"024","monto_factura":10000.0}},"DeudaTotalRequest":{"properties":{"tributo":{"type":"number","title":"Tributo"},"fecha_vencimiento":{"type":"string","title":"Fecha Vencimiento"},"fecha_pago":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fecha Pago"},"incluir_multa_178":{"type":"boolean","title":"Incluir Multa 178","default":false},"regimen":{"type":"string","title":"Regimen","default":"general"},"anio":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Anio"}},"type":"object","required":["tributo","fecha_vencimiento"],"title":"DeudaTotalRequest","example":{"anio":2026,"fecha_pago":"2025-04-13","fecha_vencimiento":"2025-01-20","incluir_multa_178":true,"regimen":"general","tributo":5000.0}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IgvLoteItem":{"properties":{"monto":{"type":"number","title":"Monto"},"incluye_igv":{"type":"boolean","title":"Incluye Igv","default":false},"descripcion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descripcion"}},"type":"object","required":["monto"],"title":"IgvLoteItem"},"IgvLoteRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IgvLoteItem"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"IgvLoteRequest","example":{"items":[{"descripcion":"Servicio A","incluye_igv":false,"monto":1000.0},{"descripcion":"Producto B","incluye_igv":true,"monto":590.0}]}},"IgvRequest":{"properties":{"monto":{"type":"number","title":"Monto"},"incluye_igv":{"type":"boolean","title":"Incluye Igv","default":false}},"type":"object","required":["monto"],"title":"IgvRequest","example":{"incluye_igv":false,"monto":1000.0}},"MonitorBatchRequest":{"properties":{"rucs":{"items":{"type":"string"},"type":"array","title":"Rucs"}},"type":"object","required":["rucs"],"title":"MonitorBatchRequest","example":{"rucs":["20603408161","20478963719","10456789012"]}},"Multa176Request":{"properties":{"regimen":{"type":"string","title":"Regimen"},"anio":{"type":"integer","title":"Anio"},"subsanacion":{"type":"string","title":"Subsanacion","default":"voluntaria"}},"type":"object","required":["regimen","anio"],"title":"Multa176Request","example":{"anio":2026,"regimen":"general","subsanacion":"voluntaria"}},"Multa178Request":{"properties":{"tributo_omitido":{"type":"number","title":"Tributo Omitido"},"anio":{"type":"integer","title":"Anio"},"subsanacion":{"type":"string","title":"Subsanacion","default":"voluntaria_con_pago"}},"type":"object","required":["tributo_omitido","anio"],"title":"Multa178Request","example":{"anio":2026,"subsanacion":"voluntaria_con_pago","tributo_omitido":3000.0}},"NuevoSubcliente":{"properties":{"nombre":{"type":"string","title":"Nombre"},"ruc":{"type":"string","title":"Ruc"},"email":{"type":"string","title":"Email"}},"type":"object","required":["nombre","ruc"],"title":"NuevoSubcliente"},"Renta4taExoneracionRequest":{"properties":{"ingresos_anuales_proyectados":{"type":"number","title":"Ingresos Anuales Proyectados"},"anio":{"type":"integer","title":"Anio","default":2026}},"type":"object","required":["ingresos_anuales_proyectados"],"title":"Renta4taExoneracionRequest","example":{"anio":2026,"ingresos_anuales_proyectados":30000.0}},"Renta4taRequest":{"properties":{"monto_pago":{"type":"number","title":"Monto Pago"},"acumulado_mes":{"type":"number","title":"Acumulado Mes","default":0.0},"anio":{"type":"integer","title":"Anio","default":2026},"tiene_suspension":{"type":"boolean","title":"Tiene Suspension","default":false}},"type":"object","required":["monto_pago"],"title":"Renta4taRequest","example":{"acumulado_mes":500.0,"anio":2026,"monto_pago":3000.0,"tiene_suspension":false}},"RucCliente":{"properties":{"ruc":{"type":"string","title":"Ruc"}},"type":"object","required":["ruc"],"title":"RucCliente"},"RucLoteRequest":{"properties":{"rucs":{"items":{"type":"string"},"type":"array","title":"Rucs"}},"type":"object","required":["rucs"],"title":"RucLoteRequest","example":{"rucs":["20603408161","20478963719","10456789012"]}},"SancionRequest":{"properties":{"codigo":{"type":"string","title":"Codigo"},"regimen":{"type":"string","title":"Regimen"},"anio":{"type":"integer","title":"Anio"},"tributo_base":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tributo Base"}},"type":"object","required":["codigo","regimen","anio"],"title":"SancionRequest","example":{"anio":2026,"codigo":"178-1","regimen":"general","tributo_base":5000.0}},"SsppEnviarRequest":{"properties":{"ruc":{"type":"string","title":"Ruc"},"nombreArchivo":{"type":"string","title":"Nombrearchivo"},"archivo":{"type":"string","title":"Archivo"}},"type":"object","required":["ruc","nombreArchivo","archivo"],"title":"SsppEnviarRequest","example":{"archivo":"UEsDBAoAAAAAAGR...","nombreArchivo":"20603408161-01-F001-1234.zip","ruc":"20603408161"}},"TimRequest":{"properties":{"monto":{"type":"number","title":"Monto"},"fecha_vencimiento":{"type":"string","title":"Fecha Vencimiento"},"fecha_pago":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fecha Pago"}},"type":"object","required":["monto","fecha_vencimiento"],"title":"TimRequest","example":{"fecha_pago":"2025-04-13","fecha_vencimiento":"2025-01-20","monto":5000.0}},"ValidarComprobanteRequest":{"properties":{"numRuc":{"type":"string","title":"Numruc"},"codComp":{"type":"string","title":"Codcomp"},"numeroSerie":{"type":"string","title":"Numeroserie"},"numero":{"type":"string","title":"Numero"},"fechaEmision":{"type":"string","title":"Fechaemision"},"monto":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto"}},"type":"object","required":["numRuc","codComp","numeroSerie","numero","fechaEmision"],"title":"ValidarComprobanteRequest","example":{"codComp":"01","fechaEmision":"2024-01-15","monto":1180.0,"numRuc":"20603408161","numero":"1234","numeroSerie":"F001"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Contribuyente","description":"Consulta de RUC, validación de comprobantes, tipo de cambio, SIRE (Registro de Ventas), GRE (Guía de Remisión Electrónica) y SSPP (Receptor XML)."},{"name":"Control Aduanero","description":"Transmisión de documentos sustentatorios digitalizados (PDF en Base64) y otros servicios de Control Aduanero SUNAT."},{"name":"Mi Cuenta","description":"Endpoints para que el cliente consulte su propio perfil y uso."},{"name":"Administración","description":"Gestión de clientes, credenciales y estadísticas. Requiere `X-Admin-Secret`."},{"name":"Health","description":"Estado del servicio."}]}