{"openapi":"3.1.0","info":{"title":"api-cpe","description":"API de Pytronia para los servicios de SUNAT sobre comprobantes electrónicos y del MTC para la guía de remisión.","version":"2.3.0"},"paths":{"/api/v1/cpe/consultar":{"post":{"tags":["Comprobantes"],"summary":"Datos de un comprobante","description":"Datos de un comprobante tal como los tiene SUNAT (fecha, moneda, total y razones sociales), sin\ndescargar archivos.","operationId":"getCpeDetails","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPERequest"}}},"required":true},"responses":{"200":{"description":"Los datos del comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPEConsulta"}}}},"401":{"description":"Falta la API key, o SUNAT no aceptó el acceso (usuario o clave SOL, permiso del usuario o credenciales de la aplicación): el motivo va en detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"403":{"description":"API key no autorizada: no existe o está desactivada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"404":{"description":"El comprobante no está en SUNAT o no tiene ese archivo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"429":{"description":"Se superó el límite de peticiones por minuto de la API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"500":{"description":"SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"502":{"description":"SUNAT error: SUNAT respondió algo ilegible; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"503":{"description":"SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"504":{"description":"SUNAT error: SUNAT no respondió a tiempo; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/cpe/pdf":{"post":{"tags":["Comprobantes"],"summary":"PDF de un comprobante","description":"La representación impresa del comprobante, en base64.","operationId":"downloadCpePdf","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPERequest"}}},"required":true},"responses":{"200":{"description":"El archivo del comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPEArchivo"}}}},"401":{"description":"Falta la API key, o SUNAT no aceptó el acceso (usuario o clave SOL, permiso del usuario o credenciales de la aplicación): el motivo va en detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"403":{"description":"API key no autorizada: no existe o está desactivada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"404":{"description":"El comprobante no está en SUNAT o no tiene ese archivo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"429":{"description":"Se superó el límite de peticiones por minuto de la API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"500":{"description":"SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"502":{"description":"SUNAT error: SUNAT respondió algo ilegible; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"503":{"description":"SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"504":{"description":"SUNAT error: SUNAT no respondió a tiempo; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/cpe/xml":{"post":{"tags":["Comprobantes"],"summary":"XML de un comprobante","description":"El XML firmado del comprobante, en base64.","operationId":"downloadCpeXml","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPERequest"}}},"required":true},"responses":{"200":{"description":"El archivo del comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPEArchivo"}}}},"401":{"description":"Falta la API key, o SUNAT no aceptó el acceso (usuario o clave SOL, permiso del usuario o credenciales de la aplicación): el motivo va en detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"403":{"description":"API key no autorizada: no existe o está desactivada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"404":{"description":"El comprobante no está en SUNAT o no tiene ese archivo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"429":{"description":"Se superó el límite de peticiones por minuto de la API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"500":{"description":"SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"502":{"description":"SUNAT error: SUNAT respondió algo ilegible; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"503":{"description":"SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"504":{"description":"SUNAT error: SUNAT no respondió a tiempo; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/cpe/cdr":{"post":{"tags":["Comprobantes"],"summary":"CDR de un comprobante","description":"La constancia de recepción de SUNAT (CDR), en base64.","operationId":"downloadCpeCdr","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPERequest"}}},"required":true},"responses":{"200":{"description":"El archivo del comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CPEArchivo"}}}},"401":{"description":"Falta la API key, o SUNAT no aceptó el acceso (usuario o clave SOL, permiso del usuario o credenciales de la aplicación): el motivo va en detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"403":{"description":"API key no autorizada: no existe o está desactivada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"404":{"description":"El comprobante no está en SUNAT o no tiene ese archivo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"429":{"description":"Se superó el límite de peticiones por minuto de la API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"500":{"description":"SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"502":{"description":"SUNAT error: SUNAT respondió algo ilegible; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"503":{"description":"SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"504":{"description":"SUNAT error: SUNAT no respondió a tiempo; reintentar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/vehicles/{plate}":{"get":{"tags":["Vehículos"],"summary":"Vehículo por placa","description":"Busca la placa en el Registro Nacional de Transporte de Carga del MTC y devuelve la TUC del\nvehículo y el Registro MTC del transportista, lo que pide la guía de remisión. La placa puede ir\ncon o sin guion. Lo ya consultado se sirve sin volver al MTC.","operationId":"getVehicle","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"plate","in":"path","required":true,"schema":{"type":"string","description":"Placa del vehículo, con o sin guion (ABC123 o ABC-123).","title":"Plate"},"description":"Placa del vehículo, con o sin guion (ABC123 o ABC-123)."}],"responses":{"200":{"description":"El vehículo. Si la placa no está en el registro de carga, registered es false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleOut"}}}},"401":{"description":"UNAUTHORIZED: Falta la API key, no existe o su cliente está desactivado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"INVALID_REQUEST: La petición no es válida: un dato con formato incorrecto (una placa que no tiene 6 letras o números, un lote vacío o demasiado grande) o un método que la ruta no admite. Dentro del estado de un comprobante: SUNAT no aceptó los datos de ese comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"INVALID_REQUEST: La petición no es válida: un dato con formato incorrecto (una placa que no tiene 6 letras o números, un lote vacío o demasiado grande) o un método que la ruta no admite. Dentro del estado de un comprobante: SUNAT no aceptó los datos de ese comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"RATE_LIMITED: Se superó el límite de peticiones por minuto de la API key, el tope de consultas por hora al MTC o el de consultas por minuto a SUNAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_ERROR: Fallo inesperado del propio servicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"MTC_FORMAT_CHANGED: La consulta del MTC cambió o pidió verificación humana; queda suspendida y Pytronia recibe el aviso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"SERVICE_DISABLED: El servicio pedido está desactivado en este servidor. MTC_UNAVAILABLE: El MTC no responde, está atendiendo otra consulta o está en pausa tras un fallo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/documents/status":{"post":{"tags":["Estado de comprobantes"],"summary":"Estado de comprobantes en SUNAT","description":"Pregunta a SUNAT, con la consulta de validez, si tiene cada comprobante del lote: facturas, boletas y\nnotas de la empresa, también las declaradas por resumen diario. Sirve para decidir, ante un resumen en\nduda, si un comprobante está declarado o hay que volver a enviarlo.","operationId":"checkDocumentStatus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatusRequest"}}},"required":true},"responses":{"200":{"description":"Un resultado por comprobante. Un fallo de SUNAT en uno lo deja en unknown sin tumbar el lote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatusResponse"}}}},"401":{"description":"UNAUTHORIZED: Falta la API key, no existe o su cliente está desactivado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"SUNAT_CREDENTIALS_REJECTED: SUNAT rechazó las credenciales de la aplicación: no existen, se revocaron o la aplicación no está registrada para el servicio pedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"INVALID_REQUEST: La petición no es válida: un dato con formato incorrecto (una placa que no tiene 6 letras o números, un lote vacío o demasiado grande) o un método que la ruta no admite. Dentro del estado de un comprobante: SUNAT no aceptó los datos de ese comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"INVALID_REQUEST: La petición no es válida: un dato con formato incorrecto (una placa que no tiene 6 letras o números, un lote vacío o demasiado grande) o un método que la ruta no admite. Dentro del estado de un comprobante: SUNAT no aceptó los datos de ese comprobante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"RATE_LIMITED: Se superó el límite de peticiones por minuto de la API key, el tope de consultas por hora al MTC o el de consultas por minuto a SUNAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_ERROR: Fallo inesperado del propio servicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"SUNAT_FORMAT_CHANGED: SUNAT respondió algo que el servicio no sabe leer; Pytronia recibe el aviso. En un lote, sale en cada comprobante afectado; el lote entero falla así solo si no se pudo leer ninguno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"SERVICE_DISABLED: El servicio pedido está desactivado en este servidor. SUNAT_UNAVAILABLE: SUNAT no respondió o falló. En un lote, sale en cada comprobante afectado; el lote entero falla así solo si no se pudo consultar ninguno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"CPEArchivo":{"properties":{"filename":{"type":"string","title":"Filename","description":"Nombre del archivo."},"content_base64":{"type":"string","title":"Content Base64","description":"Contenido del archivo en base64."},"size":{"type":"integer","title":"Size","description":"Tamaño en bytes."},"via":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Via","description":"Por dónde se obtuvo: «oficial» (la aplicación SUNAT) o «portal» (el portal SOL, de respaldo)."}},"type":"object","required":["filename","content_base64","size"],"title":"CPEArchivo","description":"Un archivo del comprobante.","examples":[{"content_base64":"PD94bWwgdmVyc2lvbj0iMS4wIj8+","filename":"20999999999-01-F001-123.xml","size":8421,"via":"oficial"}]},"CPEConsulta":{"properties":{"ruc_emisor":{"type":"string","title":"Ruc Emisor","description":"RUC del emisor."},"tipo_comprobante":{"type":"string","title":"Tipo Comprobante","description":"Tipo de comprobante (01, 03, 07 u 08)."},"serie":{"type":"string","title":"Serie","description":"Serie."},"numero":{"type":"integer","title":"Numero","description":"Correlativo."},"fecha_emision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fecha Emision","description":"Fecha de emisión tal como la da SUNAT (dd/mm/aaaa)."},"moneda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moneda","description":"Código de moneda (PEN, USD...)."},"total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total","description":"Importe total."},"razon_social_emisor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social Emisor","description":"Razón social del emisor."},"razon_social_receptor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social Receptor","description":"Razón social del receptor."}},"type":"object","required":["ruc_emisor","tipo_comprobante","serie","numero"],"title":"CPEConsulta","description":"Datos de un comprobante tal como los tiene SUNAT.","examples":[{"fecha_emision":"15/09/2026","moneda":"PEN","numero":123,"razon_social_emisor":"EMPRESA EMISORA S.A.C.","razon_social_receptor":"SU EMPRESA S.A.C.","ruc_emisor":"20999999999","serie":"F001","tipo_comprobante":"01","total":1180.0}]},"CPERequest":{"properties":{"ruc":{"type":"string","title":"Ruc","description":"RUC de la empresa que consulta (la que emitió o recibió el comprobante)."},"usuario":{"type":"string","title":"Usuario","description":"Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL."},"password":{"type":"string","title":"Password","description":"Clave SOL de ese usuario. No se guarda en el servicio."},"ruc_emisor":{"type":"string","title":"Ruc Emisor","description":"RUC de quien emitió el comprobante."},"tipo":{"type":"string","title":"Tipo","description":"Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.","default":"01"},"serie":{"type":"string","title":"Serie","description":"Serie del comprobante, por ejemplo F001."},"numero":{"type":"string","title":"Numero","description":"Correlativo del comprobante, por ejemplo 123."},"filtro":{"type":"string","title":"Filtro","description":"1 emitido por la empresa que consulta; 2 recibido de un proveedor.","default":"2"},"oauth_client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oauth Client Id","description":"client_id de la aplicación que la empresa genera en SOL («Credenciales de API SUNAT»). Con él y su secreto se usa la vía oficial de SUNAT."},"oauth_client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oauth Client Secret","description":"client_secret de esa aplicación."},"oauth_user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oauth User","description":"Usuario SOL de la vía oficial, si no es `usuario`."},"oauth_password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oauth Password","description":"Clave de ese usuario, si no es `password`."}},"type":"object","required":["ruc","usuario","password","ruc_emisor","serie","numero"],"title":"CPERequest","description":"Petición de consulta o descarga de un comprobante.","examples":[{"filtro":"2","numero":"123","oauth_client_id":"00000000-0000-0000-0000-000000000000","oauth_client_secret":"secreto","password":"clave-sol","ruc":"20100000001","ruc_emisor":"20999999999","serie":"F001","tipo":"01","usuario":"USUARIO1"}]},"CarrierOut":{"properties":{"ruc":{"type":"string","title":"Ruc","description":"RUC de la empresa de transporte."},"name":{"type":"string","title":"Name","description":"Razón social de la empresa de transporte."},"mtc_registration":{"type":"string","title":"Mtc Registration","description":"Número de Registro MTC del transportista, el que pide la guía de remisión. Solo letras y números en mayúscula."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Estado de la empresa en el registro del MTC."},"authorized":{"type":"boolean","title":"Authorized","description":"La empresa está habilitada y su autorización no ha vencido."},"valid_until":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Valid Until","description":"Fin de la autorización (AAAA-MM-DD)."},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality","description":"Modalidad de la empresa en el registro."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Ciudad en la que se inscribió."}},"type":"object","required":["ruc","name","mtc_registration","authorized"],"title":"CarrierOut"},"DocumentIn":{"properties":{"document_type":{"type":"string","enum":["01","03","07","08"],"title":"Document Type","description":"Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito."},"series":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]{3}$","title":"Series","description":"Serie del comprobante electrónico: una letra y tres letras o números (B001, F001, BC01)."},"number":{"type":"integer","maximum":99999999.0,"minimum":1.0,"title":"Number","description":"Número correlativo, sin ceros a la izquierda."},"issue_date":{"type":"string","format":"date","title":"Issue Date","description":"Fecha de emisión (AAAA-MM-DD). Tiene que ser la exacta."},"total":{"type":"number","minimum":0.0,"title":"Total","description":"Importe total, exacto y en positivo, también en las notas de crédito. Con otro importe u otra fecha, SUNAT contesta que no lo tiene."}},"type":"object","required":["document_type","series","number","issue_date","total"],"title":"DocumentIn"},"DocumentStatusOut":{"properties":{"document_type":{"type":"string","title":"Document Type","description":"Tipo de comprobante, como se pidió."},"series":{"type":"string","title":"Series","description":"Serie, como se pidió (en mayúscula)."},"number":{"type":"integer","title":"Number","description":"Número, como se pidió."},"status":{"type":"string","enum":["accepted","annulled","not_found","unknown"],"title":"Status","description":"accepted: SUNAT lo tiene y es válido. annulled: SUNAT lo tiene comunicado de baja. not_found: SUNAT no lo tiene con esa fecha y ese importe; puede no estar declarado o estarlo con otros datos, SUNAT no distingue. unknown: no se pudo saber; el motivo va en error."},"sunat_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sunat Code","description":"El estado tal como lo da SUNAT (estadoCp)."},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorBody"},{"type":"null"}],"description":"Por qué el estado es unknown; vacío en los demás. Su code puede ser SUNAT_UNAVAILABLE o RATE_LIMITED (reintentar más tarde), INVALID_REQUEST (SUNAT no aceptó los datos de ese comprobante) o SUNAT_FORMAT_CHANGED."}},"type":"object","required":["document_type","series","number","status"],"title":"DocumentStatusOut"},"DocumentStatusRequest":{"properties":{"credentials":{"$ref":"#/components/schemas/ValidityCredentials","description":"La aplicación de consulta de validez de la empresa."},"documents":{"items":{"$ref":"#/components/schemas/DocumentIn"},"type":"array","maxItems":50,"minItems":1,"title":"Documents","description":"Los comprobantes, de 1 a 50 por petición."}},"type":"object","required":["credentials","documents"],"title":"DocumentStatusRequest","examples":[{"credentials":{"client_id":"11111111-2222-3333-4444-555555555555","client_secret":"<su CLAVE>","ruc":"20999999991"},"documents":[{"document_type":"03","issue_date":"2026-09-24","number":1234,"series":"B001","total":25.0},{"document_type":"07","issue_date":"2026-09-23","number":12,"series":"BC01","total":4.0},{"document_type":"03","issue_date":"2026-09-24","number":1299,"series":"B001","total":10.0}]}]},"DocumentStatusResponse":{"properties":{"ruc":{"type":"string","title":"Ruc","description":"RUC de la empresa consultada."},"checked_at":{"type":"string","format":"date-time","title":"Checked At","description":"Cuándo se consultó a SUNAT, en UTC."},"documents":{"items":{"$ref":"#/components/schemas/DocumentStatusOut"},"type":"array","title":"Documents","description":"Un resultado por comprobante, en el orden pedido."}},"type":"object","required":["ruc","checked_at","documents"],"title":"DocumentStatusResponse","examples":[{"checked_at":"2026-09-26T02:30:00Z","documents":[{"document_type":"03","number":1234,"series":"B001","status":"accepted","sunat_code":"1"},{"document_type":"07","number":12,"series":"BC01","status":"accepted","sunat_code":"1"},{"document_type":"03","number":1299,"series":"B001","status":"not_found","sunat_code":"0"}],"ruc":"20999999991"}]},"ErrorBody":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode","description":"Código estable del error: decidir por él, no por el texto."},"message":{"type":"string","title":"Message","description":"Explicación para una persona; puede cambiar entre versiones."},"retryable":{"type":"boolean","title":"Retryable","description":"Si repetir la misma petición más tarde puede funcionar."}},"type":"object","required":["code","message","retryable"],"title":"ErrorBody"},"ErrorCode":{"type":"string","enum":["INVALID_REQUEST","UNAUTHORIZED","NOT_FOUND","RATE_LIMITED","SERVICE_DISABLED","MTC_UNAVAILABLE","MTC_FORMAT_CHANGED","SUNAT_UNAVAILABLE","SUNAT_CREDENTIALS_REJECTED","SUNAT_FORMAT_CHANGED","INTERNAL_ERROR"],"title":"ErrorCode"},"ErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody","description":"El error."}},"type":"object","required":["error"],"title":"ErrorEnvelope","description":"Forma común de todo error de las rutas /v1.","examples":[{"error":{"code":"MTC_UNAVAILABLE","message":"El MTC no respondió: sin respuesta del MTC (ConnectTimeout)","retryable":true}}]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LegacyErrorOut":{"properties":{"detail":{"type":"string","title":"Detail","description":"Qué pasó. «SUNAT error: …» marca los fallos de SUNAT."}},"type":"object","required":["detail"],"title":"LegacyErrorOut","description":"Error de las rutas de comprobantes. Si empieza por «SUNAT error:», el fallo es de SUNAT."},"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"},"ValidityCredentials":{"properties":{"ruc":{"type":"string","pattern":"^[0-9]{11}$","title":"Ruc","description":"RUC de la empresa: la dueña de la aplicación y la que emitió los comprobantes."},"client_id":{"type":"string","pattern":"^[A-Za-z0-9-]{1,100}$","title":"Client Id","description":"ID de la aplicación que la empresa registró en SOL, en «Consulta de Validez de Comprobantes de Pago». Las credenciales del SIRE no sirven aquí."},"client_secret":{"type":"string","maxLength":200,"minLength":1,"format":"password","title":"Client Secret","description":"CLAVE de esa aplicación. El servicio no la guarda.","writeOnly":true}},"type":"object","required":["ruc","client_id","client_secret"],"title":"ValidityCredentials"},"VehicleOut":{"properties":{"plate":{"type":"string","title":"Plate","description":"La placa consultada, sin guion ni espacios."},"registered":{"type":"boolean","title":"Registered","description":"Si la placa está en el registro de transporte de carga del MTC. Si es false, los demás datos vienen vacíos: es normal en vehículos M1/L o de menos de 2 TM."},"certificate_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certificate Number","description":"TUC o Certificado de Habilitación Vehicular del vehículo, el que pide la guía. Solo letras y números en mayúscula."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Categoría del vehículo (N1, N2, N3...)."},"chassis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chassis","description":"Serie del chasis."},"manufacture_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Manufacture Year","description":"Año de fabricación, si el MTC lo tiene."},"axles":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Axles","description":"Número de ejes."},"payload_kg":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Payload Kg","description":"Carga útil en kilos."},"dry_weight_kg":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Dry Weight Kg","description":"Peso seco en kilos."},"carrier":{"anyOf":[{"$ref":"#/components/schemas/CarrierOut"},{"type":"null"}],"description":"La empresa de transporte dueña del vehículo."},"source":{"type":"string","title":"Source","description":"De dónde sale el dato.","default":"MTC - Registro Nacional de Transporte de Carga"},"checked_at":{"type":"string","format":"date-time","title":"Checked At","description":"Cuándo se miró en el MTC, en UTC."},"from_cache":{"type":"boolean","title":"From Cache","description":"Si el dato salió de una consulta anterior, sin volver al MTC."}},"type":"object","required":["plate","registered","checked_at","from_cache"],"title":"VehicleOut","examples":[{"axles":2,"carrier":{"authorized":true,"city":"LIMA","modality":"Mercancias en general","mtc_registration":"15100000CNG","name":"TRANSPORTES DE PRUEBA S.A.C.","ruc":"20999999991","status":"Habilitado","valid_until":"2031-08-12"},"category":"N1","certificate_number":"15M25000004E","chassis":"CHASIS0000000004","checked_at":"2026-09-24T16:35:02Z","dry_weight_kg":1800,"from_cache":false,"payload_kg":1699,"plate":"ABC123","registered":true,"source":"MTC - Registro Nacional de Transporte de Carga"}]}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"API key de la empresa, que genera Pytronia.","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Comprobantes","description":"El XML, el PDF y el CDR de un comprobante electrónico, y sus datos, tal como los tiene SUNAT. Contrato anterior a /v1: se mantiene tal cual, y sus errores tienen otra forma."},{"name":"Estado de comprobantes","description":"Si SUNAT tiene cada comprobante de un lote: aceptado, de baja o no encontrado. Para decidir si uno en duda está declarado."},{"name":"Vehículos","description":"Los datos de un vehículo de carga para la guía de remisión: TUC y Registro MTC del transportista."}],"servers":[{"url":"https://cpe.sistemerp.com"}]}