Dokumentacja API v1

Endpointy, autoryzacja, parametry, odpowiedzi i limity publicznego API Apresly. Specyfikacja OpenAPI gotowa do importu.

Adres i autoryzacja

Adres bazowy: https://app.apresly.com/api/public/v1. Wszystkie trzy operacje wymagają nagłówka Authorization: Bearer <YOUR_API_KEY>. Klucz tworzysz w ustawieniach API. Używaj go wyłącznie po stronie serwera lub w prywatnym połączeniu automatyzacji.

Pobierz OpenAPI 3.1 do importu w Postmanie lub narzędziu generującym klienta. Plik na tej stronie wskazuje pełny adres produkcyjny. Specyfikacja bezpośrednio z API używa ścieżki względnej i nie wymaga klucza.

Lista kampanii

GET /campaigns

Zwraca kampanie konta w kolejności rosnących ID. Bez filtra obejmuje szkice i kampanie opublikowane.

Parametr query	Wartość	Znaczenie
`limit`	1-100, domyślnie 50	Liczba kampanii na stronie
`afterId`	Dodatnia liczba całkowita	ID z `nextAfterId` poprzedniej odpowiedzi
`isDraft`	`true` lub `false`	`false`: opublikowane, `true`: szkice

curl --fail-with-body "https://app.apresly.com/api/public/v1/campaigns?isDraft=false&limit=50" \
  -H "Authorization: Bearer $APRESLY_API_KEY"

{
  "items": [
    {
      "id": 42,
      "name": "Post-purchase upsell",
      "type": {
        "id": 1,
        "name": "Campaign type"
      },
      "isDraft": false
    }
  ],
  "nextAfterId": null
}

Odpowiedź 200 zawiera items oraz nextAfterId. Każda kampania ma id, name, type (id i name) oraz isDraft. Gdy nextAfterId jest null, to ostatnia strona. W przeciwnym razie wywołaj np. /campaigns?isDraft=false&limit=50&afterId=42, używając otrzymanego kursora.

Rejestracja leada

POST /campaigns/{campaignId}/leads

campaignId to dodatnie ID kampanii należącej do konta klucza. Kampania musi być opublikowana. Wysyłaj Content-Type: application/json i poniższe pola, bez dodatkowych właściwości.

Pole JSON	Wymagane	Wartość
`email`	Tak	Poprawny adres, maks. 254 znaki, bez spacji na początku i końcu
`language`	Nie	`en` albo `pl`, domyślnie `en`; język obrazu licznika

curl --fail-with-body -X POST "https://app.apresly.com/api/public/v1/campaigns/42/leads" \
  -H "Authorization: Bearer $APRESLY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"email":"[email protected]","language":"pl"}'

201 oznacza nowego logicznego leada, 200 istniejącego leada. Szkic zwraca 409 / CAMPAIGN_NOT_PUBLISHED bez rejestracji. Zachowaj pisownię, wielkość liter i aliasy + e-maila między integracjami, to tożsamość używana przez kampanię. Nie wysyłaj deadline, clientId ani adresu IP.

Odczyt istniejącej oferty

POST /campaigns/{campaignId}/leads/lookup

Wymaga tego samego JSON i nagłówków co rejestracja. Zwraca 200, ale bez pola created. Nie rejestruje leada, nie aktywuje ani nie odnawia licznika. POST pozwala nie umieszczać adresu e-mail w URL żądania. Autoryzacja, limity i historia żądań nadal obowiązują.

curl --fail-with-body -X POST "https://app.apresly.com/api/public/v1/campaigns/42/leads/lookup" \
  -H "Authorization: Bearer $APRESLY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"email":"[email protected]","language":"pl"}'

Brak leada daje 404 / LEAD_NOT_FOUND. Można otrzymać wygasły termin. Historyczny lead w szkicu zwraca CAMPAIGN_NOT_PUBLISHED w ostrzeżeniach, bez linków i licznika.

Pola odpowiedzi

Poniżej ilustracyjna odpowiedź rejestracji, z kampanii bez stron oferty i licznika mailowego. Daty i ID są przykładowe.

