API pública | SOS Mi Gente

Antes de empezar

Necesitas una llave. La emite a mano el administrador de la plataforma, una por organización. Escribe a hola@sosmigente.com contando quién eres, qué vas a construir y qué recursos necesitas.

La única excepción es el catálogo, que se lee sin llave: es el vocabulario, y hace falta poder mirarlo antes de decidir si integrarse.

La dirección base es https://api.sosmigente.com/publica/v1. Ábrela en el navegador y te dice qué recursos hay y cómo autenticarte. La versión va en la ruta: cuando cambie la forma de una respuesta, será bajo /v2 y /v1 seguirá funcionando.

Desde el navegador también. Esta API responde a cualquier origen, así que un mapa o un tablero puede llamarla directamente desde el navegador de quien lo mire, sin montar un servidor intermedio. El ETag queda legible desde JavaScript.

Cómo se manda la llave

curl https://api.sosmigente.com/publica/v1/necesidades \
  -H "Authorization: Bearer smg_tu_llave_aqui"

Nunca la pongas en la dirección como parámetro: ahí queda escrita en los registros de todos los intermediarios del camino.

Primero el catálogo

Este es el paso que la mayoría se salta y luego cuesta caro. Tu «Cobija» y la nuestra tienen que ser el mismo artículo, o los datos no se pueden cruzar con nada.

GET /publica/v1/catalogo        sin llave

{
  "categorias": [ { "codigo": "abrigo", "nombre": "Ropa y abrigo" }, … ],
  "articulos":  [ { "id": "9f3c…", "nombre": "Cobija",
                    "unidad": "unidades", "categoria": "abrigo" }, … ]
}

Mapea tu vocabulario contra esa lista una vez. Después, cada necesidad y cada línea de inventario traen el articulo_id y ya sabes qué es sin adivinar.

Los recursos

GET /ciudades

Dónde hay operación, cuántas necesidades abiertas y cuántos centros.

GET /necesidades

Lo que hace falta. Qué, cuánto se pidió, cuánto falta, en qué zona y qué organizaciones se comprometieron.

`ciudad`	id de ciudad del catálogo de ciudades
`categoria`	código de categoría
`desde`	fecha ISO 8601: solo lo que cambió después
`cursor`	el `siguiente_cursor` de la respuesta anterior
`limite`	hasta 500, por defecto 100

GET /centros

Dónde recibir donaciones, con horario, teléfono y punto en el mapa. Cada centro trae su confianza y una frase que la explica. Muéstrala. Servir el nombre sin ella convierte tu plataforma en un aval que nosotros no dimos.

GET /inventario

Lo que hay disponible, nunca el total: lo reservado ya tiene dueño, y mostrarlo mandaría a alguien a pedir lo que no está.

Por defecto viene sumado por ciudad y artículo. El detalle por centro (?detalle=true) necesita un permiso aparte en la llave, porque decir «este centro tiene 500 cobijas» es decirle a alguien dónde ir.

Bajar solo lo que cambió

Dos cosas que ahorran trabajo a los dos lados.

ETag. Cada respuesta trae uno. Devuélvelo en If-None-Match y si no cambió nada recibes un 304 sin cuerpo.

curl https://api.sosmigente.com/publica/v1/necesidades \
  -H "Authorization: Bearer smg_…" \
  -H 'If-None-Match: "a3f9…"'

Cursor. Las necesidades vienen paginadas por cursor y no por número de página. Con páginas, una necesidad nueva empuja a todas las demás y quien va por la página 3 se salta una fila sin enterarse.

GET /necesidades?limite=100
  → { "necesidades": […], "siguiente_cursor": 4821, "hay_mas": true }
GET /necesidades?limite=100&cursor=4821

Errores

Códigos HTTP de verdad, y un cuerpo con dos campos: error para tu programa, que no cambia nunca, y mensaje para la persona que esté depurando.

`400`	un parámetro no vale: fecha mal escrita, límite fuera de rango
`401`	falta la llave, o no sirve
`403`	la llave está revocada, o no incluye ese recurso
`404`	esa ruta no existe, o esa ciudad o ese centro no existen
`405`	usaste otro método: todo aquí es `GET`
`429`	pasaste el límite por minuto; trae `reintentar_en_segundos` y la cabecera `Retry-After`

Todos traen los mismos dos campos, incluida una ruta mal escrita. No hay una segunda forma de error que haya que aprender aparte.

{
  "error": "limite_alcanzado",
  "mensaje": "Llegaste al límite de 60 peticiones por minuto.",
  "reintentar_en_segundos": 23,
  "documentacion": "https://sosmigente.com/api.html"
}

Lo que esta API no te va a dar

Ninguna persona. De una necesidad no sale el teléfono, ni la dirección exacta, ni el nombre de quien la publicó, ni siquiera abreviado. El tablero acorta el nombre a «Ana L.» porque un vecino puede reconocer a otro y eso a veces ayuda; una plataforma tercera no reconoce a nadie y no necesita ni eso. Lo que sí sale con nombre es la organización que se comprometió: esa visibilidad es la que impide que dos grupos hagan el mismo viaje.

Ni el punto de una entrega. La coordenada de una entrega es la casa de una familia.

Ni lo bloqueado. Una necesidad que alguien fue a verificar y reportó como no real no sale por aquí.

Si estás construyendo algo que necesita contactar a las personas directamente, esto no es lo que buscas: escríbenos y hablamos.