Invoices and corrections

curl "https://app.ksefshop.pl/v1/invoices?limit=10" \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/invoices?limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo count($data['data']), ' objects', PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/invoices?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.data.length, data.has_more);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/invoices?limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(len(data["data"]), data["has_more"])

curl -X POST https://app.ksefshop.pl/v1/invoices \
  -H "Authorization: Bearer $KSEF_API_KEY" \
  -H "Idempotency-Key: order-SO-1001" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {
    "external_id": "SO-1001",
    "number": "1001",
    "paid_at": "2026-10-19T09:13:05Z",
    "currency": "PLN",
    "payment_method": "card",
    "buyer": {
      "nip": "5260250274",
      "name": "Testowa Firma sp. z o.o.",
      "address_line1": "ul. Prosta 20",
      "address_line2": "00-850 Warszawa",
      "email": "jan@example.com"
    },
    "lines": [
      {
        "name": "Kubek ceramiczny 350 ml",
        "sku": "KUB-350",
        "quantity": 2,
        "unit_price": "49.00",
        "vat_rate": "23"
      },
      {
        "name": "Książka: Podstawy księgowości",
        "sku": "KS-001",
        "quantity": 1,
        "unit_price": "59.90",
        "discount": "9.90",
        "vat_rate": "5"
      }
    ],
    "shipping": [
      {
        "name": "Kurier InPost",
        "price": "15.99",
        "vat_rate": "23"
      }
    ]
  }
}'

<?php
$payload = [
    'order' => [
        'external_id' => 'SO-1001',
        'number' => '1001',
        'paid_at' => '2026-10-19T09:13:05Z',
        'currency' => 'PLN',
        'payment_method' => 'card',
        'buyer' => [
            'nip' => '5260250274',
            'name' => 'Testowa Firma sp. z o.o.',
            'address_line1' => 'ul. Prosta 20',
            'address_line2' => '00-850 Warszawa',
            'email' => 'jan@example.com',
        ],
        'lines' => [
            [
                'name' => 'Kubek ceramiczny 350 ml',
                'sku' => 'KUB-350',
                'quantity' => 2,
                'unit_price' => '49.00',
                'vat_rate' => '23',
            ],
            [
                'name' => 'Książka: Podstawy księgowości',
                'sku' => 'KS-001',
                'quantity' => 1,
                'unit_price' => '59.90',
                'discount' => '9.90',
                'vat_rate' => '5',
            ],
        ],
        'shipping' => [
            ['name' => 'Kurier InPost', 'price' => '15.99', 'vat_rate' => '23'],
        ],
    ],
];

$ch = curl_init('https://app.ksefshop.pl/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
        'Idempotency-Key: order-SO-1001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['id'], true), ' ', var_export($data['status'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
    "Idempotency-Key": "order-SO-1001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      external_id: "SO-1001",
      number: "1001",
      paid_at: "2026-10-19T09:13:05Z",
      currency: "PLN",
      payment_method: "card",
      buyer: {
        nip: "5260250274",
        name: "Testowa Firma sp. z o.o.",
        address_line1: "ul. Prosta 20",
        address_line2: "00-850 Warszawa",
        email: "jan@example.com",
      },
      lines: [
        {
          name: "Kubek ceramiczny 350 ml",
          sku: "KUB-350",
          quantity: 2,
          unit_price: "49.00",
          vat_rate: "23",
        },
        {
          name: "Książka: Podstawy księgowości",
          sku: "KS-001",
          quantity: 1,
          unit_price: "59.90",
          discount: "9.90",
          vat_rate: "5",
        },
      ],
      shipping: [
        { name: "Kurier InPost", price: "15.99", vat_rate: "23" },
      ],
    },
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.id, data.status);

import os
import requests

