Autenticación
Envía tu API Key de DatosPerú en Authorization: Bearer. La cuenta debe estar verificada y la clave debe tener permiso para esta operación. Guarda la clave en tu servidor o en el almacén de credenciales de tu herramienta.
Parámetros de consulta
Añade los parámetros a la URL con codificación URL. Los parámetros adicionales se rechazan.
| Campo | Obligatorio | Formato |
|---|---|---|
numRuc | Sí | string^[0-9]{11}$ |
tipoDocumento | Sí | string |
numSerieComprobante | Sí | string |
numDocumentoComprobante | Sí | string |
Ejemplo cURL
Los números y las credenciales del ejemplo son ilustrativos. Sustitúyelos por datos cuya consulta tengas autorizada. Una petición exitosa utiliza créditos reales.
curl --request GET 'https://api.datosperu.net/api/v1/sunat/guia/json?numRuc=20123456789&tipoDocumento=09&numSerieComprobante=T001&numDocumentoComprobante=1' \
--header "Authorization: Bearer $DATOSPERU_API_KEY" \
--header 'Content-Type: application/json'Schema de la respuesta
Una consulta exitosa devuelve success: true, data y meta. El siguiente esquema corresponde a data. Los campos opcionales dependen de la fuente; null indica ausencia de valor.
{
"type": [
"object",
"null"
],
"description": "Datos detallados de la respuesta"
}meta.request_id identifica la solicitud y meta.timestamp utiliza una fecha ISO 8601. No registres los datos personales o archivos completos cuando solo necesites identificar un incidente.
Errores y reintentos
Los errores devuelven success: false y un objeto error con code y message. Un error del proveedor libera la reserva de crédito. Evita reintentar entradas inválidas o claves revocadas.
| HTTP | Cómo actuar |
|---|---|
| 401 | API Key ausente, inválida o revocada. Revisa la credencial. |
| 403 | Cuenta, verificación o permiso insuficiente. Revisa tu acceso. |
| 404 | Sin resultados o ruta inexistente. Comprueba los datos y el endpoint. |
| 422 | Parámetros inválidos. Corrige el cuerpo antes de reintentar. |
| 429 | Límite por minuto o cuota del periodo. Revisa el código de error y tu consumo. |
| 502 / 504 | Error o demora de la fuente. Reintenta con espera y un máximo de intentos. |
| 503 | Servicio no disponible o pendiente de configuración. Consulta el estado. |
Consumo y disponibilidad
Una consulta exitosa consume un crédito. Gratis incluye 100 créditos cada 30 días. Los planes pagados renuevan según su periodo contratado; cada plan conserva un límite por minuto. Revisa los valores vigentes en Precios.
La disponibilidad depende de la fuente y la configuración del servicio. DatosPerú es independiente de las entidades públicas mencionadas y utiliza JSON.pe como proveedor. Consulta solo los datos que estés autorizado a tratar.