Przejdź do treści
Oplac

Referencja API

Produkty

Produkty do sprzedaży bez sklepu (Bez programisty).

POST/v1/productsGET/v1/products/{id}POST/v1/products/{id}GET/v1/products

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

Obiekt product#

Produkt (prod_) sprzedawany na stronie sprzedaży bez własnego sklepu: jednorazowy (one_time) albo subskrypcja (recurring) z planem Bill, który obciąża klienta co miesiąc albo co rok. Cena, waluta i typ są stałe po utworzeniu. Zdjęcie dodaje się w panelu; API zwraca image_url.

Pola

  • id string wymagane

    Identyfikator produktu.

  • object string wymagane

    Nazwa typu obiektu, zawsze "product".

  • name string wymagane

    Do 120 znaków.

  • description string | null

    Zwykły tekst bez HTML, pokazywany na stronie sprzedaży. Do 2000 znaków.

  • image_url string | null

    Zdjęcie produktu (JPEG, PNG albo WebP) wgrane w panelu; null bez zdjęcia.

  • amount integer wymagane

    Cena w groszach.

  • currency string wymagane
    PLNEURUSD
  • type string wymagane

    one_time: płatność jednorazowa (Accept); recurring: subskrypcja (Bill, od planu Firma).

    one_timerecurring
  • interval string | null

    Okres subskrypcji; null dla one_time.

    monthyear
  • plan string | null

    Plan Bill (plan_) utworzony razem z produktem recurring; pełny obiekt przy expand[]=plan.

  • active boolean wymagane

    Wyłączony produkt nie przyjmuje zakupów na żadnej stronie sprzedaży.

  • metadata object wymagane

    Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.

  • livemode boolean wymagane

    true dla obiektów produkcyjnych (klucz sk_live_), false dla piaskownicy (sk_test_).

  • created integer wymagane

    Chwila utworzenia jako znacznik czasu Unix (sekundy, UTC).

JSON 
{
  "id": "prod_Ab12Cd34Ef56Gh",
  "object": "product",
  "name": "Kurs fotografii online",
  "description": "Dostęp do nagrań na rok.",
  "image_url": "https://oplac.pl/media/produkt/prod_Ab12Cd34Ef56Gh",
  "amount": 12900,
  "currency": "PLN",
  "type": "one_time",
  "interval": null,
  "plan": null,
  "active": true,
  "metadata": {
    "sku": "KURS-1"
  },
  "livemode": false,
  "created": 1760000000
}

Utwórz produkt#

POST /v1/products

Produkt do sprzedaży bez sklepu: nazwa, opis, cena i typ. type recurring tworzy razem z produktem plan Bill (interval month albo year, opcjonalnie trial_days) i wymaga planu Firma. Zdjęcie dodaje się w panelu, w zakładce Strony sprzedaży. Po utworzeniu produktu utwórz dla niego stronę sprzedaży (POST /v1/checkout_pages).

Nagłówki opcjonalne: Oplac-Version, Idempotency-Key

Treść żądania JSON

  • name string wymagane

    Od 2 do 120 znaków.

  • description string

    Zwykły tekst bez HTML. Do 2000 znaków.

  • amount integer wymagane

    Cena w groszach. Od 100 do 999999999.

  • currency string wymagane

    Waluta. EUR i USD od planu Skala.

    PLNEURUSD
  • type string

    Domyślnie 'one_time'.

    one_timerecurring
  • interval string

    Wymagane przy type recurring.

    monthyear
  • trial_days integer

    Dni okresu próbnego subskrypcji. Domyślnie 0. Od 0 do 365.

  • metadata object

    Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.

Odpowiedź

HTTP 201: obiekt product.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, module_not_in_plan, currency_not_in_plan, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl https://oplac.pl/api/v1/products \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Kurs fotografii online",
  "description": "Dostęp do nagrań na rok.",
  "amount": 12900,
  "currency": "PLN",
  "metadata": {
    "sku": "KURS-1"
  }
}'
$ch = curl_init('https://oplac.pl/api/v1/products');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Kurs fotografii online',
        'description' => 'Dostęp do nagrań na rok.',
        'amount' => 12900,
        'currency' => 'PLN',
        'metadata' => [
            'sku' => 'KURS-1',
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$product = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/products', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Kurs fotografii online',
    description: 'Dostęp do nagrań na rok.',
    amount: 12900,
    currency: 'PLN',
    metadata: {
      sku: 'KURS-1',
    },
  }),
});
const product = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/products",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "name": "Kurs fotografii online",
        "description": "Dostęp do nagrań na rok.",
        "amount": 12900,
        "currency": "PLN",
        "metadata": {
            "sku": "KURS-1",
        },
    },
)
product = res.json()
Odpowiedź HTTP 201 
{
  "id": "prod_Ab12Cd34Ef56Gh",
  "object": "product",
  "name": "Kurs fotografii online",
  "description": "Dostęp do nagrań na rok.",
  "image_url": "https://oplac.pl/media/produkt/prod_Ab12Cd34Ef56Gh",
  "amount": 12900,
  "currency": "PLN",
  "type": "one_time",
  "interval": null,
  "plan": null,
  "active": true,
  "metadata": {
    "sku": "KURS-1"
  },
  "livemode": false,
  "created": 1760000000
}

