Saltar a contenido

Guide: Syncing (carga inicial + incremental)

El patrón recomendado para integrar FarmAPI es:

  1. Carga inicial (bootstrap): snapshot paginado por territorio.
  2. Incremental: changes desde un watermark, con paginación por cursor.
  3. (Opcional) Webhooks: notificación cuando un territorio ha sincronizado, y el cliente hace pull de changes.

1) Carga inicial con snapshot

Para cada territorio permitido por tu API key:

  1. Llama GET /v1/farmacias/snapshot/{territory_code}?limit=...
  2. Guarda items
  3. Si next_cursor no es null, vuelve a llamar con cursor=<next_cursor>
TERR=ES-MD
CURSOR=""
while true; do
  if [ -n "$CURSOR" ]; then
    URL="$FARMAAPI_BASE_URL/v1/farmacias/snapshot/$TERR?limit=1000&cursor=$CURSOR"
  else
    URL="$FARMAAPI_BASE_URL/v1/farmacias/snapshot/$TERR?limit=1000"
  fi
  BODY=$(curl -sS "$URL" -H "X-API-Key: $FARMAAPI_API_KEY")
  NEXT=$(echo "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('next_cursor') or '')")
  [ -z "$NEXT" ] && break
  CURSOR="$NEXT"
done

Note

Si el territorio aún no está cargado, snapshot devuelve 503 con territory_status=not_loaded.

2) Incremental con changes

GET /v1/farmacias/changes devuelve eventos técnicos:

  • operation=upsert: actualiza o inserta el record.
  • operation=delete: elimina la farmacia (por external_id + territory_code).

Watermark recomendado

Persistir:

  • last_cursor (int)
  • since (datetime UTC ISO)

Estrategia simple y robusta:

  1. Inicializa since (por ejemplo, la fecha de tu go-live).
  2. En cada poll:
  3. Llama changes?since=<since>&cursor=<last_cursor>
  4. Procesa items en orden
  5. Actualiza last_cursor = next_cursor (si viene)
  6. Si reinicias el proceso, reanudas con el mismo since y el último cursor persistido.
curl -sS "$FARMAAPI_BASE_URL/v1/farmacias/changes?since=2026-01-01T00:00:00Z&limit=500" \
  -H "X-API-Key: $FARMAAPI_API_KEY"

Filtrado por territorios

Puedes limitar con:

  • territories=ES-MD,ES-AS,...

Si pides territorios fuera del scope:

  • 403

3) Webhooks (pull after push)

El webhook no envía registros uno a uno. Notifica un evento compacto:

  • territory.sync.completed

Tras recibir el webhook, el cliente:

  1. verifica firma
  2. hace pull de changes (o snapshot si es su primer día)

El callback se registra como origin:

  • https://tu-dominio.com

Y FarmAPI llama siempre a:

  • https://tu-dominio.com/.well-known/farmaapi/webhook

Ver: Webhooks.