🔧

API para Desarrolladores

Documentación de la API pública de ReportaVNZLA. Conecta tu plataforma y ayuda a cruzar información para encontrar personas desaparecidas.

🎯 Misión de la API

La API de ReportaVNZLA permite a otras plataformas de búsqueda, organizaciones humanitarias y desarrolladores cruzar datos y sincronizar información sobre personas desaparecidas tras el terremoto de Venezuela 2026.

📥 Importar Datos

Envía registros de personas desde tu plataforma. Nos encargamos de deduplicar.

📤 Exportar Datos

Obtiene registros actualizados para cruzar con tu base de datos.

🔄 Sincronizar

Mantén tus datos actualizados con cambios de estado y nuevas informaciones.

🌐 URL Base

https://reportavnzla.com/api/v1

Todas las respuestas son JSON. La API usa CORS para permitir solicitudes desde cualquier origen.

🔑 Autenticación

La API es pública y gratuita para fines humanitarios. No se requiere autenticación para lecturas. Para escrituras (POST/PATCH), recomendamos incluir un header de identificación:

X-Source: nombre-de-tu-plataforma

⚡ Límites de Uso

OperaciónLímiteNotas
GET (lectura)60 req/minCache: 60s
POST (crear)30 req/minMax 100/batch
PATCH (actualizar)60 req/min
POST /sync10 req/minMax 500/batch

📡 Endpoints

GET/api/v1/personasBuscar personas

Obtiene una lista paginada de personas con filtros avanzados.

Parámetros de Query

ParámetroTipoDescripción
qstringBúsqueda general (nombre, apellido, cédula, ubicación, descripción)
estadostringbuscado | encontrado | fallecido
cedulastringBúsqueda parcial de cédula
nombrestringBúsqueda parcial de nombre
apellidostringBúsqueda parcial de apellido
edad_min / edad_maxintRango de edad
generostringmasculino | femenino
ubicacionstringBúsqueda parcial de ubicación
external_idstringID externo de tu plataforma
pageintPágina (default: 0)
limitintRegistros por página (max: 200, default: 50)
sortstringCampo: created_at, nombre, edad, estado (default: created_at)
orderstringasc | desc (default: desc)

Ejemplo

curl "https://reportavnzla.com/api/v1/personas?q=González&estado=buscado&limit=10"

Respuesta

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "nombre": "María",
      "apellido": "González",
      "cedula": "V-12345678",
      "edad": 35,
      "genero": "femenino",
      "estado": "buscado",
      "ultimaUbicacion": "La Guaira",
      "descripcion": "Última vez vista en...",
      "fotoUrl": "https://...",
      "lat": 10.5,
      "lng": -66.9,
      "externalId": null,
      "reportadoPorNombre": "Juan Pérez",
      "createdAt": "2026-06-25T...",
      "updatedAt": "2026-06-25T..."
    }
  ],
  "pagination": {
    "total": 150,
    "page": 0,
    "limit": 10,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
GET/api/v1/personas/:idObtener persona por ID
curl "https://reportavnzla.com/api/v1/personas/UUID_AQUI"
POST/api/v1/personasRegistrar persona(s)

Crea uno o múltiples registros. Acepta un objeto individual o un array (batch, max 100).

Body (single)

{
  "nombre": "María",
  "apellido": "González",
  "cedula": "V-12345678",
  "edad": 35,
  "genero": "femenino",
  "estado": "buscado",
  "ultima_ubicacion": "La Guaira, sector Catia La Mar",
  "descripcion": "Llevaba ropa roja...",
  "foto_url": "https://ejemplo.com/foto.jpg",
  "lat": 10.5,
  "lng": -66.9,
  "external_id": "tu-plataforma-12345",
  "reportado_por_nombre": "Juan Pérez",
  "reportado_por_telefono": "+58 412 1234567"
}

Body (batch)

[
  { "nombre": "Persona 1", "apellido": "Apellido 1", ... },
  { "nombre": "Persona 2", "apellido": "Apellido 2", ... }
]

💡 external_id es clave para deduplicación cruzada. Usa el ID de tu plataforma.

PATCH/api/v1/personas/:idActualizar persona
curl -X PATCH "https://reportavnzla.com/api/v1/personas/UUID" \
  -H "Content-Type: application/json" \
  -d '{"estado": "encontrado", "notas": "Encontrada en hospital"}'
GET/api/v1/statsEstadísticas
{
  "success": true,
  "data": {
    "total": 15000,
    "buscados": 14000,
    "encontrados": 800,
    "fallecidos": 200
  }
}
POST/api/v1/syncSincronizar datos entre plataformas

Envía un batch de registros desde tu plataforma. Los registros con external_id existente se actualizan automáticamente (deduplicación). Nuevos registros se insertan.

{
  "source": "venezuelatebusca.com",
  "url": "https://venezuelatebusca.com",
  "persons": [
    {
      "nombre": "Juan",
      "apellido": "Pérez",
      "external_id": "vtb-abc123",
      "cedula": "V-12345678",
      "edad": 30,
      "estado": "buscado",
      "ultima_ubicacion": "Caracas",
      "foto_url": "https://..."
    }
  ]
}

Respuesta

{
  "success": true,
  "source": "venezuelatebusca.com",
  "syncResult": {
    "inserted": 15,
    "updated": 3,
    "skipped": 2,
    "totalProcessed": 20
  }
}
GET/api/v1/syncExportar datos para sincronización

Exporta registros modificados desde una fecha. Los campos usan snake_case para compatibilidad.

curl "https://reportavnzla.com/api/v1/sync?since=2026-06-25T00:00:00Z&limit=500"
ParámetroTipoDescripción
sinceISO dateSolo registros actualizados después de esta fecha
estadostringFiltrar por estado
limitintMax registros (default: 100, max: 1000)

🤖 Notificaciones y bots (Telegram / Webhook)

Conecta tu propio bot de Telegram (o cualquier servicio por webhook) para recibir avisos de personas nuevas y consultar datos en tiempo real. Dos modos: pull (tu bot consulta el feed) y push (te avisamos nosotros).

1) Feed para bots (pull)

