Przejdź do treści
Oplac

Referencja API

Faktury

Faktury VAT z terminem, po opłaceniu i korekty, KSeF.

POST/v1/invoicesGET/v1/invoices/{id}POST/v1/invoices/{id}GET/v1/invoices

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

Faktura VAT (inv_). type payable: wystawiona z terminem i własną stroną płatności (moduł Invoices); paid: po opłaceniu płatności albo okresu subskrypcji; credit_note: korekta po zwrocie (kwoty ujemne).

Pola

  • id string wymagane

    Identyfikator faktury.

  • object string wymagane

    Nazwa typu obiektu, zawsze "invoice".

  • number string wymagane

    Numer z serii sprzedawcy.

  • type string wymagane
    payablepaidcredit_note
  • corrects string | null

    Faktura pierwotna (inv_) dla korekty.

  • refund string | null

    Zwrot (re_), po którym powstała korekta.

  • status string wymagane
    openpartially_paidpaidrefunded
  • customer_name string | null
  • customer_tax_id string | null
  • customer_email string | null
  • lines array of object
    • nazwa string
    • ilosc number
    • netto integer
  • vat_rate integer | null

    Stawka VAT w procentach.

  • net integer
  • vat integer
  • gross integer wymagane

    Kwota brutto w groszach.

  • amount_paid integer
  • amount_due integer
  • overpaid integer
  • currency string wymagane
  • issue_date string | null
  • due_date string | null
  • disputed boolean
  • payment string | null

    Płatność (pay_), która opłaciła fakturę.

  • payment_url string | null

    Strona płatności faktury (type payable).

  • ksef_status string | null

    Stan w KSeF: null, wyslana, przyjeta, blad.

  • ksef_number string | null
  • 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_).

  • paid_at integer | null
  • created integer wymagane

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

JSON 
{
  "id": "inv_Ab12Cd34Ef56Gh",
  "object": "invoice",
  "number": "FV/2026/10/0001",
  "type": "payable",
  "corrects": null,
  "refund": null,
  "status": "open",
  "customer_name": "Firma Testowa sp. z o.o.",
  "customer_tax_id": "1234563218",
  "customer_email": "[email protected]",
  "lines": [
    {
      "nazwa": "Usługa wdrożenia",
      "ilosc": 1,
      "netto": 100000
    }
  ],
  "vat_rate": 23,
  "net": 100000,
  "vat": 23000,
  "gross": 123000,
  "amount_paid": 0,
  "amount_due": 123000,
  "overpaid": 0,
  "currency": "PLN",
  "issue_date": "2026-10-03",
  "due_date": "2026-10-17",
  "disputed": false,
  "payment": null,
  "payment_url": "https://oplac.pl/f/Kx7Pq2MnAb12",
  "ksef_status": null,
  "ksef_number": null,
  "metadata": [],
  "livemode": false,
  "paid_at": null,
  "created": 1760000000
}

Wystaw fakturę z terminem#

POST /v1/invoices

Faktura VAT do zapłaty (type payable) z własną stroną płatności (payment_url). Nabywca z customer (cus_) albo z pól customer_*. Z send (domyślnie true) i adresem e-mail nabywcy faktura idzie mailem, a przypomnienia według harmonogramu z panelu. Wymaga uzupełnionych danych firmy sprzedawcy w panelu.

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

Treść żądania JSON

  • customer string

    Klient cus_; jego nazwa, NIP, adres i e-mail trafiają na fakturę.

  • customer_name string

    Do 190 znaków.

  • customer_tax_id string

    Do 20 znaków.

  • customer_address string

    Do 255 znaków.

  • customer_email string (email)
  • due_date string wymagane

    Termin płatności RRRR-MM-DD, nie wcześniej niż dziś.

  • lines array of object wymagane
    • name string wymagane

      Do 256 znaków.

    • quantity number wymagane

      Od 0.01 do 100000.

    • unit_net integer wymagane

      Cena netto jednostki w groszach. Od 1.

  • vat_rate integer

    Stawka VAT w procentach (23, 8, 5, 0); domyślnie stawka z ustawień konta.

  • send boolean

    Domyślnie true.

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

