Referencia API

Generada del propio servicio: lo que se lee aquí es lo que responde.

Dirección base: https://cpe.sistemerp.com
Autenticación: cabecera X-API-Key con la API key de su empresa (ver Autenticación).
Errores: ver los códigos de error y cuándo reintentar.
Contrato en formato OpenAPI: /openapi.json.

Comprobantes

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.

POST/api/v1/cpe/consultar

Datos de un comprobante

Datos de un comprobante tal como los tiene SUNAT (fecha, moneda, total y razones sociales), sin descargar archivos.

Requiere la cabecera X-API-Key.

Cuerpo (JSON): `CPERequest`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa que consulta (la que emitió o recibió el comprobante).
`usuario`	texto	Sí	Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL.
`password`	texto	Sí	Clave SOL de ese usuario. No se guarda en el servicio.
`ruc_emisor`	texto	Sí	RUC de quien emitió el comprobante.
`tipo`	texto	No (por defecto "01")	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`serie`	texto	Sí	Serie del comprobante, por ejemplo F001.
`numero`	texto	Sí	Correlativo del comprobante, por ejemplo 123.
`filtro`	texto	No (por defecto "2")	1 emitido por la empresa que consulta; 2 recibido de un proveedor.
`oauth_client_id`	texto o null	No	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`	texto o null	No	client_secret de esa aplicación.
`oauth_user`	texto o null	No	Usuario SOL de la vía oficial, si no es `usuario`.
`oauth_password`	texto o null	No	Clave de ese usuario, si no es `password`.

{
  "ruc": "20100000001",
  "usuario": "USUARIO1",
  "password": "clave-sol",
  "ruc_emisor": "20999999999",
  "tipo": "01",
  "serie": "F001",
  "numero": "123",
  "filtro": "2",
  "oauth_client_id": "00000000-0000-0000-0000-000000000000",
  "oauth_client_secret": "secreto"
}

Respuestas

HTTP	Contenido	Cuándo
200	`CPEConsulta`	Los datos del comprobante.
401	`LegacyErrorOut`	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.
403	`LegacyErrorOut`	API key no autorizada: no existe o está desactivada.
404	`LegacyErrorOut`	El comprobante no está en SUNAT o no tiene ese archivo.
422	`HTTPValidationError`	Validation Error
429	`LegacyErrorOut`	Se superó el límite de peticiones por minuto de la API key.
500	`LegacyErrorOut`	SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.
502	`LegacyErrorOut`	SUNAT error: SUNAT respondió algo ilegible; reintentar.
503	`LegacyErrorOut`	SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.
504	`LegacyErrorOut`	SUNAT error: SUNAT no respondió a tiempo; reintentar.

Ejemplo de respuesta correcta:

{
  "ruc_emisor": "20999999999",
  "tipo_comprobante": "01",
  "serie": "F001",
  "numero": 123,
  "fecha_emision": "15/09/2026",
  "moneda": "PEN",
  "total": 1180.0,
  "razon_social_emisor": "EMPRESA EMISORA S.A.C.",
  "razon_social_receptor": "SU EMPRESA S.A.C."
}

POST/api/v1/cpe/pdf

PDF de un comprobante

La representación impresa del comprobante, en base64.

Requiere la cabecera X-API-Key.

Cuerpo (JSON): `CPERequest`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa que consulta (la que emitió o recibió el comprobante).
`usuario`	texto	Sí	Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL.
`password`	texto	Sí	Clave SOL de ese usuario. No se guarda en el servicio.
`ruc_emisor`	texto	Sí	RUC de quien emitió el comprobante.
`tipo`	texto	No (por defecto "01")	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`serie`	texto	Sí	Serie del comprobante, por ejemplo F001.
`numero`	texto	Sí	Correlativo del comprobante, por ejemplo 123.
`filtro`	texto	No (por defecto "2")	1 emitido por la empresa que consulta; 2 recibido de un proveedor.
`oauth_client_id`	texto o null	No	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`	texto o null	No	client_secret de esa aplicación.
`oauth_user`	texto o null	No	Usuario SOL de la vía oficial, si no es `usuario`.
`oauth_password`	texto o null	No	Clave de ese usuario, si no es `password`.