Tu bot consulta periódicamente y usa serverTime como próximo since para traer solo lo nuevo.

GET /api/v1/feed?since=2026-06-01T00:00:00Z&q=perez&estado=buscado&limit=50
{ "success": true, "serverTime": "...", "count": 2, "data": [ { "id": "...", "nombre": "...", "apellido": "...", "estado": "buscado", "ultimaUbicacion": "...", "fotoUrl": "...", "url": "https://reportavnzla.com/persona/<id>" } ] }

1b) Centros de acopio y estructuras

Datos de ayuda (centros de acopio y edificaciones afectadas) con coordenadas, para mapas u otras integraciones.

GET /api/v1/recursos?tipo=centro_acopio · GET /api/v1/recursos?tipo=estructura

2) Suscripción push (Telegram o Webhook)

Registra una suscripción con filtros; te enviaremos las personas nuevas que coincidan. Guarda el token que devuelve para gestionarla.

POST /api/v1/subscriptions # Telegram: { "canal": "telegram", "telegramBotToken": "123:ABC", "telegramChatId": "12345678", "q": "perez", "estado": "buscado" } # Webhook (recomendado, no compartes el token del bot): { "canal": "webhook", "webhookUrl": "https://tu-servidor/hook", "estado": "buscado" } → { "success": true, "id": "...", "token": "..." } DELETE /api/v1/subscriptions?id=<id>&token=<token> # desactivar

🔒 Por seguridad, el modo webhook es preferible: tú envías a tu Telegram desde tu servidor y no compartes el token de tu bot. El push corre por un proceso programado (cada ~10 min).

3) Probar tu bot de Telegram

Verifica que tu bot y chat funcionan (crea el bot con @BotFathery obtén tu chatId).

POST /api/v1/telegram { "botToken": "123:ABC", "chatId": "12345678", "message": "Hola desde ReportaVNZLA" }

🛠️ Guía de Integración

1. JavaScript / Fetch

// Buscar personas
const res = await fetch(
  'https://reportavnzla.com/api/v1/personas?q=González&estado=buscado'
)
const { data, pagination } = await res.json()

// Registrar persona desde tu plataforma
await fetch('https://reportavnzla.com/api/v1/personas', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Source': 'mi-plataforma.com' },
  body: JSON.stringify({
    nombre: 'María',
    apellido: 'González',
    cedula: 'V-12345678',
    estado: 'buscado',
    external_id: 'mi-plat-123',
    foto_url: 'https://mi-plataforma.com/fotos/maria.jpg'
  })
})

// Sincronizar batch
await fetch('https://reportavnzla.com/api/v1/sync', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source: 'mi-plataforma.com',
    url: 'https://mi-plataforma.com',
    persons: [
      { nombre: 'Juan', apellido: 'Pérez', external_id: 'jp-001', ... },
      { nombre: 'Ana', apellido: 'López', external_id: 'al-002', ... },
    ]
  })
})

2. Python

import requests

# Buscar
res = requests.get('https://reportavnzla.com/api/v1/personas', params={
    'q': 'González',
    'estado': 'buscado',
    'limit': 10
})
data = res.json()

# Exportar datos actualizados
res = requests.get('https://reportavnzla.com/api/v1/sync', params={
    'since': '2026-06-25T00:00:00Z',
    'limit': 1000
})
for person in res.json()['data']:
    print(f"{person['nombre']} {person['apellido']} - {person['estado']}")

3. cURL

# Buscar
curl "https://reportavnzla.com/api/v1/personas?q=Pérez&limit=5"

# Crear persona
curl -X POST "https://reportavnzla.com/api/v1/personas" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Juan","apellido":"Pérez","estado":"buscado"}'

