Opis lokalnego API agenta

​

Bazowy adres URL

http://localhost:5555

​

Dostęp i bezpieczeństwo

• Tylko localhost. Agent nasłuchuje wyłącznie na adresach pętli zwrotnej (127.0.0.1 i ::1). Inne komputery w Twojej sieci nie mogą się z nim połączyć i nie potrzebuje on reguły zapory. Żądanie, które wskazuje inny host niż localhost lub adres pętli zwrotnej, jest odrzucane z kodem 403 Forbidden.
• Jeden wymagany nagłówek. Każde żądanie do trasy zaczynającej się od /api musi zawierać nagłówek X-Omnilinker-Local: 1. Bez niego agent odpowiada 403 Forbidden z pustą treścią. /health nie sprawdza tego nagłówka; wysłanie go tam niczemu nie szkodzi.
• Przeglądarki: tylko Omnilinker. Strona internetowa nie może dodać tego nagłówka, nie pytając najpierw agenta (zapytanie wstępne CORS). Agent zgadza się tylko dla adresu Omnilinkera, https://omnilinker.pl, i jego subdomen, przez HTTPS. Dzięki temu karta Usługa lokalna aplikacji webowej, otwarta w przeglądarce na komputerze agenta, odczytuje API. Żądania z każdej innej strony są odrzucane z kodem 403.
• Brak uwierzytelniania. Programy na komputerze, takie jak aplikacja w zasobniku, PowerShell czy curl, wysyłają nagłówek i nie potrzebują klucza API, hasła ani tokenu.

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/status

​

Konwencje

• Treści żądań i odpowiedzi są w formacie JSON. Nazwy właściwości są w notacji camelCase.
• Czas jest podawany w UTC, w formacie ISO 8601, na przykład 2026-09-27T08:15:02.1234567Z.
• Wartości wyliczeniowe są zwracane jako liczby, a nie nazwy. Tabele na tej stronie podają ich wartości.
• Trasy sterujące zwracają 400 Bad Request z wynikiem polecenia, gdy agent odrzuca polecenie.
• 403 Forbidden z pustą treścią oznacza, że żądanie zostało odrzucone, zanim dotarło do agenta: brakuje nagłówka X-Omnilinker-Local, host to nie localhost albo przeglądarka wysłała je z innej strony.
• Przykłady używają PowerShell. W Windows PowerShell 5.1 curl jest aliasem polecenia Invoke-WebRequest. Aby użyć curl, wpisz curl.exe.

​

Trasy

​

Stan

​

GET /health

Invoke-WebRequest -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/health -UseBasicParsing |
  Select-Object StatusCode, Content

​

GET /api/sync/health

curl -H "X-Omnilinker-Local: 1" http://localhost:5555/api/sync/health

{ "status": "healthy", "timestamp": "2026-09-27T08:15:02.1234567Z" }

​

Status

​

GET /api/sync/status

$status = Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/status
$status | Select-Object state, isConnected, isErpConnected, lastSyncTime, lastError
$status.outbox

{
  "state": 0,
  "isConnected": true,
  "isErpConnected": true,
  "lastSyncTime": "2026-09-27T08:15:02.1234567Z",
  "nextSyncTime": null,
  "errorCount": 0,
  "lastError": null,
  "waitingReason": null,
  "suggestedActions": [],
  "outbox": { "pending": 0, "sent": 245, "failed": 0, "retrying": 0 },
  "entityCounts": {
    "Product": { "total": 240, "synced": 240, "failed": 0, "pending": 0 },
    "Brand": { "total": 5, "synced": 5, "failed": 0, "pending": 0 }
  },
  "version": "<agent version>",
  "updateAvailable": false,
  "updateVersion": null
}

​

GET /api/sync/config

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/config

​

Sterowanie

​

Wynik polecenia

​

POST /api/sync/now

Invoke-RestMethod -Method Post -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/now

curl -X POST -H "X-Omnilinker-Local: 1" http://localhost:5555/api/sync/now

​

POST /api/sync/pause

• Zdarzenia, które już są w kolejce wychodzącej, są nadal wysyłane do Omnilinkera, gdy agent jest wstrzymany.
• Wstrzymanie nie jest zachowywane po ponownym uruchomieniu usługi.

Invoke-RestMethod -Method Post -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/pause

​

POST /api/sync/resume

Invoke-RestMethod -Method Post -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/resume

​

Logi

​

GET /api/sync/logs

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } "http://localhost:5555/api/sync/logs?count=20&level=Warning" |
  Format-Table timestamp, level, category, message

curl -H "X-Omnilinker-Local: 1" "http://localhost:5555/api/sync/logs?count=20&level=Warning"

​

Kolejka wychodząca

​

GET /api/sync/outbox/stats

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/outbox/stats

{ "pending": 5, "sent": 1245, "failed": 0, "retrying": 0 }

​

Weryfikacja hash

​

GET /api/sync/hash/status

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/hash/status

​

GET /api/sync/hash/stats

Invoke-RestMethod -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/hash/stats

​

POST /api/sync/hash/trigger

Invoke-RestMethod -Method Post -Headers @{ "X-Omnilinker-Local" = "1" } http://localhost:5555/api/sync/hash/trigger

​

Potok nazwany

• Kto może się połączyć: SYSTEM, administratorzy i osoby zalogowane na komputerze, przy konsoli albo przez Pulpit zdalny.
• Co mogą zrobić: każdy połączony może odczytać status, logi i ustawienia. Polecenia, które zmieniają agenta, jego bazę danych ERP lub dane logowania albo go wstrzymują, wymagają członka grupy Omnilinker ERP Sync Operators albo administratora, którego aplikacja w zasobniku działa z podwyższonymi uprawnieniami. Pozostali dostają błąd „Only an administrator of this PC can do that.” (kod Pipe:NotAllowed). Zobacz Kto może zmieniać agenta.
• Która usługa: aplikacja w zasobniku rozmawia tylko z usługą Windows. Nie ufa innemu programowi, który otworzy potok o tej samej nazwie.