Przykłady end-to-end

Kilka kompletnych scenariuszy „od klucza do wyniku". Wszystkie zakładają klucz API w zmiennej środowiskowej:

export GEO_KEY="geo_twoj_klucz"   # panel → Klucze API

1. Pierwszy request — podsumowanie widoczności

curl -s -H "X-API-Key: $GEO_KEY" \
  "https://geoplatform.pl/v1/visibility/summary?days=30"

Dostaniesz SoV, sentyment i pozycję per platforma za ostatnie 30 dni — te same liczby, które widzisz na dashboardzie.

2. Dzienny trend SoV do arkusza

curl -s -H "X-API-Key: $GEO_KEY" \
  "https://geoplatform.pl/v1/visibility/timeseries?days=90" \
  | python3 -c "
import csv, json, sys
rows = json.load(sys.stdin)['data']
w = csv.DictWriter(sys.stdout, fieldnames=rows[0].keys()); w.writeheader(); w.writerows(rows)
" > sov_trend.csv

3. Cały katalog produktów (paginacja kursorowa)

CURSOR=""
while :; do
  RESP=$(curl -s -H "X-API-Key: $GEO_KEY" \
    "https://geoplatform.pl/v1/products?limit=100&cursor=$CURSOR")
  echo "$RESP" | python3 -c "import sys,json; [print(p['name']) for p in json.load(sys.stdin)['data']]"
  CURSOR=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['meta'].get('next_cursor') or '')")
  [ -z "$CURSOR" ] && break
done

Kursor jest nieprzejrzysty — przekazuj go bez zmian, pętla kończy się, gdy next_cursor jest puste.

4. Wysyłka zamówienia (atrybucja)

Wymaga scope orders:write. Upsert jest idempotentny po external_id — wyślij to samo zamówienie ponownie (np. ze statusem returned), aby je zaktualizować:

curl -s -X POST -H "X-API-Key: $GEO_KEY" -H "Content-Type: application/json" \
  https://geoplatform.pl/v1/orders -d '{
    "external_id": "ORD-2026-1234",
    "ordered_at": "2026-07-22T10:15:00Z",
    "status": "paid",
    "total_value": 349.99,
    "currency": "PLN",
    "utm_source": "chatgpt.com",
    "items": [
      {"product_external_id": "SKU-001", "name": "Buty trailowe X", "quantity": 1,
       "unit_price": 349.99, "total_price": 349.99}
    ]
  }'

product_external_id zgodny z identyfikatorami katalogu spina zamówienie z przychodem per SKU. Do zrzutów historycznych użyj POST /v1/orders/batch (do 500 zamówień; błędne lądują w errors z indeksem, reszta przechodzi).

5. Odbiornik webhooków z weryfikacją podpisu

Minimalny odbiornik (FastAPI), który przyjmuje zdarzenie i weryfikuje X-GEO-Signature — szczegóły formatu w Webhooki:

import hashlib, hmac, os
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRET = os.environ["GEO_WEBHOOK_SECRET"]

@app.post("/geo-webhook")
async def geo_webhook(request: Request, x_geo_signature: str = Header("")):
    body = await request.body()  # surowe bajty — przed parsowaniem!
    expected = "sha256=" + hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, x_geo_signature):
        raise HTTPException(status_code=401)
    event = await request.json()
    # odłóż do kolejki i odpowiedz szybko (limit 10 s)
    print(event["event"], event["data"])
    return {"ok": True}

Dobre praktyki

• Obserwuj nagłówki X-RateLimit-* i zwalniaj przy 429 (przegląd).
• Do masowych zrzutów użyj Eksportu danych lub BigQuery Sync — API służy do odczytów bieżących i automatyzacji.