# API Pública — Venezuela Te Busca

> Documentación extendida: [05-api.md](05-api.md) · Índice general: [README.md](README.md)

Base de datos unificada para que desarrolladores e iniciativas solidarias **lean y escriban** en el mismo registro de personas desaparecidas, SOS y edificios afectados.

## URLs

| Recurso | URL |
|---------|-----|
| **API** | `https://n0xnahm83j.execute-api.sa-east-1.amazonaws.com` |
| **OpenAPI (JSON)** | `GET /v1/docs` |
| **Health** | `GET /v1/health` (sin clave) |
| **Portal web** | https://d2s8ujt32olfq2.cloudfront.net/docs/index.html |

---

## Autenticación

Todas las rutas `/v1/*` (excepto `/v1/health` y `/v1/docs`) requieren:

```http
X-API-Key: vtb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

| Permiso | Qué permite |
|---------|-------------|
| `read` | Consultar registros, metadata, stats |
| `write` | Crear y actualizar registros, subir fotos |

Solicitar clave al operador o ver [07-scripts-y-operaciones.md](07-scripts-y-operaciones.md).

---

## Lectura: S3 (recomendado) vs API

```bash
# Rápido — miles de usuarios (sin API key)
curl https://d2s8ujt32olfq2.cloudfront.net/data/desaparecidos/listing-recent.json
curl https://d2s8ujt32olfq2.cloudfront.net/data/desaparecidos/listing.json

# API — filtros, apps, sync
curl "https://API/v1/desaparecidos?limit=24&q=maria" -H "X-API-Key: ..."
```

---

## Endpoints resumidos

Ver tabla completa en [05-api.md](05-api.md).

| Método | Ruta | Auth |
|--------|------|------|
| GET | `/v1/health`, `/v1/docs` | No |
| GET | `/v1/desaparecidos`, `/v1/sos`, `/v1/edificios` | read |
| POST | `/v1/desaparecidos`, `/v1/avisos`, `/v1/sos`, `/v1/edificios` | write |
| PATCH | `/v1/desaparecidos/{id}`, `/v1/sos/{id}`, `/v1/edificios/{id}` | write |
| POST | `/v1/upload-url` | write |
| GET | `/v1/data-urls`, `/v1/stats`, `/v1/metadata` | read |

---

## Ejemplo: registrar persona

```bash
curl -X POST "https://n0xnahm83j.execute-api.sa-east-1.amazonaws.com/v1/desaparecidos" \
  -H "X-API-Key: vtb_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María",
    "apellido": "González",
    "ultima_ubicacion": "Cumaná",
    "reportado_por_nombre": "Tu App",
    "reportado_por_telefono": "+58412...",
    "fuente": "https://tu-sitio.org"
  }'
```

---

## Buenas prácticas

1. Lectura masiva → S3 `listing.json`
2. Escritura → API `/v1/` con `fuente`
3. No duplicar registros — buscar antes de crear
4. No exponer API keys en JavaScript del navegador

Documentación completa: **[docs/05-api.md](05-api.md)**