Przewodniki
Faktury w walucie obcej i kurs NBP
Zamówienie może być w euro, dolarach albo innej walucie z tabeli A NBP. Faktura ma kwoty w walucie, a VAT również w złotych po kursie NBP.
Jak to działa
Ustaw order.currency na kod waluty, np. EUR. Ceny pozycji i dostawy podajesz w tej walucie. Faktura ma kwoty w walucie zamówienia, a kwotę VAT również w złotych, przeliczoną po średnim kursie NBP z tabeli A z ostatniego dnia roboczego przed dniem zapłaty (paid_at). Numer tabeli i datę kursu drukujemy na fakturze.
POST /v1/invoices
curl -X POST https://app.ksefshop.pl/v1/invoices \
-H "Authorization: Bearer $KSEF_API_KEY" \
-H "Idempotency-Key: order-SO-1002" \
-H "Content-Type: application/json" \
-d '{
"order": {
"external_id": "SO-1002",
"paid_at": "2026-10-20T07:15:00Z",
"currency": "EUR",
"payment_method": "transfer",
"buyer": {
"nip": "7740001454",
"name": "Przykład S.A.",
"address_line1": "ul. Długa 5",
"address_line2": "80-831 Gdańsk"
},
"lines": [
{
"name": "Lampka biurkowa LED",
"quantity": 1,
"unit_price": "123.00",
"vat_rate": "23"
}
]
}
}'<?php
$payload = [
'order' => [
'external_id' => 'SO-1002',
'paid_at' => '2026-10-20T07:15:00Z',
'currency' => 'EUR',
'payment_method' => 'transfer',
'buyer' => [
'nip' => '7740001454',
'name' => 'Przykład S.A.',
'address_line1' => 'ul. Długa 5',
'address_line2' => '80-831 Gdańsk',
],
'lines' => [
[
'name' => 'Lampka biurkowa LED',
'quantity' => 1,
'unit_price' => '123.00',
'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-1002',
'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-1002",
"Content-Type": "application/json",
},
body: JSON.stringify({
order: {
external_id: "SO-1002",
paid_at: "2026-10-20T07:15:00Z",
currency: "EUR",
payment_method: "transfer",
buyer: {
nip: "7740001454",
name: "Przykład S.A.",
address_line1: "ul. Długa 5",
address_line2: "80-831 Gdańsk",
},
lines: [
{ name: "Lampka biurkowa LED", quantity: 1, unit_price: "123.00", 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-1002",
},
json={
"order": {
"external_id": "SO-1002",
"paid_at": "2026-10-20T07:15:00Z",
"currency": "EUR",
"payment_method": "transfer",
"buyer": {
"nip": "7740001454",
"name": "Przykład S.A.",
"address_line1": "ul. Długa 5",
"address_line2": "80-831 Gdańsk",
},
"lines": [
{
"name": "Lampka biurkowa LED",
"quantity": 1,
"unit_price": "123.00",
"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"])Które waluty
PLN oraz każda waluta, którą NBP publikuje w tabeli A kursów średnich (EUR, USD, GBP, CHF, CZK i inne). Waluta spoza tabeli A zwraca 400 currency_not_supported.
Sprawdź kurs przed wysłaniem
Kurs i przeliczenie VAT możesz sprawdzić ręcznie w naszym darmowym narzędziu: kurs NBP do faktury. Liczy tak samo: tabela A z dnia roboczego przed podaną datą.
Na co uważać
paid_atdecyduje o dacie kursu. Wysyłaj prawdziwy moment płatności, nie moment wysyłki do API.total_grossw obiekcie faktury jest w walucie faktury, nie w złotych.- Korekta faktury walutowej jest w tej samej walucie co faktura pierwotna.