Przejdź do treści
Oplac

Referencja API

Klienci

Klienci sprzedawcy (cus_).

POST/v1/customersGET/v1/customers/{id}POST/v1/customers/{id}GET/v1/customersDELETE/v1/customers/{id}

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

Klient sprzedawcy (cus_): łączy płatności, subskrypcje i faktury jednej osoby albo firmy. Metody płatności przechowuje dostawca płatności, nie Oplac. Usunięty klient wraca jako {id, object, deleted: true}.

Pola

  • id string wymagane

    Identyfikator klienta.

  • object string wymagane

    Nazwa typu obiektu, zawsze "customer".

  • email string | null
  • name string | null
  • tax_id string | null

    NIP.

  • address object | null
    • line1 string | null
    • line2 string | null
    • city string | null
    • postal_code string | null
    • country string | null

      Kod kraju ISO 3166-1 alpha-2, np. PL.

  • payment_methods array of object

    Zawsze pusta lista: zapisane metody płatności żyją u dostawcy płatności.

  • deleted boolean

    Tylko dla usuniętego klienta.

  • 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.

  • livemode boolean wymagane

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

  • created integer

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

JSON 
{
  "id": "cus_Xy98Zw76Vu54Ts",
  "object": "customer",
  "email": "[email protected]",
  "name": "Anna Nowak",
  "tax_id": null,
  "address": {
    "line1": "ul. Prosta 1",
    "city": "Warszawa",
    "postal_code": "00-001",
    "country": "PL"
  },
  "payment_methods": [],
  "metadata": {
    "crm_id": "7"
  },
  "livemode": false,
  "created": 1760000000
}

Utwórz klienta#

POST /v1/customers

Wszystkie pola opcjonalne. Zdarzenie customer.created.

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

Treść żądania JSON, opcjonalna

  • email string (email)

    Do 190 znaków.

  • name string

    Do 190 znaków.

  • tax_id string

    NIP. Do 20 znaków.

  • address object | string

    Obiekt (line1, line2, city, postal_code, country) albo jeden tekst.

    • line1 string | null
    • line2 string | null
    • city string | null
    • postal_code string | null
    • country string | null

      Kod kraju ISO 3166-1 alpha-2, np. PL.

  • 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 customer.

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/customers \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "name": "Anna Nowak",
  "metadata": {
    "crm_id": "7"
  }
}'
$ch = curl_init('https://oplac.pl/api/v1/customers');
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([
        'email' => '[email protected]',
        'name' => 'Anna Nowak',
        'metadata' => [
            'crm_id' => '7',
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$customer = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    name: 'Anna Nowak',
    metadata: {
      crm_id: '7',
    },
  }),
});
const customer = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/customers",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "email": "[email protected]",
        "name": "Anna Nowak",
        "metadata": {
            "crm_id": "7",
        },
    },
)
customer = res.json()
Odpowiedź HTTP 201 
{
  "id": "cus_Xy98Zw76Vu54Ts",
  "object": "customer",
  "email": "[email protected]",
  "name": "Anna Nowak",
  "tax_id": null,
  "address": {
    "line1": "ul. Prosta 1",
    "city": "Warszawa",
    "postal_code": "00-001",
    "country": "PL"
  },
  "payment_methods": [],
  "metadata": {
    "crm_id": "7"
  },
  "livemode": false,
  "created": 1760000000
}

Pobierz klienta#

GET /v1/customers/{id}

Klient po identyfikatorze; usunięty wraca jako {id, object, deleted: true}.

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator cus_.

Odpowiedź

HTTP 200: obiekt customer.

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/customers/cus_Xy98Zw76Vu54Ts \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$customer = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const customer = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
customer = res.json()
Odpowiedź HTTP 200 
{
  "id": "cus_Xy98Zw76Vu54Ts",
  "object": "customer",
  "email": "[email protected]",
  "name": "Anna Nowak",
  "tax_id": null,
  "address": {
    "line1": "ul. Prosta 1",
    "city": "Warszawa",
    "postal_code": "00-001",
    "country": "PL"
  },
  "payment_methods": [],
  "metadata": {
    "crm_id": "7"
  },
  "livemode": false,
  "created": 1760000000
}

