Public API – Wystawianie faktur

Wymagania

• Client API ID – aby uzyskać identyfikator, napisz na [email protected] i podaj swój NIP (tax ID).
• Bazowy URL: https://app.autofaktury.pl/api. Wszystkie poniższe endpointy dodają /public/api/....
• Wysyłaj nagłówek clientApiId w każdym żądaniu.

Uwierzytelnianie – Informacje

Weryfikuje przekazany clientApiId bez efektów ubocznych. Używaj do sprawdzenia prawidłowości poświadczeń i weryfikacji kondycji usługi.

URL:

GET $BASE_URL/public/api/invoices/v1/info

Nagłówki:

clientApiId: <CLIENT_API_ID>

Curl:

curl --location "$BASE_URL/public/api/invoices/v1/info" \
  --header "clientApiId: <CLIENT_API_ID>"

Odpowiedź (przykład):

{
  "info": "OK"
}

• info: "OK" | "FAILED"

Uwagi:

• Brak efektów ubocznych; sprawdza ważność clientApiId.
• Zwraca prosty status informujący, czy poświadczenia są poprawne i konto jest aktywne.

Obsługa błędów:

• 200 z info: "OK" — poświadczenia poprawne.
• 200 z info: "FAILED" — poświadczenia niepoprawne lub brak autoryzacji.
• 5xx — błąd serwera.

Utworzenie faktury

Tworzy nową fakturę z podanymi danymi, w tym dostawcą, pozycjami i warunkami płatności.

URL:

POST $BASE_URL/public/api/invoices/v1

Nagłówki:

clientApiId: <CLIENT_API_ID>
Content-Type: application/json

Curl:

curl --location "$BASE_URL/public/api/invoices/v1" \
  --header "clientApiId: <CLIENT_API_ID>" \
  --header "Content-Type: application/json" \
  --data '{
    "mainLanguage": "PL",
    "type": "VAT",
    "title": "FV/12/09/2025",
    "invoiceDate": "2025-09-15",
    "sellDate": "2025-09-15",
    "createdBy": "API Tester",
    "invoiceCity": "Warszawa",
    "supplier": {
      "supplierName": "Firma sp. z o.o.",
      "nip": "5250001009",
      "city": "Warszawa",
      "postalCode": "00-001",
      "number": "1",
      "countryCode": "PL",
      "business": true
    },
    "lines": [
      { "name": "Usługa programowania", "unit": "szt.", "quantity": 1, "unitPriceNetto": "100.00", "vat": 23 }
    ],
    "currency": "PLN",
    "comments": "Płatność w terminie 30 dni",
    "paymentStatus": "TO_PAID",
    "paymentDate": "2025-10-01",
    "paymentType": "TRANSFER",
    "requestedAccountNumber": "12345678901234567890123456"
  }'

Żądanie (przykład):

{
  "mainLanguage": "PL",
  "type": "VAT",
  "title": "FV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "createdBy": "API Tester",
  "invoiceCity": "Warszawa",
  "supplier": {
    "supplierName": "Firma sp. z o.o.",
    "nip": "5250001009",
    "city": "Warszawa",
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true
  },
  "lines": [
    { "name": "Usługa programowania", "unit": "szt.", "quantity": 1, "unitPriceNetto": "100.00", "vat": 23 }
  ],
  "currency": "PLN",
  "comments": "Płatność w terminie 30 dni",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456"
}

Odpowiedź (przykład):

{
  "mainLanguage": "PL",
  "secondLanguage": null,
  "type": "VAT",
  "title": "FV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "invoiceCity": "Warszawa",
  "supplierId": null,
  "supplier": {
    "id": null,
    "supplierFirstname": null,
    "supplierName": "Firma sp. z o.o.",
    "nip": "5250001009",
    "city": "Warszawa",
    "street": null,
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true,
    "email": null,
    "phone": null
  },
  "lines": [
    {
      "id": null,
      "name": "Usługa programowania",
      "unit": "szt.",
      "quantity": 1,
      "unitPriceNetto": "100.00",
      "vat": 23,
      "discountValue": null,
      "discountPercentage": null,
      "priceNetto": "100.00",
      "priceVat": "23.0000",
      "priceBrutto": "123.0000"
    }
  ],
  "currency": "PLN",
  "comments": "Płatność w terminie 30 dni",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456",
  "file": {
    "publicUrl": null
  }
}

Uwagi:

• Podaj dokładnie jedno z: invoicePatternId (skonfigurowane per firma) LUB title.
• Daty: YYYY-MM-DD. Ceny jako stringi z kropką, np. "100.00".
• Dla paymentType = TRANSFER wymagany jest requestedAccountNumber. Niecyfrowe znaki mogą zostać usunięte.

Pola i ograniczenia (skrót)

• mainLanguage: enum PL, EN.
• secondLanguage: enum PL, EN (opcjonalne).
• type: enum VAT, PRO_FORMA, CORRECTION.
• title: string 1..254 (wzajemnie wyklucza się z invoicePatternId).
• invoicePatternId: string 1..64 (wzajemnie wyklucza się z title).
• invoiceDate, sellDate, paymentDate: YYYY-MM-DD (paymentDate: termin płatności).
• createdBy: 1..64, invoiceCity: 1..128.
• supplier: obiekt (jeśli podany, supplierId jest ignorowany).
• lines: tablica pozycji
  • name 1..1000, unit 1..64
  • quantity: dodatnia liczba dziesiętna
  • unitPriceNetto: dodatnia liczba dziesiętna (string), 2 miejsca po przecinku
  • vat: liczba całkowita ≥ 0
  • discountValue/discountPercentage: liczba dziesiętna (string), 2 miejsca po przecinku
• currency: 3 litery
• paymentStatus: enum TO_PAID, IN_PAYMENT, PAID, NOT_PAYABLE, NEW
• paymentType: enum TRANSFER, CASH, CARD, CREDIT_CARD, ONLINE
• requestedAccountNumber: wymagane dla TRANSFER.

Obsługa błędów

• 400 FIELDS_ERROR — problemy z walidacją (brakujące/nieprawidłowe pola, tylko spacje).
• 500 — błąd serwera; sprawdź ponownie payload i logi serwera.

Pobranie faktury po ID

Pobiera istniejącą fakturę po jej unikalnym identyfikatorze.

URL:

GET $BASE_URL/public/api/invoices/v1/{id}

Nagłówki:

clientApiId: <CLIENT_API_ID>

Curl:

curl --location "$BASE_URL/public/api/invoices/v1/{id}" \
  --header "clientApiId: <CLIENT_API_ID>"

Odpowiedź (przykład):

{
  "mainLanguage": "PL",
  "secondLanguage": null,
  "type": "VAT",
  "title": "FV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "invoiceCity": "Warszawa",
  "supplierId": null,
  "supplier": {
    "id": null,
    "supplierFirstname": null,
    "supplierName": "Firma sp. z o.o.",
    "nip": "5250001009",
    "city": "Warszawa",
    "street": null,
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true,
    "email": null,
    "phone": null
  },
  "lines": [
    {
      "id": null,
      "name": "Usługa programowania",
      "unit": "szt.",
      "quantity": 1,
      "unitPriceNetto": "100.00",
      "vat": 23,
      "discountValue": null,
      "discountPercentage": null,
      "priceNetto": "100.00",
      "priceVat": "23.0000",
      "priceBrutto": "123.0000"
    }
  ],
  "currency": "PLN",
  "comments": "Płatność w terminie 30 dni",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456",
  "file": {
    "publicUrl": null
  }
}