{
  "ruc": "20100000001",
  "usuario": "USUARIO1",
  "password": "clave-sol",
  "ruc_emisor": "20999999999",
  "tipo": "01",
  "serie": "F001",
  "numero": "123",
  "filtro": "2",
  "oauth_client_id": "00000000-0000-0000-0000-000000000000",
  "oauth_client_secret": "secreto"
}

Respuestas

HTTP	Contenido	Cuándo
200	`CPEArchivo`	El archivo del comprobante.
401	`LegacyErrorOut`	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.
403	`LegacyErrorOut`	API key no autorizada: no existe o está desactivada.
404	`LegacyErrorOut`	El comprobante no está en SUNAT o no tiene ese archivo.
422	`HTTPValidationError`	Validation Error
429	`LegacyErrorOut`	Se superó el límite de peticiones por minuto de la API key.
500	`LegacyErrorOut`	SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.
502	`LegacyErrorOut`	SUNAT error: SUNAT respondió algo ilegible; reintentar.
503	`LegacyErrorOut`	SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.
504	`LegacyErrorOut`	SUNAT error: SUNAT no respondió a tiempo; reintentar.

Ejemplo de respuesta correcta:

{
  "filename": "20999999999-01-F001-123.xml",
  "content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+",
  "size": 8421,
  "via": "oficial"
}

POST/api/v1/cpe/xml

XML de un comprobante

El XML firmado del comprobante, en base64.

Requiere la cabecera X-API-Key.

Cuerpo (JSON): `CPERequest`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa que consulta (la que emitió o recibió el comprobante).
`usuario`	texto	Sí	Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL.
`password`	texto	Sí	Clave SOL de ese usuario. No se guarda en el servicio.
`ruc_emisor`	texto	Sí	RUC de quien emitió el comprobante.
`tipo`	texto	No (por defecto "01")	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`serie`	texto	Sí	Serie del comprobante, por ejemplo F001.
`numero`	texto	Sí	Correlativo del comprobante, por ejemplo 123.
`filtro`	texto	No (por defecto "2")	1 emitido por la empresa que consulta; 2 recibido de un proveedor.
`oauth_client_id`	texto o null	No	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`	texto o null	No	client_secret de esa aplicación.
`oauth_user`	texto o null	No	Usuario SOL de la vía oficial, si no es `usuario`.
`oauth_password`	texto o null	No	Clave de ese usuario, si no es `password`.

{
  "ruc": "20100000001",
  "usuario": "USUARIO1",
  "password": "clave-sol",
  "ruc_emisor": "20999999999",
  "tipo": "01",
  "serie": "F001",
  "numero": "123",
  "filtro": "2",
  "oauth_client_id": "00000000-0000-0000-0000-000000000000",
  "oauth_client_secret": "secreto"
}

Respuestas

HTTP	Contenido	Cuándo
200	`CPEArchivo`	El archivo del comprobante.
401	`LegacyErrorOut`	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.
403	`LegacyErrorOut`	API key no autorizada: no existe o está desactivada.
404	`LegacyErrorOut`	El comprobante no está en SUNAT o no tiene ese archivo.
422	`HTTPValidationError`	Validation Error
429	`LegacyErrorOut`	Se superó el límite de peticiones por minuto de la API key.
500	`LegacyErrorOut`	SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.
502	`LegacyErrorOut`	SUNAT error: SUNAT respondió algo ilegible; reintentar.
503	`LegacyErrorOut`	SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.
504	`LegacyErrorOut`	SUNAT error: SUNAT no respondió a tiempo; reintentar.

Ejemplo de respuesta correcta:

{
  "filename": "20999999999-01-F001-123.xml",
  "content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+",
  "size": 8421,
  "via": "oficial"
}

POST/api/v1/cpe/cdr

CDR de un comprobante

La constancia de recepción de SUNAT (CDR), en base64.

Requiere la cabecera X-API-Key.

Cuerpo (JSON): `CPERequest`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa que consulta (la que emitió o recibió el comprobante).
`usuario`	texto	Sí	Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL.
`password`	texto	Sí	Clave SOL de ese usuario. No se guarda en el servicio.
`ruc_emisor`	texto	Sí	RUC de quien emitió el comprobante.
`tipo`	texto	No (por defecto "01")	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`serie`	texto	Sí	Serie del comprobante, por ejemplo F001.
`numero`	texto	Sí	Correlativo del comprobante, por ejemplo 123.
`filtro`	texto	No (por defecto "2")	1 emitido por la empresa que consulta; 2 recibido de un proveedor.
`oauth_client_id`	texto o null	No	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`	texto o null	No	client_secret de esa aplicación.
`oauth_user`	texto o null	No	Usuario SOL de la vía oficial, si no es `usuario`.
`oauth_password`	texto o null	No	Clave de ese usuario, si no es `password`.

