Podstawy API

Uwierzytelnianie i tryby

Każde żądanie do API uwierzytelnia klucz tajny w nagłówku Authorization: Bearer <klucz>. Klucz mówi też, w którym trybie pracujesz: sk_test_ to piaskownica, sk_live_ to produkcja. Nie ma osobnych adresów ani przełączników, a obiekty obu trybów są od siebie całkowicie oddzielone.

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 Authorization#

Klucz przesyłasz w nagłówku Authorization ze schematem Bearer. API przyjmuje wyłącznie HTTPS. Żądanie bez nagłówka, z kluczem odwołanym, z literówką albo z konta bez aktywnego planu dla danego trybu kończy się 401 api_key_invalid z komunikatem, co poprawić. Klucz nie wędruje nigdzie poza serwer: w bazie Oplac zapisany jest tylko jego skrót SHA-256 i cztery ostatnie znaki.

Nagłówek Authorization

curl https://oplac.pl/api/v1/account \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"

$ch = curl_init('https://oplac.pl/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OPLAC_SECRET_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
$account = json_decode(curl_exec($ch), true);

const res = await fetch('https://oplac.pl/api/v1/account', {
  headers: { Authorization: `Bearer ${process.env.OPLAC_SECRET_KEY}` },
});
const account = await res.json();

import os
import requests

res = requests.get(
    "https://oplac.pl/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['OPLAC_SECRET_KEY']}"},
)
account = res.json()

Odpowiedź

HTTP/1.1 401 Unauthorized
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "Podaj klucz API w nagłówku Authorization: Bearer sk_test_... albo sk_live_...",
    "param": null,
    "doc_url": "https://oplac.pl/docs/bledy#api_key_invalid",
    "request_id": "req_7mK2pQ9rT4vX1bN8cD3fG6hJ"
  }
}

Rodzaje kluczy#

Klucz	Przedrostek	Tryb	Gdzie go dostajesz
tajny testowy	`sk_test_`	piaskownica, bez ruchu pieniędzy	panel, zakładka Deweloperzy, od razu po zapisie
tajny produkcyjny	`sk_live_`	produkcja przez operatora płatności	panel, po wyborze planu i podpięciu operatora

tajny testowy

Przedrostek: sk_test_
Tryb: piaskownica, bez ruchu pieniędzy
Gdzie go dostajesz: panel, zakładka Deweloperzy, od razu po zapisie

tajny produkcyjny

Przedrostek: sk_live_
Tryb: produkcja przez operatora płatności
Gdzie go dostajesz: panel, po wyborze planu i podpięciu operatora

Klucz ma 48 znaków: przedrostek i 40 losowych znaków. Pełną wartość widzisz tylko raz, przy utworzeniu. Utwórz nowy klucz w panelu wydaje nowy i natychmiast unieważnia poprzedni tego samego trybu, więc rotację zrób w dwóch krokach: wygeneruj klucz, podmień w konfiguracji, wdroż. Jeden klucz na tryb i konto; osoby z zespołu korzystają z tego samego klucza konta, a ich czynności w panelu są w logu audytu.

Tryb testowy i produkcyjny#

Tryb wynika z klucza i jest zapisany w każdym obiekcie polem livemode. Klucz sk_test_ widzi tylko obiekty testowe, sk_live_ tylko produkcyjne; żądanie o obiekt z drugiego trybu kończy się 404 resource_missing, tak samo jak o obiekt, który nie istnieje. Osobne dla trybów są też adres i sekret webhooka, klucze idempotencji i liczniki limitów.

	`sk_test_`	`sk_live_`
Strona płatności (`checkout_url`)	strona Oplac z kodami BLIK i przyciskami wyniku	strona operatora płatności Twojego konta
Pieniądze	brak	prawdziwe, rozliczane przez operatora
Pomocnicy `/v1/test_helpers`	działają	`403 test_helpers_live_mode`
Limit zapytań	25 na sekundę	100 na sekundę
Wymagania	konto po zapisie (demo 14 dni) albo dowolny plan	plan z cennika i podpięty operator płatności
Webhook	adres testowy	adres produkcyjny

Strona płatności (checkout_url)

sk_test_: strona Oplac z kodami BLIK i przyciskami wyniku
sk_live_: strona operatora płatności Twojego konta

Pieniądze

sk_test_: brak
sk_live_: prawdziwe, rozliczane przez operatora

Pomocnicy /v1/test_helpers

sk_test_: działają
sk_live_: 403 test_helpers_live_mode

Limit zapytań

sk_test_: 25 na sekundę
sk_live_: 100 na sekundę

Wymagania

sk_test_: konto po zapisie (demo 14 dni) albo dowolny plan
sk_live_: plan z cennika i podpięty operator płatności

Webhook

sk_test_: adres testowy
sk_live_: adres produkcyjny

Jak przechowywać klucz#

Klucz trzymaj w zmiennej środowiskowej albo w menedżerze sekretów serwera. Nigdy w repozytorium, w kodzie frontu, w aplikacji mobilnej ani w logach.
Żądania wysyłaj tylko z serwera. Przeglądarka klienta widzi wyłącznie checkout_url.
Logując żądania, maskuj nagłówek Authorization. Do diagnozy wystarczy X-Request-Id z odpowiedzi.
Podejrzewasz wyciek? W panelu kliknij Utwórz nowy klucz: stary przestaje działać od razu. Panel pokazuje końcówkę klucza, żeby dało się rozpoznać, który jest w konfiguracji.
Panel Oplac logowania chroni kodem z maila (i SSO SAML w planie Platforma), a klucz operatora płatności oraz sekrety webhooków są w bazie zaszyfrowane kluczem aplikacji.

Sprawdzenie konta: GET /v1/account#

Dobre pierwsze wywołanie po wygenerowaniu klucza. Zwraca plan, listę modułów, dostępne waluty, charges_enabled (czy w tym trybie przechodzą płatności), provider_connected (czy produkcja ma operatora) i webhook_configured (czy ten tryb ma adres webhooka). W piaskownicy charges_enabled jest true zawsze; w produkcji dopiero po podpięciu operatora i opłaceniu planu.

Powiązane

Szybki start/docs/szybki-start Błędy/docs/bledy Limity zapytań/docs/limity Konto w referencji API/docs/api/konto

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