# Sincronizar
curl -X POST "https://reportavnzla.com/api/v1/sync" \
  -H "Content-Type: application/json" \
  -d '{"source":"mi-plataforma","persons":[...]}'

4. Centros de acopio y estructuras (bidireccional)

GET para recibir y POST para enviar — un objeto o un lote { items: [...] } (máx. 500). Asíncrono, CORS abierto, anti-spam, deduplicado e idempotente por externalId. Usa ?since= (epoch ms o ISO) + ?page=/?pageSize= para sincronización incremental.

cURL — recibir / enviar
# Recibir estructuras nuevas desde una fecha
curl "https://reportavnzla.com/api/v1/recursos?tipo=estructura&since=1782000000000&pageSize=200"

# Recibir centros de acopio
curl "https://reportavnzla.com/api/v1/recursos?tipo=centro_acopio"

# Enviar (lote): 1 centro + 1 estructura
curl -X POST "https://reportavnzla.com/api/v1/recursos" \
  -H "Content-Type: application/json" \
  -H "X-Api-Source: mi-plataforma.org" \
  -d '{"items":[
    {"tipo":"centro_acopio","nombre":"Iglesia X","direccion":"Catia La Mar",
     "recibe":"agua, alimentos","contacto":"0412-0000000","lat":10.6,"lng":-67.03},
    {"tipo":"estructura","nombre":"Edificio Y","ciudad":"La Guaira",
     "nivelDanio":"severo","externalId":"miorg-001","lat":10.6,"lng":-66.93}
  ]}'
JavaScript — recibir / enviar
// Recibir (paginado incremental)
const r = await fetch(
  'https://reportavnzla.com/api/v1/recursos?tipo=estructura&since=' + lastSync
)
const { data, nextPage } = await r.json()

// Enviar lote
await fetch('https://reportavnzla.com/api/v1/recursos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Source': 'mi-plataforma.org',
  },
  body: JSON.stringify({ items: [
    { tipo: 'centro_acopio', nombre: 'Iglesia X', recibe: 'agua' },
    { tipo: 'estructura', nombre: 'Edificio Y', nivelDanio: 'severo',
      externalId: 'miorg-001' },
  ]}),
})
Python
import requests
B = 'https://reportavnzla.com/api/v1/recursos'

# Recibir estructuras (sincronización incremental)
out = requests.get(B, params={'tipo': 'estructura', 'since': last_sync}).json()
for e in out['data']:
    print(e['nombre'], e.get('nivelDanio'))

# Enviar lote (recibir+enviar simultáneo entre plataformas)
requests.post(B, headers={'X-Api-Source': 'mi-plataforma.org'}, json={'items': [
    {'tipo': 'centro_acopio', 'nombre': 'Iglesia X', 'recibe': 'agua'},
    {'tipo': 'estructura', 'nombre': 'Edificio Y', 'nivelDanio': 'severo',
     'externalId': 'miorg-001'},
]})
PHP
<?php
$B = 'https://reportavnzla.com/api/v1/recursos';

// Recibir
$data = json_decode(file_get_contents($B . '?tipo=centro_acopio'), true);

// Enviar lote
$ch = curl_init($B);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Api-Source: mi-plataforma.org'],
  CURLOPT_POSTFIELDS => json_encode(['items' => [
    ['tipo' => 'estructura', 'nombre' => 'Edificio Y', 'nivelDanio' => 'severo', 'externalId' => 'miorg-001'],
  ]]),
  CURLOPT_RETURNTRANSFER => true,
]);
$resp = json_decode(curl_exec($ch), true);
Compartir datos entre plataformas (enviar y recibir a la vez): programa un job que cada N minutos haga GET …?since=<última sync> para recibir lo nuevo y un POST {items} para enviar lo tuyo. El externalId evita duplicados en ambos sentidos, así que es seguro ejecutarlo en bucle.

🤝 Estrategia Cruzada

La API está diseñada para que múltiples plataformas compartan datos sin duplicación:

  1. Cada plataforma usa external_id con su propio formato (ej: vtb-abc123, dtv-456)
  2. Al sincronizar, los registros con el mismo external_id se actualizan en vez de duplicarse
  3. Usá GET /api/v1/sync?since=... para obtener solo los cambios recientes
  4. Actualizá estados (buscado → encontrado) desde cualquier plataforma
  5. Las fotos se referencian por URL — no hay transferencia de archivos

📊 Fuentes de Datos

ReportaVNZLA agrega datos de múltiples fuentes. Puedes contribuir la tuya:

venezuelatebusca.comRegistro público principal de desaparecidos (~21,000)✅ Sincronizado
desaparecidosterremotovenezuela.comPlataforma adicional (~45,700 registros)✅ Sincronizado
Tu plataforma¿Tienes datos? Conéctate vía API⬜ Disponible

📞 Contacto para Desarrolladores

¿Necesitas ayuda con la integración? ¿Tienes una plataforma con datos que quieras compartir?