{
  "ruc": "20100000001",
  "usuario": "USUARIO1",
  "password": "clave-sol",
  "ruc_emisor": "20999999999",
  "tipo": "01",
  "serie": "F001",
  "numero": "123",
  "filtro": "2",
  "oauth_client_id": "00000000-0000-0000-0000-000000000000",
  "oauth_client_secret": "secreto"
}

Respuestas

HTTP	Contenido	Cuándo
200	`CPEArchivo`	El archivo del comprobante.
401	`LegacyErrorOut`	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.
403	`LegacyErrorOut`	API key no autorizada: no existe o está desactivada.
404	`LegacyErrorOut`	El comprobante no está en SUNAT o no tiene ese archivo.
422	`HTTPValidationError`	Validation Error
429	`LegacyErrorOut`	Se superó el límite de peticiones por minuto de la API key.
500	`LegacyErrorOut`	SUNAT error: fallo de SUNAT, que ocurre al azar; reintentar.
502	`LegacyErrorOut`	SUNAT error: SUNAT respondió algo ilegible; reintentar.
503	`LegacyErrorOut`	SUNAT error: SUNAT no pudo dar acceso en ese momento; reintentar.
504	`LegacyErrorOut`	SUNAT error: SUNAT no respondió a tiempo; reintentar.

Ejemplo de respuesta correcta:

{
  "filename": "20999999999-01-F001-123.xml",
  "content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+",
  "size": 8421,
  "via": "oficial"
}

Estado de comprobantes

Si SUNAT tiene cada comprobante de un lote: aceptado, de baja o no encontrado. Para decidir si uno en duda está declarado.

POST/v1/documents/status

Estado de comprobantes en SUNAT

Pregunta a SUNAT, con la consulta de validez, si tiene cada comprobante del lote: facturas, boletas y notas de la empresa, también las declaradas por resumen diario. Sirve para decidir, ante un resumen en duda, si un comprobante está declarado o hay que volver a enviarlo.

Requiere la cabecera X-API-Key.

Cuerpo (JSON): `DocumentStatusRequest`

Campo	Tipo	Obligatorio	Descripción
`credentials`	`ValidityCredentials`	Sí	La aplicación de consulta de validez de la empresa.
`documents`	`lista de DocumentIn`	Sí	Los comprobantes, de 1 a 50 por petición.

{
  "credentials": {
    "ruc": "20999999991",
    "client_id": "11111111-2222-3333-4444-555555555555",
    "client_secret": "<su CLAVE>"
  },
  "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
    }
  ]
}

Respuestas

HTTP	Contenido	Cuándo
200	`DocumentStatusResponse`	Un resultado por comprobante. Un fallo de SUNAT en uno lo deja en unknown sin tumbar el lote.
401	`ErrorEnvelope`	UNAUTHORIZED: Falta la API key, no existe o su cliente está desactivado.
403	`ErrorEnvelope`	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.
405	`ErrorEnvelope`	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.
422	`ErrorEnvelope`	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.
429	`ErrorEnvelope`	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.
500	`ErrorEnvelope`	INTERNAL_ERROR: Fallo inesperado del propio servicio.
502	`ErrorEnvelope`	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.
503	`ErrorEnvelope`	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.

Ejemplo de respuesta correcta:

{
  "ruc": "20999999991",
  "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"
    }
  ]
}

Vehículos

Los datos de un vehículo de carga para la guía de remisión: TUC y Registro MTC del transportista.

GET/v1/vehicles/{plate}

Vehículo por placa

Busca la placa en el Registro Nacional de Transporte de Carga del MTC y devuelve la TUC del vehículo y el Registro MTC del transportista, lo que pide la guía de remisión. La placa puede ir con o sin guion. Lo ya consultado se sirve sin volver al MTC.

Requiere la cabecera X-API-Key.

Parámetros de la ruta

