Podstawy API

Wersje API i polityka zmian

Wersja API to data, przesyłana w nagłówku Oplac-Version. Dziś jest jedna wersja: 2026-10-03. Zmiany zgodne wstecz (nowe pola, nowe trasy, nowe typy zdarzeń) wchodzą bez zmiany wersji. Zmiana, która mogłaby zepsuć działającą integrację, dostanie nową datę, a dotychczasowa wersja pozostanie dostępna przez nagłówek.

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

Nagłówek Oplac-Version#

Bez nagłówka żądanie jest obsługiwane w najnowszej wersji. Z nagłówkiem Oplac-Version: 2026-10-03 przypinasz integrację do konkretnej wersji; nieznana data to 400 api_version_invalid z listą dostępnych wersji. Każda odpowiedź ma nagłówek Oplac-Version z wersją, w której została przygotowana, a każde zdarzenie webhooka pole api_version.

Zalecenie: wysyłaj nagłówek zawsze, nawet dziś, z datą, na której integrację testowałeś. Gdy pojawi się nowa wersja, Twój kod dalej dostanie stare odpowiedzi, a migrację zrobisz w wybranym momencie, zmieniając jedną stałą.

Nagłówek Oplac-Version

curl https://oplac.pl/api/v1/account \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Oplac-Version: 2026-10-03"

$ch = curl_init('https://oplac.pl/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ', 'Oplac-Version: 2026-10-03'],
    CURLOPT_RETURNTRANSFER => true,
]);
$account = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/account', {
  headers: { Authorization: 'Bearer sk_test_TWOJ_KLUCZ', 'Oplac-Version': '2026-10-03' },
});
const account = await res.json();

import requests

res = requests.get(
    "https://oplac.pl/api/v1/account",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ", "Oplac-Version": "2026-10-03"},
)
account = res.json()

Odpowiedź

HTTP/1.1 200 OK
Oplac-Version: 2026-10-03
X-Request-Id: req_7mK2pQ9rT4vX1bN8cD3fG6hJ
{
  "id": "acct_Ab12Cd34Ef56Gh",
  "object": "account",
  "plan": "firma",
  "livemode": false
}

Co nie zmienia wersji#

Pisz integrację tak, żeby poniższe zmiany jej nie zepsuły. To standardowa lista zmian zgodnych wstecz.

Nowe pola w istniejących obiektach i nowe parametry opcjonalne w żądaniach.
Nowe trasy i nowe zasoby.
Nowe typy zdarzeń webhooków (nieznany typ pomijaj zamiast zgłaszać błąd) i nowe pola w obiekcie event.
Nowe wartości w polach wyliczeniowych, które z natury rosną: failure_code, decline_code, ksef_status.
Nowe kody błędów w obrębie istniejących klas type; obsługa po type zostaje poprawna.
Zmiana treści komunikatów message, kolejności pól w JSON, długości identyfikatorów.

Co dostaje nową wersję#

Usunięcie albo zmiana nazwy pola, parametru lub trasy.
Zmiana typu pola (np. liczba na tekst) albo znaczenia istniejącej wartości.
Zmiana zestawu wartości status obiektu w sposób, który łamie dotychczasowe przejścia.
Zmiana formatu podpisu webhooka albo struktury obiektu event.

Nowa wersja ma datę i wpis w tej dokumentacji z listą różnic i instrukcją migracji. Poprzednie wersje pozostają dostępne przez nagłówek co najmniej 12 miesięcy od ogłoszenia następnej, a specyfikacja OpenAPI pod /api/openapi.json zawsze opisuje wersję najnowszą.

Historia wersji#

Wersja	Zmiany
2026-10-03	Pierwsza wersja REST API v1: jeden obiekt błędu z `doc_url` i `request_id`, obiekty z `object`, `livemode`, `created` i `metadata`, stronicowanie kursorem, `expand[]`, idempotencja z `Idempotent-Replayed`, zdarzenia z `api_version` i stanem doręczenia, adres webhooka przez API, pomocnicy testowi piaskownicy

Powiązane

Konwencje/docs/konwencje Błędy/docs/bledy Zdarzenia/docs/zdarzenia Referencja API/docs/api

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