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.
Cuerpo JSON
Envía Content-Type: application/json. Los valores de entrada se expresan como cadenas. Los parámetros adicionales se rechazan.
| Campo | Obligatorio | Formato |
|---|---|---|
dni | Sí | Número de Documento Nacional de Identidad (DNI) de 8 dígitos. Debe ser numérico y tener exactamente 8 caracteres.^[0-9]{8}$ |
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 POST 'https://api.datosperu.net/api/v1/dni' \
--header "Authorization: Bearer $DATOSPERU_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"dni": "12345678"
}'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",
"additionalProperties": false,
"properties": {
"documento": {
"type": [
"string",
"null"
],
"description": "Número de DNI consultado"
},
"nombres": {
"type": [
"string",
"null"
],
"description": "Nombres de pila de la persona"
},
"apellido_paterno": {
"type": [
"string",
"null"
],
"description": "Primer apellido (apellido paterno) de la persona"
},
"apellido_materno": {
"type": [
"string",
"null"
],
"description": "Segundo apellido (apellido materno) de la persona"
}
}
}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.