resp = requests.post(
    "https://app.ksefshop.pl/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
        "Idempotency-Key": "order-SO-1001",
    },
    json={
        "order": {
            "external_id": "SO-1001",
            "number": "1001",
            "paid_at": "2026-10-19T09:13:05Z",
            "currency": "PLN",
            "payment_method": "card",
            "buyer": {
                "nip": "5260250274",
                "name": "Testowa Firma sp. z o.o.",
                "address_line1": "ul. Prosta 20",
                "address_line2": "00-850 Warszawa",
                "email": "jan@example.com",
            },
            "lines": [
                {
                    "name": "Kubek ceramiczny 350 ml",
                    "sku": "KUB-350",
                    "quantity": 2,
                    "unit_price": "49.00",
                    "vat_rate": "23",
                },
                {
                    "name": "Książka: Podstawy księgowości",
                    "sku": "KS-001",
                    "quantity": 1,
                    "unit_price": "59.90",
                    "discount": "9.90",
                    "vat_rate": "5",
                },
            ],
            "shipping": [
                {"name": "Kurier InPost", "price": "15.99", "vat_rate": "23"},
            ],
        },
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["id"], data["status"])

curl https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['status'], true), ' ', var_export($data['ksef_number'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.status, data.ksef_number);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["status"], data["ksef_number"])

curl https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/pdf \
  -H "Authorization: Bearer $KSEF_API_KEY" \
  --fail -o invoice.pdf

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/pdf');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException('PDF: HTTP ' . $status); // 409 pdf_not_ready: retry in a few seconds
}
file_put_contents('invoice.pdf', $body);

import { writeFile } from "node:fs/promises";

const res = await fetch("https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/pdf", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`PDF: HTTP ${res.status}`); // 409 pdf_not_ready: retry in a few seconds
await writeFile("invoice.pdf", Buffer.from(await res.arrayBuffer()));

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
resp.raise_for_status()  # 409 pdf_not_ready: retry in a few seconds
with open("invoice.pdf", "wb") as f:
    f.write(resp.content)

curl -X POST https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/corrections \
  -H "Authorization: Bearer $KSEF_API_KEY" \
  -H "Idempotency-Key: refund-RF-1" \
  -H "Content-Type: application/json" \
  -d '{
  "refund": {
    "external_id": "RF-1",
    "reason": "Zwrot towaru",
    "lines": [
      {
        "name": "Kubek ceramiczny 350 ml",
        "sku": "KUB-350",
        "quantity": 1,
        "unit_price": "49.00",
        "vat_rate": "23"
      }
    ],
    "shipping": {
      "price": "15.99"
    }
  }
}'

<?php
$payload = [
    'refund' => [
        'external_id' => 'RF-1',
        'reason' => 'Zwrot towaru',
        'lines' => [
            [
                'name' => 'Kubek ceramiczny 350 ml',
                'sku' => 'KUB-350',
                'quantity' => 1,
                'unit_price' => '49.00',
                'vat_rate' => '23',
            ],
        ],
        'shipping' => ['price' => '15.99'],
    ],
];

$ch = curl_init('https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/corrections');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
        'Idempotency-Key: refund-RF-1',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['id'], true), ' ', var_export($data['status'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/corrections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
    "Idempotency-Key": "refund-RF-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    refund: {
      external_id: "RF-1",
      reason: "Zwrot towaru",
      lines: [
        {
          name: "Kubek ceramiczny 350 ml",
          sku: "KUB-350",
          quantity: 1,
          unit_price: "49.00",
          vat_rate: "23",
        },
      ],
      shipping: { price: "15.99" },
    },
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.id, data.status);

import os
import requests

resp = requests.post(
    "https://app.ksefshop.pl/v1/invoices/inv_4fJ2kP9xQwErTy7uI0oPaSdF/corrections",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
        "Idempotency-Key": "refund-RF-1",
    },
    json={
        "refund": {
            "external_id": "RF-1",
            "reason": "Zwrot towaru",
            "lines": [
                {
                    "name": "Kubek ceramiczny 350 ml",
                    "sku": "KUB-350",
                    "quantity": 1,
                    "unit_price": "49.00",
                    "vat_rate": "23",
                },
            ],
            "shipping": {"price": "15.99"},
        },
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["id"], data["status"])