Błędy tej operacji: seller_details_missing, amount_too_large, parameter_missing, api_key_invalid, module_not_in_plan, 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/invoices \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Idempotency-Key: 5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_name": "Firma Testowa sp. z o.o.",
  "customer_tax_id": "1234563218",
  "customer_email": "[email protected]",
  "due_date": "2026-10-17",
  "lines": [
    {
      "name": "Usługa wdrożenia",
      "quantity": 1,
      "unit_net": 100000
    }
  ]
}'
$ch = curl_init('https://oplac.pl/api/v1/invoices');
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([
        'customer_name' => 'Firma Testowa sp. z o.o.',
        'customer_tax_id' => '1234563218',
        'customer_email' => '[email protected]',
        'due_date' => '2026-10-17',
        'lines' => [[
            'name' => 'Usługa wdrożenia',
            'quantity' => 1,
            'unit_net' => 100000,
        ]],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$invoice = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Idempotency-Key': '5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_name: 'Firma Testowa sp. z o.o.',
    customer_tax_id: '1234563218',
    customer_email: '[email protected]',
    due_date: '2026-10-17',
    lines: [{
      name: 'Usługa wdrożenia',
      quantity: 1,
      unit_net: 100000,
    }],
  }),
});
const invoice = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/invoices",
    headers={
        "Authorization": "Bearer sk_test_TWOJ_KLUCZ",
        "Idempotency-Key": "5f0c2a4e-7d1b-4e8a-9b2f-1c3d5e7f9a0b",
    },
    json={
        "customer_name": "Firma Testowa sp. z o.o.",
        "customer_tax_id": "1234563218",
        "customer_email": "[email protected]",
        "due_date": "2026-10-17",
        "lines": [{
            "name": "Usługa wdrożenia",
            "quantity": 1,
            "unit_net": 100000,
        }],
    },
)
invoice = res.json()
Odpowiedź HTTP 201 
{
  "id": "inv_Ab12Cd34Ef56Gh",
  "object": "invoice",
  "number": "FV/2026/10/0001",
  "type": "payable",
  "corrects": null,
  "refund": null,
  "status": "open",
  "customer_name": "Firma Testowa sp. z o.o.",
  "customer_tax_id": "1234563218",
  "customer_email": "[email protected]",
  "lines": [
    {
      "nazwa": "Usługa wdrożenia",
      "ilosc": 1,
      "netto": 100000
    }
  ],
  "vat_rate": 23,
  "net": 100000,
  "vat": 23000,
  "gross": 123000,
  "amount_paid": 0,
  "amount_due": 123000,
  "overpaid": 0,
  "currency": "PLN",
  "issue_date": "2026-10-03",
  "due_date": "2026-10-17",
  "disputed": false,
  "payment": null,
  "payment_url": "https://oplac.pl/f/Kx7Pq2MnAb12",
  "ksef_status": null,
  "ksef_number": null,
  "metadata": [],
  "livemode": false,
  "paid_at": null,
  "created": 1760000000
}

Pobierz fakturę#

GET /v1/invoices/{id}

Faktura po identyfikatorze.

Nagłówki opcjonalne: Oplac-Version

Parametry ścieżki

  • id string wymagane

    Identyfikator inv_.

Parametry zapytania

  • expand[] array of string

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

    paymentrefundcorrects

Odpowiedź

HTTP 200: obiekt invoice.

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