Pobierz produkt#

GET /v1/products/{id}

Produkt po identyfikatorze.

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator prod_.

Parametry zapytania

  • expand[] array of string

    Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: plan.

    plan

Odpowiedź

HTTP 200: obiekt product.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, resource_missing, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$product = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const product = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
product = res.json()
Odpowiedź HTTP 200 
{
  "id": "prod_Ab12Cd34Ef56Gh",
  "object": "product",
  "name": "Kurs fotografii online",
  "description": "Dostęp do nagrań na rok.",
  "image_url": "https://oplac.pl/media/produkt/prod_Ab12Cd34Ef56Gh",
  "amount": 12900,
  "currency": "PLN",
  "type": "one_time",
  "interval": null,
  "plan": null,
  "active": true,
  "metadata": {
    "sku": "KURS-1"
  },
  "livemode": false,
  "created": 1760000000
}

Zmień produkt#

POST /v1/products/{id}

name, description, active (wyłączony produkt nie przyjmuje zakupów), metadata. Próba zmiany amount, currency, type albo interval to 400 parameter_invalid: utwórz nowy produkt.

Nagłówki opcjonalne: Oplac-Version, Idempotency-Key

Parametry ścieżki

  • id string wymagane

    Identyfikator prod_.

Treść żądania JSON, opcjonalna

  • name string

    Od 2 do 120 znaków.

  • description string

    Do 2000 znaków.

  • active boolean
  • metadata object

    Własne pary klucz: wartość (do 50 kluczy, klucz do 40 znaków, wartość tekstowa do 500 znaków). Wracają w obiekcie i w zdarzeniach webhooka. Przy zmianie nowe klucze dochodzą do zapisanych, pusta wartość usuwa klucz, pusty tekst zamiast obiektu czyści wszystko.

Odpowiedź

HTTP 200: obiekt product.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, resource_missing, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
$ch = curl_init('https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'active' => false,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$product = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    active: false,
  }),
});
const product = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/products/prod_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "active": False,
    },
)
product = res.json()
Odpowiedź HTTP 200 
{
  "id": "prod_Ab12Cd34Ef56Gh",
  "object": "product",
  "name": "Kurs fotografii online",
  "description": "Dostęp do nagrań na rok.",
  "image_url": "https://oplac.pl/media/produkt/prod_Ab12Cd34Ef56Gh",
  "amount": 12900,
  "currency": "PLN",
  "type": "one_time",
  "interval": null,
  "plan": null,
  "active": true,
  "metadata": {
    "sku": "KURS-1"
  },
  "livemode": false,
  "created": 1760000000
}

Lista produktów#

GET /v1/products

Produkty konta w trybie klucza.

Nagłówki opcjonalne: Oplac-Version

Parametry zapytania

  • limit integer

    Liczba obiektów na stronie (1 do 100). Domyślnie 10. Od 1 do 100.

  • starting_after string

    Identyfikator obiektu; zwraca starsze od niego (następna strona).

  • ending_before string

    Identyfikator obiektu; zwraca nowsze od niego (poprzednia strona). Nie łączyć ze starting_after.

  • created object

    Filtr po chwili utworzenia (Unix): created[gte]=1760000000.

    • gt integer
    • gte integer
    • lt integer
    • lte integer
  • active boolean

    Tylko włączone albo wyłączone.

  • type string

    Filtr typu.

    one_timerecurring
  • expand[] array of string

    Pola do rozwinięcia w pełny obiekt (na liście z przedrostkiem data. albo bez). Rozwijalne: plan.

    plan

Odpowiedź

HTTP 200: lista {object: "list", url, has_more, data} z obiektami product od najnowszego. Stronicowanie kursorem opisuje przewodnik.

Błędy tej operacji: parameter_missing, parameter_invalid, metadata_invalid, expand_invalid, api_version_invalid, idempotency_key_reused, idempotency_key_invalid, api_key_invalid, rate_limited, api_error . Każdy błąd to ten sam obiekt error, opisany w przewodniku Błędy. 

curl "https://oplac.pl/api/v1/products?limit=3" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/products?limit=3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$products = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/products?limit=3', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const products = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/products?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
products = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/products",
  "has_more": false,
  "data": [
    {
      "id": "prod_Ab12Cd34Ef56Gh",
      "object": "product",
      "name": "Kurs fotografii online",
      "description": "Dostęp do nagrań na rok.",
      "image_url": "https://oplac.pl/media/produkt/prod_Ab12Cd34Ef56Gh",
      "amount": 12900,
      "currency": "PLN",
      "type": "one_time",
      "interval": null,
      "plan": null,
      "active": true,
      "metadata": {
        "sku": "KURS-1"
      },
      "livemode": false,
      "created": 1760000000
    }
  ]
}

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

BLIK, karty, subskrypcje i KSeF w jednym panelu.