Wystawianie wielu faktur naraz

Endpoint POST /async/invoices.json przyjmuje tę samą treść żądania co tworzenie synchroniczne, ale zamiast faktury od razu zwraca identyfikator zadania. Zlecenia trafiają do kolejki, która nadaje numery po kolei, więc równoległe zlecenia nie powodują konfliktów numeracji.

Wymagania

Klucz API z zakresami api:invoices:write i api:invoices:read w zmiennej INFAKT_API_KEY.
Opcjonalnie: webhook ze zdarzeniami async_invoice_creation_success i async_invoice_creation_error.

Kroki

Zlecenie utworzenia faktury

Każda faktura to osobne zlecenie. Faktura, która ma od razu trafić do KSeF, wymaga parametru ?send_to_ksef=true.

curl -X POST "https://api.sandbox-infakt.pl/v3/async/invoices.json" \
  -H "X-inFakt-ApiKey: $INFAKT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "kind": "vat",
      "payment_method": "cash",
      "client_company_name": "Testowa Firma sp. z o.o.",
      "client_tax_code": "2222222222",
      "services": [
        {
          "name": "Usługa programistyczna",
          "tax_symbol": "23",
          "quantity": 1,
          "unit_net_price": 10000
        }
      ]
    }
  }'

const res = await fetch("https://api.sandbox-infakt.pl/v3/async/invoices.json", {
  method: "POST",
  headers: {
    "X-inFakt-ApiKey": process.env.INFAKT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "invoice": {
      "kind": "vat",
      "payment_method": "cash",
      "client_company_name": "Testowa Firma sp. z o.o.",
      "client_tax_code": "2222222222",
      "services": [
        {
          "name": "Usługa programistyczna",
          "tax_symbol": "23",
          "quantity": 1,
          "unit_net_price": 10000
        }
      ]
    }
  }),
});
const data = await res.json();
console.log(res.status, data);

import os
import requests

res = requests.post(
    "https://api.sandbox-infakt.pl/v3/async/invoices.json",
    headers={"X-inFakt-ApiKey": os.environ["INFAKT_API_KEY"]},
    json={
        "invoice": {
            "kind": "vat",
            "payment_method": "cash",
            "client_company_name": "Testowa Firma sp. z o.o.",
            "client_tax_code": "2222222222",
            "services": [
                {
                    "name": "Usługa programistyczna",
                    "tax_symbol": "23",
                    "quantity": 1,
                    "unit_net_price": 10000
                }
            ]
        }
    },
)
print(res.status_code, res.json())

<?php
$ch = curl_init('https://api.sandbox-infakt.pl/v3/async/invoices.json');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-inFakt-ApiKey: ' . getenv('INFAKT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'invoice' => [
            'kind' => 'vat',
            'payment_method' => 'cash',
            'client_company_name' => 'Testowa Firma sp. z o.o.',
            'client_tax_code' => '2222222222',
            'services' => [
                [
                    'name' => 'Usługa programistyczna',
                    'tax_symbol' => '23',
                    'quantity' => 1,
                    'unit_net_price' => 10000,
                ],
            ],
        ],
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, ' ', $response, PHP_EOL;

Odpowiedź 201 potwierdza przyjęcie zlecenia:

{
  "invoice_task_reference_number": "4f6a8c1e-2b3d-4e5f-9a7b-8c9d0e1f2a3b",
  "processing_code": 100,
  "processing_description": "Zlecenie przyjęte",
  "action": "create_invoice",
  "invoice_kind": "invoice",
  "timestamps": {
    "task_created_at": "2026-10-02 12:00:00 +0200"
  }
}

Wartość invoice_task_reference_number warto zapisać, np. przy zamówieniu w systemie sklepu.

Odbiór wyniku

Najprościej odebrać webhook async_invoice_creation_success, w którym pole resource.invoice_uuid wskazuje utworzoną fakturę. Bez webhooka status zadania sprawdza się co kilka sekund:

curl "https://api.sandbox-infakt.pl/v3/async/invoices/status/$TASK_REF.json" \
  -H "X-inFakt-ApiKey: $INFAKT_API_KEY"

const res = await fetch(`https://api.sandbox-infakt.pl/v3/async/invoices/status/${process.env.TASK_REF}.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/async/invoices/status/{os.environ['TASK_REF']}.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/async/invoices/status/' . getenv('TASK_REF') . '.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

Wartość processing_code: 201 oznacza, że faktura została utworzona. Pole invoice_uuid zawiera jej identyfikator:

{
  "invoice_task_reference_number": "4f6a8c1e-2b3d-4e5f-9a7b-8c9d0e1f2a3b",
  "processing_code": 201,
  "processing_description": "Faktura stworzona",
  "action": "create_invoice",
  "invoice_kind": "invoice",
  "invoice_uuid": "9bdc76fd-7a02-42ec-a4a3-42bc867b9a9f"
}

Wartość processing_code: 422 oznacza błąd. Szczegóły zawiera pole invoice_errors. Po poprawieniu danych zlecenie wysyła się ponownie. Kody 100, 120 i 140 oznaczają, że zadanie jest jeszcze przetwarzane.