--- name: datosperu description: Integra o consulta la API REST de DatosPerú para DNI, RUC, SUNAT, vehículos, recibos y finanzas. Úsalo cuando el usuario pida trabajar con datosperu.net o implementar una consulta con sus endpoints. metadata: version: "1.0.0" homepage: "https://datosperu.net/docs/skill" --- # DatosPerú API Implementa integraciones o realiza las consultas que el usuario solicite mediante la API de DatosPerú. Es un servicio independiente que utiliza JSON.pe como proveedor; no es una API oficial de SUNAT ni RENIEC. ## Contrato y selección de endpoints Antes de implementar, consulta [OpenAPI 3.1](https://datosperu.net/openapi.json) y la referencia del endpoint. Usa su método, nombres de parámetros y esquema; no deduzcas las rutas a partir del nombre de una entidad. El índice [llms.txt](https://datosperu.net/llms.txt) enlaza la referencia en Markdown de las 25 operaciones. - Base: `https://api.datosperu.net`. - Prefijo de todas las consultas: `/api/v1/`. - DNI: `POST /api/v1/dni`, campo `dni` (8 dígitos). - RUC: `POST /api/v1/ruc`, campo `ruc` (11 dígitos). - Representantes: `POST /api/v1/ruc/representantes`, campo `ruc`; el resultado `data` es un array o null. - Otros: SUNAT/CPE, XML, guías, placa, SOAT, revisión técnica, recibos, tipo de cambio y AFP. Consulta sus esquemas antes de usarlos. - Las guías `sunat/guia/xml` y `sunat/guia/json` usan GET con query parameters. No envíes un JSON body en esos GET. - Todos los parámetros de consulta son strings. Mantén ceros iniciales y rechaza campos adicionales según OpenAPI. Lee solo la referencia pertinente: por ejemplo, [RUC en Markdown](https://datosperu.net/docs/ruc.md) o [representantes en Markdown](https://datosperu.net/docs/ruc/representantes.md). ## Autenticación y ejecución Usa `Authorization: Bearer `. Obtén la clave del entorno del proyecto o su gestor de secretos. Si falta, indica al usuario que la configure con una clave de producción creada en [su dashboard](https://datosperu.net/dashboard/keys). No solicites que pegue contraseñas, cookies ni tokens en código público. Las claves propias empiezan con `api_live_`; no sirven las claves de JSON.pe. `api_test_` devuelve `SANDBOX_NOT_AVAILABLE`: no existe todavía un sandbox operativo. Se requiere una cuenta verificada, una clave activa con permisos y cuota disponible. En una aplicación web, ejecuta la consulta desde el servidor. No incluyas la clave en JavaScript servido al navegador ni en parámetros de URL. Usa JSON y `Content-Type: application/json` en POST. Define un timeout, por ejemplo 30 segundos. No registres encabezados de autenticación ni respuestas personales completas. Para implementar código basta con trabajar sobre el contrato; no necesitas ejecutar una consulta real. Cuando el usuario solicite probar o consultar, utiliza los datos que haya proporcionado y el alcance autorizado. Los números de la documentación son ilustrativos. No consultes esos ejemplos como si fueran datos del usuario. ## Respuestas, errores y créditos Éxito: `{ "success": true, "data": ..., "meta": { "request_id": "...", "timestamp": "..." } }`. Error: `{ "success": false, "error": { "code": "...", "message": "..." }, "meta": ... }`. Algunos errores de infraestructura pueden omitir `meta` o no ser JSON; comprueba el estado HTTP y maneja ese caso. Valida `success` y el estado HTTP. Conserva arrays, campos opcionales y valores null; no rellenes información ausente con datos inventados. Un HTTP 200 no garantiza que todos los campos estén disponibles. - 401: corrige la clave; no repitas la misma solicitud automáticamente. - 403: revisa cuenta, verificación y permisos. - 404: revisa ruta y datos; no equivale a una respuesta exitosa vacía. - 409 `SANDBOX_NOT_AVAILABLE`: usa una clave live si el usuario desea ejecutar una consulta real. - 422: corrige el formato antes de reintentar. - 429: distingue límite de frecuencia y cuota agotada leyendo `error.code`. Respeta `Retry-After` en el límite por minuto; no reintentes una cuota agotada. - 502, 503, 504 o timeout: informa del fallo de fuente o disponibilidad. Un timeout puede haber sido procesado; no encadenes reintentos silenciosos que consuman créditos adicionales. Cada consulta exitosa consume un crédito; los errores del proveedor liberan la reserva. Los planes ilimitados mantienen límites por minuto. Consulta [precios](https://datosperu.net/precios) para los valores vigentes; no prometas un SLA ni cobertura universal. ## Entrega de la integración Conecta el resultado al flujo solicitado, presenta errores útiles y mantén la clave en configuración del servidor. Distingue las pruebas con fixtures de las consultas efectivamente realizadas. Para reproducir un error basta con el estado HTTP y `meta.request_id`, sin divulgar la respuesta personal. Recursos importables: [Postman](https://datosperu.net/postman.collection.json), [OpenAPI](https://datosperu.net/openapi.json), [guías de integración](https://datosperu.net/guias) y [probador web](https://datosperu.net/docs).