Venezuela SolidariaDirectorio de ayuda · Sismos 2026
← Volver al directorio

API de federación

API pública y estable para que las apps de la red de directorios de ayuda consulten y aporten recursos. La lectura es pública; la creación requiere una clave (X-API-Key) y los recursos entran como pendientes de moderación antes de publicarse.

Base URLhttps://api.venezuelasolidaria.com
FormatoJSON
CORSabierto en /api/v1/*
Errores{ "error": "<mensaje>" }

Descubrimiento

GET/api/v1

Metadatos de la API (nombre, versión, categorías y endpoints).

curl https://api.venezuelasolidaria.com/api/v1
{
  "name": "Venezuela Solidaria",
  "version": "1",
  "provider": "Venezuela Solidaria",
  "categories": ["donaciones", "paginas", "emergencia", "quedadas"],
  "endpoints": {
    "list": "GET /api/v1/resources",
    "detail": "GET /api/v1/resources/{id}",
    "create": "POST /api/v1/resources (header X-API-Key)"
  }
}

Consultar recursos

GET/api/v1/resources

Lista los recursos publicados, paginada.

ParámetroTipoDescripción
categorystringFiltra por categoría (ver vocabulario). Omite o todos para todas.
countrystringFiltra por país (texto exacto como aparece en el recurso).
qstringBúsqueda de texto en título, descripción, ciudad y país.
sinceISO-8601Solo recursos con updated_at >= since (sincronización incremental).
limitintMáximo por página. Por defecto 50, máximo 200.
offsetintDesplazamiento para paginar. Por defecto 0.

Respuesta

{
  "items": [ /* recursos, ver esquema */ ],
  "pagination": {
    "limit": 50, "offset": 0, "total": 132,
    "returned": 50, "has_more": true
  }
}

Ejemplos

# Primeras 20 donaciones
curl "https://api.venezuelasolidaria.com/api/v1/resources?category=donaciones&limit=20"

# Sincronización incremental: solo lo cambiado desde la última vez
curl "https://api.venezuelasolidaria.com/api/v1/resources?since=2026-06-01T00:00:00Z"

# Paginar
curl "https://api.venezuelasolidaria.com/api/v1/resources?limit=50&offset=50"

El + de un offset horario en ISO debe ir codificado como %2B, o usa el sufijo Z para UTC.

GET/api/v1/resources/{id}

Un recurso publicado por su id. Devuelve 404 si no existe o no está publicado.

Esquema de un recurso

{
  "id": "029ea6f2f4c75138",
  "category": "donaciones",
  "title": "Cruz Roja Venezolana — Emergencia",
  "description": "Donaciones para atención médica y refugio.",
  "url": "https://...",            // null si es solo teléfono
  "phone": "+58...",               // null si es URL
  "city": "Caracas",
  "country": "Venezuela",
  "lat": 10.49, "lng": -66.87,     // pueden ser null
  "start_date": "2026-06-26",      // fecha del evento (o null)
  "end_date": null,                // fecha de fin (o null)
  "image": "https://...",          // o null
  "verified": true,                // revisado por el equipo
  "source": "Venezuela Solidaria", // origen (o el socio que lo aportó)
  "link": "https://www.venezuelasolidaria.com/recurso/029ea6f2f4c75138",
  "created_at": "2026-06-26T12:35:38+00:00",
  "updated_at": "2026-06-26T13:41:16+00:00"
}

Vocabulario de category

Crear un recurso

POST/api/v1/resourcesrequiere X-API-Key

Crea un recurso que entra como pendiente de revisión. Autenticación por header X-API-Key (la entrega el equipo de Venezuela Solidaria). Límite: 30/min · 300/hora.

CampoReq.Descripción
categorysíUna de las categorías del vocabulario.
titlesíNombre / título (máx. 280).
url*Enlace http(s). *Obligatorio url o phone.
phone*Teléfono de contacto. *Obligatorio url o phone.
descriptionnoTexto (máx. 2000).
city / countrynoUbicación.
start_date / end_datenoYYYY-MM-DD (fin >= inicio).
imagenoURL http(s) de una imagen.
lat / lngnoCoordenadas exactas; si no, se geocodifica.

Ejemplo

curl -X POST https://api.venezuelasolidaria.com/api/v1/resources \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vs_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "category": "donaciones",
    "title": "Recaudación para El Tigre",
    "url": "https://ejemplo.org/campana",
    "description": "Campaña vecinal para reconstrucción de viviendas.",
    "city": "El Tigre",
    "country": "Venezuela"
  }'

Respuestas

  • 201 { "id": "...", "status": "pending", "message": "..." }
  • 400 validación (categoría/fecha/imagen inválida, faltan campos).
  • 401 falta o es inválida la X-API-Key.
  • 409 duplicado (la URL o el teléfono ya existen).
  • 429 límite de peticiones superado.

Notas para integradores

← Volver al directorio