Referencja API

Referencja REST API

Każdy zasób i każda operacja REST API Oplac, generowane z tej samej specyfikacji OpenAPI, którą serwuje /api/openapi.json. Adres API: https://oplac.pl/api, wersja 2026-10-03.

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

Zasoby#

Konto 1 operacja Stan konta i modułów dla klucza. get /v1/account Płatności 5 operacji Płatność z hostowaną stroną płatności, adresem powrotu i webhookiem. post /v1/payments get /v1/payments/{id} post /v1/payments/{id} get /v1/payments post /v1/payments/{id}/cancel Linki do płatności 4 operacje Stałe adresy do zapłaty, z kodem QR. post /v1/payment_links get /v1/payment_links/{id} post /v1/payment_links/{id} get /v1/payment_links Zwroty 4 operacje Zwroty całościowe i częściowe. post /v1/refunds get /v1/refunds/{id} post /v1/refunds/{id} get /v1/refunds Klienci 5 operacji Klienci sprzedawcy (cus_). post /v1/customers get /v1/customers/{id} post /v1/customers/{id} get /v1/customers delete /v1/customers/{id} Plany 4 operacje Plany abonamentowe (moduł Bill). post /v1/plans get /v1/plans/{id} post /v1/plans/{id} get /v1/plans Kupony 4 operacje Rabaty do subskrypcji. post /v1/coupons get /v1/coupons/{id} get /v1/coupons delete /v1/coupons/{id} Subskrypcje 5 operacji Płatności cykliczne z okresem próbnym, proracją i Recover. post /v1/subscriptions get /v1/subscriptions/{id} post /v1/subscriptions/{id} get /v1/subscriptions post /v1/subscriptions/{id}/cancel Faktury 4 operacje Faktury VAT z terminem, po opłaceniu i korekty, KSeF. post /v1/invoices get /v1/invoices/{id} post /v1/invoices/{id} get /v1/invoices Produkty 4 operacje Produkty do sprzedaży bez sklepu (Bez programisty). post /v1/products get /v1/products/{id} post /v1/products/{id} get /v1/products Strony sprzedaży 4 operacje Publiczne strony zakupu w marce sprzedawcy, z kodem QR i przyciskiem. post /v1/checkout_pages get /v1/checkout_pages/{id} post /v1/checkout_pages/{id} get /v1/checkout_pages Portal klienta 2 operacje Jednorazowe adresy wejścia do portalu klienta końcowego. post /v1/portal_sessions get /v1/portal_sessions/{id} Zdarzenia 3 operacje Historia zdarzeń i ponowna wysyłka. get /v1/events/{id} get /v1/events post /v1/events/{id}/resend Webhooki 5 operacji Adres webhooka i sekret podpisu. post /v1/webhook_endpoints get /v1/webhook_endpoints/{id} post /v1/webhook_endpoints/{id} get /v1/webhook_endpoints delete /v1/webhook_endpoints/{id} Piaskownica 4 operacje Pomocnicy testowi dla klucza sk_test_. post /v1/test_helpers/webhooks post /v1/test_helpers/payments/{id}/confirm post /v1/test_helpers/subscriptions/{id}/confirm post /v1/test_helpers/subscriptions/{id}/renew

Wspólne nagłówki#

W żądaniu

AuthorizationBearer sk_test_... albo sk_live_...wymagane
Klucz API z panelu. Tryb (piaskownica albo produkcja) wynika z klucza. Więcej w Uwierzytelnianie i tryby.
Content-Typeapplication/json
Treść żądań POST jako JSON.
Idempotency-Keystring, 1 do 255 znaków
Przy POST i DELETE. Powtórka z tym samym kluczem i treścią w ciągu 24 godzin zwraca pierwszy wynik. Więcej w Idempotencja.
Oplac-Versiondata RRRR-MM-DD
Wersja API; domyślnie najnowsza (2026-10-03). Więcej w Wersje API i zmiany.

W odpowiedzi

X-Request-Idstring
Identyfikator żądania req_, ten sam co w treści błędu.
Oplac-Versionstring
Użyta wersja API.
X-RateLimit-Limitinteger
Limit żądań na sekundę dla konta i trybu.
X-RateLimit-Remaininginteger
Ile żądań zostało w bieżącej sekundzie.
X-RateLimit-Resetinteger
Za ile sekund okno się odnawia.
Retry-Afterinteger
Przy 429: za ile sekund ponowić.
Idempotent-Replayedstring
Odpowiedź odtworzona z zapisu idempotencji.
Original-Requeststring
Przy odtworzeniu: X-Request-Id pierwszego żądania.

Odpowiedzi#

Pojedynczy obiekt wraca wprost w treści, lista w kopercie {object: "list", url, has_more, data}. Każda odpowiedź 4xx i 5xx (także 404 nieznanej trasy, 405, 429 i 500) to ten sam obiekt błędu, nigdy strona HTML. Kody HTTP w użyciu:

HTTP	Kiedy
200	Pobranie, zmiana, lista, anulowanie, usunięcie.
201	Utworzono nowy obiekt.
400	Żądanie do poprawy: brak pola, zła wartość, zły nagłówek. Pole `param` mówi które.
401	Brak albo nieważny klucz API.
402	Konto bez podpiętego dostawcy płatności (tylko produkcja).
403	Moduł, waluta albo pomocnik testowy poza planem lub trybem klucza.
404	Nie ma obiektu w tym koncie i trybie albo nie ma takiej trasy.
405	Trasa nie obsługuje tej metody; nagłówek `Allow` wymienia dozwolone.
409	Żądanie z tym `Idempotency-Key` jest właśnie przetwarzane.
422	Stan obiektu nie pozwala na operację (np. zwrot płatności nieopłaconej).
429	Limit zapytań; odczekaj `Retry-After` sekund.
500, 502	Błąd po stronie Oplac albo dostawcy płatności. Ponów; przy powtórce podaj `request_id`.

Pełny katalog 41 kodów błędów z kotwicami, do których prowadzi doc_url: Błędy, katalog kodów.

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