Dla deweloperów

1. Uwierzytelnianie i zakresy

Utwórz klucz w Ustawienia → Klucze API (`orb_live_…`). Wysyłaj go jako `Authorization: Bearer …` albo `X-Api-Key`. Klucze są hashowane; plaintext pokazywany jest raz. Limit: do 10 kluczy na konto Scale. Limit zapytań: 60 na minutę na klucz (wspólny dla REST i MCP).
Zakresy są hierarchiczne: read ⊂ write ⊂ action. Read obejmuje GET; write dodaje konfigurację webhooków; action — uruchomienie Monitoringu. Wrażliwe użycie jest audytowane na koncie.

2. REST API v1

Ścieżka bazowa: /api/v1. OpenAPI: /api/v1/openapi.json.
Odczyt: integracje, rozbieżności, alerty Monitoring, wyszukiwanie produktu, podsumowania porównań, status webhooka.
Zapis (zakres `write`): `PUT /api/v1/webhooks` — URL HTTPS, włączenie, rotacja sekretu HMAC.
Akcja (zakres `action`): `POST /api/v1/monitoring/run` — uruchom porównanie Monitoring (opcjonalne `pairId`).

3. Serwer MCP

Zdalny Model Context Protocol pod /api/mcp (Streamable HTTP, odpowiedzi JSON). To samo uwierzytelnianie kluczem API. OAuth — wkrótce.
Tooli: `list_integrations`, `list_mismatches`, `get_monitoring_alerts`, `find_product`, `get_comparison_summary`, `get_webhook_config`, `configure_webhook` (write), `run_monitoring` (action).
`GET /api/mcp` zwraca metadane bez klucza; `POST` obsługuje JSON-RPC (`initialize`, `tools/list`, `tools/call`, `ping`).

Połącz AI — Cursor, Claude, VS Code →

4. Webhooki i zdarzenia

Subskrypcja w ustawieniach Monitoringu albo przez `PUT /api/v1/webhooks` / MCP `configure_webhook`. Orbilyn wysyła POST JSON na Twój HTTPS z nagłówkami `X-Orbilyn-Event` oraz `X-Orbilyn-Signature` (`sha256=` HMAC-SHA256 surowego body).
Zdarzenia: `catalog.duplicate.new`, `catalog.drift.status` (dryf statusu kanałów, np. BaseLinker ↔ Allegro), `sync.failure`, oraz pomocnicze `monitoring.mismatch.new`, `monitoring.alert`, `integration.health.broken`. Body zawsze ma `text` (kompatybilne ze Slack) i `event`.

5. Klienci + llms.txt

Wskaż zdalny konektor MCP / HTTP na `https://app.orbilyn.com/api/mcp` i przekaż nagłówek Bearer (lub X-Api-Key). Preferuj przewodnik Połącz AI dla Cursor, Claude i VS Code. Jeśli host wymaga dziś tylko OAuth — ta ścieżka jest wkrótce; tymczasem użyj REST v1 z tym samym kluczem. Smoke test: POST `initialize`, potem `tools/list`.
Wskaźniki maszynowe: /llms.txt · karta discovery: /.well-known/mcp.json.