<h1>API — Guía de consumo</h1>
<p>Base: <code>https://dni-drey.pe2.lol</code></p>
<h2>Autenticación</h2>
<p>Todo request lleva tu token en el header <code>X-API-Key</code>.
Sin header → <code>401</code>. Sin token válido no hay acceso: los tokens solo los emite el administrador.</p>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" https://dni-drey.pe2.lol/dni/6282044
</code></pre>
<h2>Rate limit</h2>
<p>1 request cada 5 segundos por token. Si lo excedes → <code>429</code>.</p>
<h2>Buscar por DNI</h2>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" https://dni-drey.pe2.lol/dni/6282044
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"dni": "06282044", "nombre": "EJEMPLO APELLIDO NOMBRE", "anio": "1960"}
</code></pre>
<p>Busca sin el <code>0</code> inicial (<code>06282044</code> → <code>6282044</code>); la respuesta viene con <code>0</code> pad a 8.
Si el DNI ya está en caché responde directo; si no, hace consulta viva y la guarda.
Cada request válido descuenta 1 consulta de tu membresía.</p>
<h2>Verificar un DNI</h2>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" https://dni-drey.pe2.lol/dni/6282044/verificar
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"dni": "06282044", "nombre": "EJEMPLO APELLIDO NOMBRE", "anio": "1960", "verificacion": {"coincide": true, "nota": "re-comparado contra fuentes"}}
</code></pre>
<p>Descuenta 1 consulta. Rate propio: 1 request cada 30 segundos.</p>
<h2>Buscar por nombre</h2>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" "https://dni-drey.pe2.lol/nombre/JUAN%20PEREZ"
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"resultados": [{"dni": "06282044", "nombre": "JUAN PEREZ EJEMPLO", "anio": "1960"}]}
</code></pre>
<p>Máximo 20 resultados por búsqueda. Descuenta 1 consulta.</p>
<h2>Lotes (batch)</h2>
<pre><code class="language-bash">curl -X POST -H "X-API-Key: TU_TOKEN" -H "Content-Type: application/json" \
-d '{"dnis":["6282044","12345678"]}' https://dni-drey.pe2.lol/jobs
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"job_id": "abc123"}
</code></pre>
<p>Consultar el lote:</p>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" https://dni-drey.pe2.lol/jobs/abc123
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"estado": "listo", "resultados": [{"dni": "06282044", "nombre": "EJEMPLO APELLIDO NOMBRE", "anio": "1960"}]}
</code></pre>
<p>Límite default: 20 DNIs por lote (ampliable por el administrador según tu plan).</p>
<h2>Vincular cuenta (trial)</h2>
<pre><code class="language-bash">curl -X POST -H "Content-Type: application/json" \
-d '{"token_supabase":"TU_JWT"}' https://dni-drey.pe2.lol/vincular
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"api_key": "TU_TOKEN_NUEVO"}
</code></pre>
<p>Crea tu cuenta trial automáticamente: 3 días + 50 consultas.</p>
<h2>Ver tu saldo</h2>
<pre><code class="language-bash">curl -H "X-API-Key: TU_TOKEN" https://dni-drey.pe2.lol/perfil
</code></pre>
<p>Respuesta real:</p>
<pre><code class="language-json">{"expires_at": "2026-10-03", "consultas_restantes": 49}
</code></pre>
<h2>Errores</h2>
<table>
<thead>
<tr>
<th>Código</th>
<th>Significado</th>
</tr>
</thead>
<tbody>
<tr>
<td>401</td>
<td>Sin token o token inválido (<code>X-API-Key</code> faltante o incorrecto)</td>
</tr>
<tr>
<td>403</td>
<td>Membresía vencida o consultas agotadas</td>
</tr>
<tr>
<td>404</td>
<td>DNI no existe (o tabla vacía)</td>
</tr>
<tr>
<td>429</td>
<td>Rate limit: espera 5 s (30 s en <code>/verificar</code>)</td>
</tr>
<tr>
<td>503</td>
<td>Servicio de verificación no disponible, reintenta luego</td>
</tr>
</tbody>
</table>