{
  "campaignId": 42,
  "email": "[email protected]",
  "registeredAt": "2026-09-12T12:00:00.000Z",
  "deadline": "2026-09-14T12:00:00.000Z",
  "timeZone": "Europe/Warsaw",
  "offerLinks": [],
  "mailTimerUrl": null,
  "warnings": [
    "NO_OFFER_PAGES",
    "NO_MAIL_TIMER"
  ],
  "created": true
}

Pole	Znaczenie
`campaignId`	ID kampanii.
`email`	Adres użyty w żądaniu.
`registeredAt`	Pierwsza zachowana rejestracja lub aktywacja, ISO 8601 w UTC. Nie czas odpowiedzi.
`deadline`	Termin z mechanizmu kampanii w UTC albo null, jeśli go nie ustalono.
`timeZone`	Strefa czasowa kampanii, np. Europe/Warsaw.
`offerLinks`	Tablica stron posortowana po pageId. Może być pusta.
`offerLinks[].pageId`	ID strony, użyj do wyboru właściwej oferty.
`offerLinks[].pageUrl`	Skonfigurowany adres strony.
`offerLinks[].url`	Spersonalizowany link CTA. Ten adres wstaw do przycisku.
`mailTimerUrl`	Adres obrazu licznika mailowego albo null.
`warnings`	Lista ostrzeżeń o brakujących zasobach. Zobacz poradnik rozwiązywania problemów.
`created`	Tylko rejestracja. true, gdy wcześniej nie było identyfikowalnego leada.

Zasady kampanii i linków

API stosuje istniejące ustawienia terminu, resetu i cykli kampanii. Powtórzenie rejestracji nie wydłuża terminu, gdy reset jest wyłączony. created opisuje tożsamość leada, nie uruchomienie nowego cyklu ani jednokrotną wysyłkę wiadomości.

API nie wysyła e-maili. Nie zastępuje widgetu: zachowanie HIDE, ZERO lub REDIRECT po wygaśnięciu egzekwują istniejące strony i zainstalowany widget. Wygenerowanie URL nie aktywuje oferty; otwarcie CTA lub obrazu licznika podlega standardowym zasadom kampanii.

Spersonalizowane linki można przekazać dalej. Zawierają tożsamość odbiorcy i nie są tajnymi, jednorazowymi tokenami dostępu. Zmiana stron lub ustawień kampanii może zmienić linki w kolejnych odpowiedziach. Unieważnienie klucza nie unieważnia wcześniej otrzymanych linków.

Limity i ponowienia

Domyślnie 120 autoryzowanych żądań na minutę UTC na konto, wspólnie dla wszystkich kluczy. Limit jest konfigurowalny po stronie usługi.
JSON maks. 16 KiB. Nieznane pola i parametry query są odrzucane.
Listy: 1-100 pozycji, domyślnie 50.
Po 429 odczekaj liczbę sekund z nagłówka Retry-After.
Timeout i 503 ponawiaj z rosnącym opóźnieniem oraz ograniczoną liczbą prób.
Utracona odpowiedź nie oznacza wycofania rejestracji. Deduplikuj zdarzenia i wysyłkę w swoim systemie, nie opieraj ich wyłącznie na created.

Błędy i diagnostyka

Błędy zawierają status, code, message i requestId. Odpowiedzi API zawierają także nagłówek X-Request-Id oraz Cache-Control: no-store. Nie zapisuj kluczy, e-maili ani spersonalizowanych linków w logach.

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid API key",
  "requestId": "00000000-0000-4000-8000-000000000001"
}

HTTP	Kod
400	`INVALID_JSON`, `INVALID_CURSOR`
401	`UNAUTHORIZED`
403	`ACCOUNT_SUSPENDED`
404	`CAMPAIGN_NOT_FOUND`, `LEAD_NOT_FOUND`, `NOT_FOUND`
409	`CAMPAIGN_NOT_PUBLISHED`
413	`PAYLOAD_TOO_LARGE`
415	`UNSUPPORTED_MEDIA_TYPE`
422	`VALIDATION_ERROR`
429	`RATE_LIMITED`
500	`INTERNAL_ERROR`
503	`SERVICE_UNAVAILABLE`

Sposoby rozwiązania błędów i ostrzeżeń. Historia żądań w panelu pokazuje domyślnie ostatnie 7 dni bez payloadów, e-maili i sekretów. Awaria zapisu historii może pozostawić luki.