---
name: faktura-consultar-un-dni
description: "Consultar un DNI con la API de Faktura (facturación electrónica SUNAT, Perú). Encuentra el nombre de una persona que tiene RUC 10, es decir, que se registró en SUNAT como persona natural con negocio. Su RUC es 10 + DNI + un dígito veri… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Consultar un DNI — Faktura API

## Propósito

Le da a tu asistente el contexto para **consultar un DNI** con la API de Faktura: Encuentra el nombre de una persona que tiene RUC 10, es decir, que se registró en SUNAT como persona natural con negocio. Su RUC es 10 + DNI + un dígito veri…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-consultar-un-dni/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/endpoints/consultas/dni/

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/lookup/dni/{dni}` |
| Producción | `GET https://faktura.cgallardo.me/v1/lookup/dni/{dni}` |

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

## Ejemplo

```bash
curl https://faktura-test.cgallardo.me/v1/lookup/dni/46779354 -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{ "dni": "46779354", "full_name": "QUISPE MAMANI JUAN CARLOS", "ruc": "10467793549", "as_of": "2026-11-15" }
```

| Campo | Descripción |
| --- | --- |
| `full_name` | Como figura en el padrón de SUNAT: apellidos y nombres. |
| `ruc` | El RUC 10 del que proviene el nombre. |
| `as_of` | Fecha del padrón de SUNAT usado. |

## Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `InvalidDni` | No son 8 dígitos. |
| `404` | `DniNotFound` | La persona **no tiene RUC 10** en el padrón. **No** significa que el DNI no exista: la mayoría de personas no tiene RUC. Pide el nombre al cliente. |
| `503` | `DniLookupUnavailable` | El servicio de consulta no está disponible temporalmente. |

Para una **boleta** no necesitas esta consulta: envía el nombre que te dé el cliente. Úsala para autocompletar cuando se pueda.

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