res = requests.get(
    "https://oplac.pl/api/v1/invoices/inv_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
invoice = res.json()
Odpowiedź HTTP 200 
{
  "id": "inv_Ab12Cd34Ef56Gh",
  "object": "invoice",
  "number": "FV/2026/10/0001",
  "type": "payable",
  "corrects": null,
  "refund": null,
  "status": "open",
  "customer_name": "Firma Testowa sp. z o.o.",
  "customer_tax_id": "1234563218",
  "customer_email": "[email protected]",
  "lines": [
    {
      "nazwa": "Usługa wdrożenia",
      "ilosc": 1,
      "netto": 100000
    }
  ],
  "vat_rate": 23,
  "net": 100000,
  "vat": 23000,
  "gross": 123000,
  "amount_paid": 0,
  "amount_due": 123000,
  "overpaid": 0,
  "currency": "PLN",
  "issue_date": "2026-10-03",
  "due_date": "2026-10-17",
  "disputed": false,
  "payment": null,
  "payment_url": "https://oplac.pl/f/Kx7Pq2MnAb12",
  "ksef_status": null,
  "ksef_number": null,
  "metadata": [],
  "livemode": false,
  "paid_at": null,
  "created": 1760000000
}

Zmień fakturę#

POST /v1/invoices/{id}

Tylko metadata: treść wystawionej faktury jest stała, poprawki to faktura korygująca.

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

Parametry ścieżki

  • id string wymagane

    Identyfikator inv_.

Treść żądania JSON, opcjonalna

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

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, 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/invoices/inv_Ab12Cd34Ef56Gh \
  -H "Authorization: Bearer sk_test_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "order_id": "10482"
  }
}'
$ch = curl_init('https://oplac.pl/api/v1/invoices/inv_Ab12Cd34Ef56Gh');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_test_TWOJ_KLUCZ',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'metadata' => [
            'order_id' => '10482',
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$invoice = json_decode(curl_exec($ch), true);
const res = await fetch('https://oplac.pl/api/v1/invoices/inv_Ab12Cd34Ef56Gh', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_TWOJ_KLUCZ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    metadata: {
      order_id: '10482',
    },
  }),
});
const invoice = await res.json();
import requests

res = requests.post(
    "https://oplac.pl/api/v1/invoices/inv_Ab12Cd34Ef56Gh",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
    json={
        "metadata": {
            "order_id": "10482",
        },
    },
)
invoice = res.json()
Odpowiedź HTTP 200 
{
  "id": "inv_Ab12Cd34Ef56Gh",
  "object": "invoice",
  "number": "FV/2026/10/0001",
  "type": "payable",
  "corrects": null,
  "refund": null,
  "status": "open",
  "customer_name": "Firma Testowa sp. z o.o.",
  "customer_tax_id": "1234563218",
  "customer_email": "[email protected]",
  "lines": [
    {
      "nazwa": "Usługa wdrożenia",
      "ilosc": 1,
      "netto": 100000
    }
  ],
  "vat_rate": 23,
  "net": 100000,
  "vat": 23000,
  "gross": 123000,
  "amount_paid": 0,
  "amount_due": 123000,
  "overpaid": 0,
  "currency": "PLN",
  "issue_date": "2026-10-03",
  "due_date": "2026-10-17",
  "disputed": false,
  "payment": null,
  "payment_url": "https://oplac.pl/f/Kx7Pq2MnAb12",
  "ksef_status": null,
  "ksef_number": null,
  "metadata": [],
  "livemode": false,
  "paid_at": null,
  "created": 1760000000
}

Lista faktur#

GET /v1/invoices

Faktury konta w trybie klucza (do zapłaty, po opłaceniu, korekty).

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

    Filtr statusu.

    openpartially_paidpaidrefunded
  • type string

    Filtr rodzaju.

    payablepaidcredit_note
  • expand[] array of string

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

    paymentrefundcorrects

Odpowiedź

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

res = requests.get(
    "https://oplac.pl/api/v1/invoices?limit=3",
    headers={"Authorization": "Bearer sk_test_TWOJ_KLUCZ"},
)
invoices = res.json()
Odpowiedź HTTP 200 
{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
      "id": "inv_Ab12Cd34Ef56Gh",
      "object": "invoice",
      "number": "FV/2026/10/0001",
      "type": "payable",
      "corrects": null,
      "refund": null,
      "status": "open",
      "customer_name": "Firma Testowa sp. z o.o.",
      "customer_tax_id": "1234563218",
      "customer_email": "[email protected]",
      "lines": [
        {
          "nazwa": "Usługa wdrożenia",
          "ilosc": 1,
          "netto": 100000
        }
      ],
      "vat_rate": 23,
      "net": 100000,
      "vat": 23000,
      "gross": 123000,
      "amount_paid": 0,
      "amount_due": 123000,
      "overpaid": 0,
      "currency": "PLN",
      "issue_date": "2026-10-03",
      "due_date": "2026-10-17",
      "disputed": false,
      "payment": null,
      "payment_url": "https://oplac.pl/f/Kx7Pq2MnAb12",
      "ksef_status": null,
      "ksef_number": null,
      "metadata": [],
      "livemode": false,
      "paid_at": null,
      "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.