Podstawy API

Limity zapytań

API przyjmuje 100 żądań na sekundę w produkcji i 25 na sekundę w piaskownicy, licząc osobno dla każdego konta i trybu. Każda odpowiedź mówi, ile zostało. Po przekroczeniu dostajesz 429 rate_limited z nagłówkiem Retry-After i ponawiasz po wskazanym czasie.

Klucz testowy w przykładach

Wklej klucz sk_test_ z panelu (zakładka Deweloperzy), a każdy przykład będzie gotowy do uruchomienia. Klucz zostaje w tej karcie przeglądarki, nie wysyłamy go nigdzie.

Przykłady używają Twojego klucza testowego. Produkcyjnego klucza nie przyjmujemy.

Tryb testowy

Ile i jak liczone#

Tryb	Limit	Liczony dla
produkcja (`sk_live_`)	100 żądań na sekundę	konto
piaskownica (`sk_test_`)	25 żądań na sekundę	konto
żądanie bez ważnego klucza	25 żądań na sekundę	adres IP

produkcja (sk_live_)

Limit: 100 żądań na sekundę
Liczony dla: konto

piaskownica (sk_test_)

Limit: 25 żądań na sekundę
Liczony dla: konto

żądanie bez ważnego klucza

Limit: 25 żądań na sekundę
Liczony dla: adres IP

Okno trwa sekundę i odnawia się w całości. Limit dotyczy wszystkich tras razem, także GET. Webhooki wychodzące nie zużywają limitu, ale Twój odbiorca musi odpowiedzieć w ciągu 10 sekund.

Nagłówki w każdej odpowiedzi#

Nagłówek	Znaczenie
`X-RateLimit-Limit`	limit żądań na sekundę dla konta i trybu
`X-RateLimit-Remaining`	ile żądań zostało w bieżącym oknie
`X-RateLimit-Reset`	za ile sekund okno się odnawia
`Retry-After`	tylko przy 429: za ile sekund ponowić

Nagłówki w każdej odpowiedzi

curl -i "https://oplac.pl/api/v1/payments?limit=1" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"

$ch = curl_init('https://oplac.pl/api/v1/payments?limit=1');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADERFUNCTION => function ($ch, $linia) use (&$zostalo) {
        if (stripos($linia, 'X-RateLimit-Remaining:') === 0) {
            $zostalo = (int) trim(substr($linia, 22));
        }
        return strlen($linia);
    },
]);
$payments = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/payments?limit=1', {
  headers: { Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const zostalo = Number(res.headers.get('X-RateLimit-Remaining'));
const payments = await res.json();

import requests

res = requests.get(
    "https://oplac.pl/api/v1/payments?limit=1",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
zostalo = int(res.headers["X-RateLimit-Remaining"])
payments = res.json()

Odpowiedź

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Przekroczony limit 25 zapytań na sekundę. Ponów żądanie za 1 s.",
    "param": null,
    "doc_url": "https://oplac.pl/docs/bledy#rate_limited",
    "request_id": "req_7mK2pQ9rT4vX1bN8cD3fG6hJ"
  }
}

Jak ponawiać#

Przy 429 odczekaj Retry-After sekund (zwykle 1) i ponów to samo żądanie. Dla POST użyj tego samego Idempotency-Key: odpowiedzi 429 nie są zapamiętywane, więc ponowienie wykona się normalnie.
Przy masowych operacjach (import klientów, wysyłka linków) rozłóż żądania w czasie zamiast wysyłać je równolegle; 100 na sekundę to 6 000 na minutę.
Zamiast odpytywać GET /v1/payments/{id} w pętli o stan płatności, odbieraj webhooki. Odpytywanie zużywa limit i zawsze jest wolniejsze od zdarzenia.
Do pobierania historii używaj filtrów created[gte] i stronicowania kursorem, nie pełnych list w pętli.

Potrzebujesz wyższego limitu w produkcji? Napisz na [email protected] z opisem obciążenia; limity w planach Platforma i Enterprise ustalamy indywidualnie.

Powiązane

Błędy/docs/bledy Idempotencja/docs/idempotencja Stronicowanie/docs/stronicowanie Webhooki/docs/webhooki

Klucz testowy dostajesz od razu po zapisie

Adres e-mail, kod z maila i piaskownica z kodami BLIK. Produkcję włączasz sam w panelu: plan, dostawca płatności, klucz sk_live_. Wolisz, żeby wdrożenie w sklepie zrobił nasz zespół? To też jest za darmo.

Zamów integrację za darmo