Campo	Tipo	Obligatorio	Descripción
`plate`	texto	Sí	Placa del vehículo, con o sin guion (ABC123 o ABC-123).

Respuestas

HTTP	Contenido	Cuándo
200	`VehicleOut`	El vehículo. Si la placa no está en el registro de carga, registered es false.
401	`ErrorEnvelope`	UNAUTHORIZED: Falta la API key, no existe o su cliente está desactivado.
405	`ErrorEnvelope`	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.
422	`ErrorEnvelope`	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.
429	`ErrorEnvelope`	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.
500	`ErrorEnvelope`	INTERNAL_ERROR: Fallo inesperado del propio servicio.
502	`ErrorEnvelope`	MTC_FORMAT_CHANGED: La consulta del MTC cambió o pidió verificación humana; queda suspendida y Pytronia recibe el aviso.
503	`ErrorEnvelope`	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.

Ejemplo de respuesta correcta:

{
  "plate": "ABC123",
  "registered": true,
  "certificate_number": "15M25000004E",
  "category": "N1",
  "chassis": "CHASIS0000000004",
  "axles": 2,
  "payload_kg": 1699,
  "dry_weight_kg": 1800,
  "carrier": {
    "ruc": "20999999991",
    "name": "TRANSPORTES DE PRUEBA S.A.C.",
    "mtc_registration": "15100000CNG",
    "status": "Habilitado",
    "authorized": true,
    "valid_until": "2031-08-12",
    "modality": "Mercancias en general",
    "city": "LIMA"
  },
  "source": "MTC - Registro Nacional de Transporte de Carga",
  "checked_at": "2026-09-24T16:35:02Z",
  "from_cache": false
}

Errores de las rutas /v1

Todos con la forma {"error": {"code", "message", "retryable"}}. Decida por code y retryable, no por el texto. Las rutas de comprobantes responden {"detail": ...}, un texto salvo en el 422 (una lista de campos): ver Errores y reintentos.

code	HTTP	Cuándo	¿Reintentar?	Qué hacer
`INVALID_REQUEST`	422 / 405	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.	No	Corregir la petición; repetirla igual dará el mismo error.
`UNAUTHORIZED`	401	Falta la API key, no existe o su cliente está desactivado.	No	Revisar la cabecera X-API-Key o pedir una clave a Pytronia.
`NOT_FOUND`	404	La ruta no existe.	No	Revisar la dirección contra la referencia.
`RATE_LIMITED`	429	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.	Sí	Esperar los segundos de la cabecera Retry-After y reintentar.
`SERVICE_DISABLED`	503	El servicio pedido está desactivado en este servidor.	No	Consultar con Pytronia; reintentar no sirve.
`MTC_UNAVAILABLE`	503	El MTC no responde, está atendiendo otra consulta o está en pausa tras un fallo.	Sí	Esperar los segundos de la cabecera Retry-After y reintentar; antes, dará el mismo error.
`MTC_FORMAT_CHANGED`	502	La consulta del MTC cambió o pidió verificación humana; queda suspendida y Pytronia recibe el aviso.	No	No reintentar; consultar con Pytronia.
`SUNAT_UNAVAILABLE`	503	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.	Sí	Reintentar pasado un minuto, o lo que diga la cabecera Retry-After.
`SUNAT_CREDENTIALS_REJECTED`	403	SUNAT rechazó las credenciales de la aplicación: no existen, se revocaron o la aplicación no está registrada para el servicio pedido.	No	Revisar las credenciales de la aplicación en SOL; repetir la petición dará el mismo error.
`SUNAT_FORMAT_CHANGED`	502	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.	No	No reintentar; consultar con Pytronia.
`INTERNAL_ERROR`	500	Fallo inesperado del propio servicio.	Sí	Reintentar más tarde; si se repite, escribir a Pytronia con el X-Request-Id de la respuesta.

Modelos

`CPEArchivo`

Un archivo del comprobante.

Campo	Tipo	Obligatorio	Descripción
`filename`	texto	Sí	Nombre del archivo.
`content_base64`	texto	Sí	Contenido del archivo en base64.
`size`	entero	Sí	Tamaño en bytes.
`via`	texto o null	No	Por dónde se obtuvo: «oficial» (la aplicación SUNAT) o «portal» (el portal SOL, de respaldo).

