Quickstart

Od zera do pierwszej zwalidowanej faktury KSeF w 5 minut. Trzy języki obok siebie.

1. Utwórz klucz API

Otwórz /dashboard/api-keys → Nowy klucz. Wybierz environment: test żeby pierwsza integracja nie konsumowała quoty i nie zapisywała historii. Plaintext klucza zobaczysz tylko raz - skopiuj go do swojego managera sekretów (env, AWS Secrets Manager, 1Password, ...).

Format klucza

Sandbox: nk_test_ + 36 hex. Produkcja: nk_live_ + 36 hex. SDK i serwer odrzucają klucze które nie pasują do tego wzorca.

2. Sprawdź połączenie (curl)

bash

# Liveness - bez auth, sprawdza tylko czy API stoi
curl https://api.naprawksef.pl/api/v1/health

# Whoami - zwraca info o kluczu, organizacji i bieżącym oknie rate-limit
curl https://api.naprawksef.pl/api/v1/me \
  -H "Authorization: Bearer nk_test_<TWOJ_KLUCZ>"

3. Zwaliduj XML faktury

Każdy POST do /validate przyjmuje albo JSON ({ xml: "..." }), albo raw application/xml.

bash

curl https://api.naprawksef.pl/api/v1/validate \
  -X POST \
  -H "Authorization: Bearer nk_test_<TWOJ_KLUCZ>" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: invoice-42-v1" \
  --data-binary @faktura.xml

typescript

import { NaprawKsef } from "@naprawksef/sdk";
import { readFileSync } from "node:fs";

const client = new NaprawKsef({
  apiKey: process.env.NAPRAW_KSEF_API_KEY!,
});

const result = await client.validate.run({
  xml: readFileSync("faktura.xml", "utf8"),
  filename: "faktura.xml",
  idempotencyKey: "invoice-42-v1",
});

if (!result.valid) {
  for (const issue of result.issues) {
    console.error(`[${issue.severity}] ${issue.code}: ${issue.message}`);
  }
}

php

<?php
use NaprawKsef\Sdk\NaprawKsef;

require __DIR__ . '/vendor/autoload.php';

$client = new NaprawKsef([
    'api_key' => $_ENV['NAPRAW_KSEF_API_KEY'],
]);

$result = $client->validate->run(
    xml: file_get_contents('faktura.xml'),
    filename: 'faktura.xml',
    idempotencyKey: 'invoice-42-v1',
);

if (!$result['valid']) {
    foreach ($result['issues'] as $issue) {
        printf("[%s] %s: %s\n", $issue['severity'], $issue['code'], $issue['message']);
    }
}

4. Co dalej?

Idempotency - bezpieczne ponawianie żądań bez ryzyka duplikatów.
Webhooks - odbiór zdarzeń (validation.completed, correction.created, quota.exceeded) z weryfikacją podpisu HMAC.
Rate limits - limity per klucz/organizacja i jak obsługiwać 429.
Katalog błędów - co znaczy każdy kod i jak na niego reagować.