Wysyłka faktury do KSeF

Wysyłka do KSeF odbywa się w tle: żądanie zwraca status pending, a wynik jest dostępny później. Poradnik dotyczy faktury, która już istnieje w inFakcie. Nową fakturę można wysłać od razu, dodając parametr send_to_ksef=true przy jej tworzeniu.

Wymagania

Klucz API z zakresami api:invoices:write i api:invoices:read w zmiennej INFAKT_API_KEY.
uuid faktury w zmiennej INVOICE_UUID. Może to być faktura VAT, zaliczkowa, końcowa lub korygująca albo jej odpowiednik w procedurze marży.

Kroki

Sprawdzenie połączenia z KSeF

curl "https://api.sandbox-infakt.pl/v3/ksef2/integration.json" \
  -H "X-inFakt-ApiKey: $INFAKT_API_KEY"

const res = await fetch("https://api.sandbox-infakt.pl/v3/ksef2/integration.json", {
  method: "GET",
  headers: {
    "X-inFakt-ApiKey": process.env.INFAKT_API_KEY,
  },
});
const data = await res.json();
console.log(res.status, data);

import os
import requests

res = requests.get(
    "https://api.sandbox-infakt.pl/v3/ksef2/integration.json",
    headers={"X-inFakt-ApiKey": os.environ["INFAKT_API_KEY"]},
)
print(res.status_code, res.json())

<?php
$ch = curl_init('https://api.sandbox-infakt.pl/v3/ksef2/integration.json');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-inFakt-ApiKey: ' . getenv('INFAKT_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, ' ', $response, PHP_EOL;

Wartość "active": true oznacza, że wysyłka jest możliwa.

Wysłanie faktury

curl -X POST "https://api.sandbox-infakt.pl/v3/ksef2/documents/$INVOICE_UUID/send.json" \
  -H "X-inFakt-ApiKey: $INFAKT_API_KEY"

const res = await fetch(`https://api.sandbox-infakt.pl/v3/ksef2/documents/${process.env.INVOICE_UUID}/send.json`, {
  method: "POST",
  headers: {
    "X-inFakt-ApiKey": process.env.INFAKT_API_KEY,
  },
});
const data = await res.json();
console.log(res.status, data);

import os
import requests

res = requests.post(
    f"https://api.sandbox-infakt.pl/v3/ksef2/documents/{os.environ['INVOICE_UUID']}/send.json",
    headers={"X-inFakt-ApiKey": os.environ["INFAKT_API_KEY"]},
)
print(res.status_code, res.json())

<?php
$ch = curl_init('https://api.sandbox-infakt.pl/v3/ksef2/documents/' . getenv('INVOICE_UUID') . '/send.json');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-inFakt-ApiKey: ' . getenv('INFAKT_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, ' ', $response, PHP_EOL;

{
  "request_uuid": "7d6c5b4a-3e2f-4a1b-9c8d-0e1f2a3b4c5d",
  "invoice_uuid": "9bdc76fd-7a02-42ec-a4a3-42bc867b9a9f",
  "invoice_kind": "vat",
  "ksef_number": null,
  "status": "pending",
  "status_description": "Faktura oczekuje na wysłanie do KSeF."
}

Odbiór wyniku

Wynik najlepiej odbierać przez webhooki send_to_ksef_success i send_to_ksef_error (Dodawanie i aktywacja webhooka). Bez webhooka status sprawdza się co kilka sekund:

curl "https://api.sandbox-infakt.pl/v3/ksef2/documents/$INVOICE_UUID/status.json" \
  -H "X-inFakt-ApiKey: $INFAKT_API_KEY"

const res = await fetch(`https://api.sandbox-infakt.pl/v3/ksef2/documents/${process.env.INVOICE_UUID}/status.json`, {
  method: "GET",
  headers: {
    "X-inFakt-ApiKey": process.env.INFAKT_API_KEY,
  },
});
const data = await res.json();
console.log(res.status, data);

import os
import requests

res = requests.get(
    f"https://api.sandbox-infakt.pl/v3/ksef2/documents/{os.environ['INVOICE_UUID']}/status.json",
    headers={"X-inFakt-ApiKey": os.environ["INFAKT_API_KEY"]},
)
print(res.status_code, res.json())

<?php
$ch = curl_init('https://api.sandbox-infakt.pl/v3/ksef2/documents/' . getenv('INVOICE_UUID') . '/status.json');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-inFakt-ApiKey: ' . getenv('INFAKT_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, ' ', $response, PHP_EOL;

Weryfikacja

Status	Znaczenie
`pending`, `sent`	wysyłka w toku; status należy sprawdzić ponownie
`success`	faktura przyjęta; `ksef_number` zawiera jej numer KSeF
`error`	faktura odrzucona; przyczynę opisuje `status_description`
`cancelled`	wysyłka została anulowana

Kod 422 przy wysyłce oznacza najczęściej brak integracji konta z KSeF (422 przy wysyłce do KSeF).