`CPEConsulta`

Datos de un comprobante tal como los tiene SUNAT.

Campo	Tipo	Obligatorio	Descripción
`ruc_emisor`	texto	Sí	RUC del emisor.
`tipo_comprobante`	texto	Sí	Tipo de comprobante (01, 03, 07 u 08).
`serie`	texto	Sí	Serie.
`numero`	entero	Sí	Correlativo.
`fecha_emision`	texto o null	No	Fecha de emisión tal como la da SUNAT (dd/mm/aaaa).
`moneda`	texto o null	No	Código de moneda (PEN, USD...).
`total`	número o null	No	Importe total.
`razon_social_emisor`	texto o null	No	Razón social del emisor.
`razon_social_receptor`	texto o null	No	Razón social del receptor.

`CPERequest`

Petición de consulta o descarga de un comprobante.

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa que consulta (la que emitió o recibió el comprobante).
`usuario`	texto	Sí	Usuario SOL de esa empresa, para la vía de respaldo por el portal SOL.
`password`	texto	Sí	Clave SOL de ese usuario. No se guarda en el servicio.
`ruc_emisor`	texto	Sí	RUC de quien emitió el comprobante.
`tipo`	texto	No (por defecto "01")	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`serie`	texto	Sí	Serie del comprobante, por ejemplo F001.
`numero`	texto	Sí	Correlativo del comprobante, por ejemplo 123.
`filtro`	texto	No (por defecto "2")	1 emitido por la empresa que consulta; 2 recibido de un proveedor.
`oauth_client_id`	texto o null	No	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`	texto o null	No	client_secret de esa aplicación.
`oauth_user`	texto o null	No	Usuario SOL de la vía oficial, si no es `usuario`.
`oauth_password`	texto o null	No	Clave de ese usuario, si no es `password`.

`CarrierOut`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa de transporte.
`name`	texto	Sí	Razón social de la empresa de transporte.
`mtc_registration`	texto	Sí	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`	texto o null	No	Estado de la empresa en el registro del MTC.
`authorized`	booleano	Sí	La empresa está habilitada y su autorización no ha vencido.
`valid_until`	fecha (AAAA-MM-DD) o null	No	Fin de la autorización (AAAA-MM-DD).
`modality`	texto o null	No	Modalidad de la empresa en el registro.
`city`	texto o null	No	Ciudad en la que se inscribió.

`DocumentIn`

Campo	Tipo	Obligatorio	Descripción
`document_type`	texto: 01, 03, 07, 08	Sí	Tipo de comprobante: 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
`series`	texto	Sí	Serie del comprobante electrónico: una letra y tres letras o números (B001, F001, BC01).
`number`	entero	Sí	Número correlativo, sin ceros a la izquierda.
`issue_date`	fecha (AAAA-MM-DD)	Sí	Fecha de emisión (AAAA-MM-DD). Tiene que ser la exacta.
`total`	número	Sí	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.

`DocumentStatusOut`