Zmień klienta#

POST /v1/customers/{id}

Zmiana podanych pól; metadata łączone z zapisanymi. Zdarzenie customer.updated.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator cus_.

Treść żądania JSON, opcjonalna

  • email string (email)

    Do 190 znaków.

  • name string

    Do 190 znaków.

  • tax_id string

    NIP. Do 20 znaków.

  • address object | string

    Obiekt (line1, line2, city, postal_code, country) albo jeden tekst.

    • line1 string | null
    • line2 string | null
    • city string | null
    • postal_code string | null
    • country string | null

      Kod kraju ISO 3166-1 alpha-2, np. PL.

  • 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 customer.

Błędy tej operacji: resource_deleted, 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/customers/cus_Xy98Zw76Vu54Ts \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "name": "Anna Nowak",
  "tax_id": "tekst"
}'
$ch = curl_init('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => '[email protected]',
        'name' => 'Anna Nowak',
        'tax_id' => 'tekst',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$customer = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    name: 'Anna Nowak',
    tax_id: 'tekst',
  }),
});
const customer = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "email": "[email protected]",
        "name": "Anna Nowak",
        "tax_id": "tekst",
    },
)
customer = res.json()
Odpowiedź HTTP 200 
{
  "id": "cus_Xy98Zw76Vu54Ts",
  "object": "customer",
  "email": "[email protected]",
  "name": "Anna Nowak",
  "tax_id": null,
  "address": {
    "line1": "ul. Prosta 1",
    "city": "Warszawa",
    "postal_code": "00-001",
    "country": "PL"
  },
  "payment_methods": [],
  "metadata": {
    "crm_id": "7"
  },
  "livemode": false,
  "created": 1760000000
}

Lista klientów#

GET /v1/customers

Klienci konta w trybie klucza, bez usuniętych.

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
  • email string

    Dokładny adres e-mail (bez względu na wielkość liter).

Odpowiedź

HTTP 200: lista {object: "list", url, has_more, data} z obiektami customer 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/customers?limit=3" \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/customers?limit=3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$customers = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/customers?limit=3', {
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const customers = await res.json();
import requests

res = requests.get(
    "https://oplac.pl/api/v1/customers?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
customers = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_Xy98Zw76Vu54Ts",
      "object": "customer",
      "email": "[email protected]",
      "name": "Anna Nowak",
      "tax_id": null,
      "address": {
        "line1": "ul. Prosta 1",
        "city": "Warszawa",
        "postal_code": "00-001",
        "country": "PL"
      },
      "payment_methods": [],
      "metadata": {
        "crm_id": "7"
      },
      "livemode": false,
      "created": 1760000000
    }
  ]
}

Usuń klienta#

DELETE /v1/customers/{id}

Klient znika z listy i jego dane kontaktowe nie wracają w API; płatności i subskrypcje zachowują odwołanie cus_. Zdarzenie customer.deleted. Powtórne usunięcie też zwraca 200.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator cus_.

Odpowiedź

HTTP 200: obiekt {id, object, deleted: true}; usuniętego obiektu nie da się już zmieniać.

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/customers/cus_Xy98Zw76Vu54Ts \
  -X DELETE \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ"
$ch = curl_init('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_TWOJ_KLUCZ'],
    CURLOPT_RETURNTRANSFER => true,
]);
$deleted = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts', {
  method: 'DELETE',
  headers: {Authorization: 'Bearer sk_test_TWOJ_KLUCZ' },
});
const deleted = await res.json();
import requests

res = requests.delete(
    "https://oplac.pl/api/v1/customers/cus_Xy98Zw76Vu54Ts",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
deleted = res.json()
Odpowiedź HTTP 200 
{
  "id": "cus_Xy98Zw76Vu54Ts",
  "object": "customer",
  "deleted": true,
  "livemode": false
}

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.