Wysyłaj ogłoszenia do Seeki przez API.

Uzyskaj klucz API

Dostęp do Agency Import API wymaga aktywnej subskrypcji agencji w Seeki. Każda subskrypcja obejmuje jeden klucz API powiązany z kontem agencji.

Zasubskrybuj na stronie dla agentów, aby rozpocząć.

Uwierzytelnianie

Każde żądanie musi zawierać Twój klucz API jako token Bearer w nagłówku Authorization.

Authorization: Bearer seeki_live_your_key_here

Klucze rozpoczynające się od seeki_live_ to klucze produkcyjne. Klucze stagingowe zaczynają się od seeki_test_. Nie są wymienne pomiędzy środowiskami.

Twój pierwszy import

Wyślij żądanie POST na /v1/listings z treścią JSON zawierającą tablicę listings. Każdy element reprezentuje jedną nieruchomość.

curl -X POST https://ingest.seeki.eu/v1/listings \
  -H "Authorization: Bearer seeki_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "listings": [
      {
        "external_id": "crm-listing-00123",
        "listing_type": "SELL",
        "real_estate_type": "APARTMENT",
        "price": 320000,
        "currency": "EUR",
        "address": {
          "street": "Wenceslas Square 1",
          "city": "Prague",
          "country_code": "CZ",
          "postal_code": "11000"
        },
        "name": "Sunny 2-bedroom apartment, Wenceslas Square",
        "floorage": 65
      }
    ]
  }'

Pomyślnie przetworzona partia zwraca HTTP 200 z tablicami accepted i rejected:

{
  "accepted": [
    { "external_id": "crm-listing-00123", "import_item_id": "uuid-…" }
  ],
  "rejected": []
}

Struktura żądania

Główny obiekt żądania to { listings: [...] }. Wymagane pola dla każdego ogłoszenia:

Pełny schemat ze wszystkimi opcjonalnymi polami znajdziesz w interaktywna dokumentacja API.

Struktura odpowiedzi i błędy

Endpoint /v1/listings zawsze zwraca HTTP 200 OK, o ile samo żądanie jest poprawnie sformułowane (poprawny JSON, prawidłowy nagłówek autoryzacji, mieszczący się w limitach rozmiaru). Błędy poszczególnych ogłoszeń są raportowane wewnątrz tablicy rejected — nie jako kody błędów HTTP.

Każdy element w rejected zawiera external_id, error_code i komunikat czytelny dla człowieka. Błędy na poziomie partii (nieprawidłowa autoryzacja, zbyt duża zawartość) zwracają status HTTP inny niż 200 z polem error_code na najwyższym poziomie.

Kody błędów

Kody na poziomie partii zwracają błędy HTTP. Kody pojedynczych pozycji pojawiają się w tablicy rejected w odpowiedzi 200.

Idempotentność / ponowny import

Re-posting a listing with the same external_id updates the existing record — it does not create a duplicate. The listing’s TTL is refreshed on every successful import.

Wewnętrznie każda pozycja importu jest mapowana na Cloudflare Workflow z ID:

agency-{agency_id}-{external_id}

Wygaśnięcie ogłoszenia

Każde zaimportowane ogłoszenie ma TTL wynoszące 60 dni od ostatniego udanego importu. Po wygaśnięciu TTL ogłoszenie jest automatycznie wycofywane z publikacji przez codzienne zadanie cron.

Aby utrzymać ogłoszenie aktywne bezterminowo, importuj je ponownie (nawet z identycznymi danymi) przed upływem 60-dniowego okna. Zalecanym wzorcem jest wdrożenie nocnej resynchronizacji aktywnych ogłoszeń.

Status i ponawianie

Użyj GET /v1/import-items/{import_item_id}/status, aby odpytać stan przetwarzania pojedynczej pozycji. Identyfikator import_item_id jest zwracany w tablicy accepted oryginalnej odpowiedzi POST.

curl https://ingest.seeki.eu/v1/import-items/{import_item_id}/status \
  -H "Authorization: Bearer seeki_live_your_key_here"

{
  "import_item_id": "uuid-…",
  "external_id": "crm-listing-00123",
  "status": "completed",
  "listing_id": "uuid-listing"
}

Jeśli pozycja zakończy się stanem INFRA_LOST lub INFRA_QUEUE_REJECTED, ponownie umieść ją w kolejce bez wysyłania całej partii:

curl -X POST https://ingest.seeki.eu/v1/import-items/{import_item_id}/retry \
  -H "Authorization: Bearer seeki_live_your_key_here"

Limity

• →Rozmiar treści: maksymalnie 25 MB na żądanie.
• →Liczba elementów na żądanie: maksymalnie 5 000. Dziel większe partie.
• →Obecnie nie obowiązuje limit QPS. Bardzo duże skoki ruchu mogą zostać automatycznie ograniczone; rozłóż synchronizacje o dużej objętości na wiele żądań.

Wdrożenie produkcyjne

Istnieją dwa odrębne środowiska. Klucze API są przypisane do środowiska — klucz produkcyjny nie zadziała w środowisku stagingowym i odwrotnie.

Wszystkie endpointy (/listings, /import-items/{id}/status, /import-items/{id}/retry) są identyczne w obu środowiskach.