Campo	Tipo	Obligatorio	Descripción
`document_type`	texto	Sí	Tipo de comprobante, como se pidió.
`series`	texto	Sí	Serie, como se pidió (en mayúscula).
`number`	entero	Sí	Número, como se pidió.
`status`	texto: accepted, annulled, not_found, unknown	Sí	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`	texto o null	No	El estado tal como lo da SUNAT (estadoCp).
`error`	`ErrorBody` o null	No	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.

`DocumentStatusRequest`

Campo	Tipo	Obligatorio	Descripción
`credentials`	`ValidityCredentials`	Sí	La aplicación de consulta de validez de la empresa.
`documents`	`lista de DocumentIn`	Sí	Los comprobantes, de 1 a 50 por petición.

`DocumentStatusResponse`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa consultada.
`checked_at`	fecha y hora UTC	Sí	Cuándo se consultó a SUNAT, en UTC.
`documents`	`lista de DocumentStatusOut`	Sí	Un resultado por comprobante, en el orden pedido.

`ErrorBody`

Campo	Tipo	Obligatorio	Descripción
`code`	`ErrorCode`	Sí	Código estable del error: decidir por él, no por el texto.
`message`	texto	Sí	Explicación para una persona; puede cambiar entre versiones.
`retryable`	booleano	Sí	Si repetir la misma petición más tarde puede funcionar.

`ErrorCode`

Uno de: INVALID_REQUEST, UNAUTHORIZED, NOT_FOUND, RATE_LIMITED, SERVICE_DISABLED, MTC_UNAVAILABLE, MTC_FORMAT_CHANGED, SUNAT_UNAVAILABLE, SUNAT_CREDENTIALS_REJECTED, SUNAT_FORMAT_CHANGED, INTERNAL_ERROR.

`ErrorEnvelope`

Forma común de todo error de las rutas /v1.

Campo	Tipo	Obligatorio	Descripción
`error`	`ErrorBody`	Sí	El error.

`HTTPValidationError`

Campo	Tipo	Obligatorio	Descripción
`detail`	`lista de ValidationError`	No

`LegacyErrorOut`

Error de las rutas de comprobantes. Si empieza por «SUNAT error:», el fallo es de SUNAT.

Campo	Tipo	Obligatorio	Descripción
`detail`	texto	Sí	Qué pasó. «SUNAT error: …» marca los fallos de SUNAT.

`ValidationError`

Campo	Tipo	Obligatorio
`loc`	lista de texto o entero	Sí
`msg`	texto	Sí
`type`	texto	Sí
`input`	cualquiera	No
`ctx`	objeto	No

`ValidityCredentials`

Campo	Tipo	Obligatorio	Descripción
`ruc`	texto	Sí	RUC de la empresa: la dueña de la aplicación y la que emitió los comprobantes.
`client_id`	texto	Sí	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`	texto	Sí	CLAVE de esa aplicación. El servicio no la guarda.

`VehicleOut`

Campo	Tipo	Obligatorio	Descripción
`plate`	texto	Sí	La placa consultada, sin guion ni espacios.
`registered`	booleano	Sí	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`	texto o null	No	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`	texto o null	No	Categoría del vehículo (N1, N2, N3...).
`chassis`	texto o null	No	Serie del chasis.
`manufacture_year`	entero o null	No	Año de fabricación, si el MTC lo tiene.
`axles`	entero o null	No	Número de ejes.
`payload_kg`	entero o null	No	Carga útil en kilos.
`dry_weight_kg`	entero o null	No	Peso seco en kilos.
`carrier`	`CarrierOut` o null	No	La empresa de transporte dueña del vehículo.
`source`	texto	No (por defecto "MTC - Registro Nacional de Transporte de Carga")	De dónde sale el dato.
`checked_at`	fecha y hora UTC	Sí	Cuándo se miró en el MTC, en UTC.
`from_cache`	booleano	Sí	Si el dato salió de una consulta anterior, sin volver al MTC.

Referencia API

Comprobantes

POST/api/v1/cpe/consultar

Cuerpo (JSON): CPERequest

Respuestas

POST/api/v1/cpe/pdf

Cuerpo (JSON): CPERequest

Respuestas

POST/api/v1/cpe/xml

Cuerpo (JSON): CPERequest

Respuestas

POST/api/v1/cpe/cdr

Cuerpo (JSON): CPERequest

Respuestas

Estado de comprobantes

POST/v1/documents/status

Cuerpo (JSON): DocumentStatusRequest

Respuestas

Vehículos

GET/v1/vehicles/{plate}

Parámetros de la ruta

Respuestas

Errores de las rutas /v1

Modelos

CPEArchivo

CPEConsulta

CPERequest

CarrierOut

DocumentIn

DocumentStatusOut

DocumentStatusRequest

DocumentStatusResponse

ErrorBody

ErrorCode

ErrorEnvelope

HTTPValidationError

LegacyErrorOut

ValidationError

ValidityCredentials

VehicleOut

Cuerpo (JSON): `CPERequest`

Cuerpo (JSON): `CPERequest`

Cuerpo (JSON): `CPERequest`

Cuerpo (JSON): `CPERequest`

Cuerpo (JSON): `DocumentStatusRequest`

`CPEArchivo`

`CPEConsulta`

`CPERequest`

`CarrierOut`

`DocumentIn`

`DocumentStatusOut`

`DocumentStatusRequest`

`DocumentStatusResponse`

`ErrorBody`

`ErrorCode`

`ErrorEnvelope`

`HTTPValidationError`

`LegacyErrorOut`

`ValidationError`

`ValidityCredentials`

`VehicleOut`