Public API – Invoicing

Requirements

• Client API ID – to obtain your identifier, email [email protected] and include your NIP (tax ID).
• Base URL: https://app.autofaktury.pl/api. All endpoints below append /public/api/....
• Send clientApiId header with every request.

Authentication – Info

Verifies the provided clientApiId without side effects. Use for credential checks and service health verification.

URL:

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

Headers:

clientApiId: <CLIENT_API_ID>

Curl:

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

Response (example):

{
  "info": "OK"
}

• info: "OK" | "FAILED"

Notes:

• Side‑effect free; checks validity of clientApiId.
• Returns a simple status to indicate whether credentials are valid and the account is active.

Error handling:

• 200 with info: "OK" — credentials valid.
• 200 with info: "FAILED" — credentials invalid or not authorized.
• 5xx — server error.

Create Invoice

Creates a new invoice with specified details including supplier information, line items, and payment terms.

URL:

POST $BASE_URL/public/api/invoices/v1

Headers:

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": "INV/12/09/2025",
    "invoiceDate": "2025-09-15",
    "sellDate": "2025-09-15",
    "createdBy": "API Test",
    "invoiceCity": "Warsaw",
    "supplier": {
      "supplierName": "Example Company Ltd",
      "nip": "5250001009",
      "city": "Warsaw",
      "postalCode": "00-001",
      "number": "1",
      "countryCode": "PL",
      "business": true
    },
    "lines": [
      { "name": "Web Development Service", "unit": "pcs", "quantity": 1, "unitPriceNetto": "100.00", "vatType": "VAT_23" }
    ],
    "currency": "PLN",
    "comments": "Payment due within 30 days",
    "paymentStatus": "TO_PAID",
    "paymentDate": "2025-10-01",
    "paymentType": "TRANSFER",
    "requestedAccountNumber": "12345678901234567890123456"
  }'

Request (example):

{
  "mainLanguage": "PL",
  "type": "VAT",
  "title": "INV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "createdBy": "API Test",
  "invoiceCity": "Warsaw",
  "supplier": {
    "supplierName": "Example Company Ltd",
    "nip": "5250001009",
    "city": "Warsaw",
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true
  },
  "lines": [
    { "name": "Web Development Service", "unit": "pcs", "quantity": 1, "unitPriceNetto": "100.00", "vatType": "VAT_23" }
  ],
  "currency": "PLN",
  "comments": "Payment due within 30 days",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456"
}

Response (example):

{
  "mainLanguage": "PL",
  "secondLanguage": null,
  "type": "VAT",
  "title": "INV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "invoiceCity": "Warsaw",
  "supplierId": null,
  "supplier": {
    "id": null,
    "supplierFirstname": null,
    "supplierName": "Example Company Ltd",
    "nip": "5250001009",
    "city": "Warsaw",
    "street": null,
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true,
    "email": null,
    "phone": null
  },
  "lines": [
    {
      "id": null,
      "name": "Web Development Service",
      "unit": "pcs",
      "quantity": 1,
      "unitPriceNetto": "100.00",
      "vatType": "VAT_23",
      "discountValue": null,
      "discountPercentage": null,
      "priceNetto": "100.00",
      "priceVat": "23.0000",
      "priceBrutto": "123.0000"
    }
  ],
  "currency": "PLN",
  "comments": "Payment due within 30 days",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456",
  "file": {
    "publicUrl": null
  }
}

Notes:

• Provide exactly one of: invoicePatternId (configured per company) OR title.
• Dates: YYYY-MM-DD. Prices as strings with dot, e.g., "100.00".
• For paymentType = TRANSFER, requestedAccountNumber is required. Non-digits may be stripped.

Fields and constraints (summary)

• mainLanguage: enum PL, EN.
• secondLanguage: enum PL, EN (optional).
• type: enum VAT, PRO_FORMA, CORRECTION.
• title: string 1..254 (mutually exclusive with invoicePatternId).
• invoicePatternId: string 1..64 (mutually exclusive with title).
• invoiceDate, sellDate, paymentDate: YYYY-MM-DD (paymentDate: due date).
• createdBy: 1..64, invoiceCity: 1..128.
• supplier: object (if provided, supplierId is ignored).
• lines: array of items
  • name 1..1000, unit 1..64
  • quantity: positive decimal
  • unitPriceNetto: positive decimal (string), 2 fraction digits
  • vatType: enum VAT_23, VAT_22, VAT_8, VAT_7, VAT_5, VAT_4, VAT_3, VAT_0_KR, VAT_0_WDT, VAT_0_EX, VAT_ZW, VAT_OO, VAT_NP1, VAT_NP2 (required)
  • discountValue/discountPercentage: decimal (string), 2 fraction digits
• currency: 3 letters
• paymentStatus: enum TO_PAID, IN_PAYMENT, PAID, NOT_PAYABLE, NEW
• paymentType: enum TRANSFER, CASH, CARD, CREDIT_CARD, ONLINE
• requestedAccountNumber: required for TRANSFER.

Error handling

• 400 FIELDS_ERROR — validation issues (missing/invalid fields, whitespace-only).
• 500 — server error; recheck payload and server logs.

Get Invoice by ID

Retrieves an existing invoice by its unique identifier.

URL:

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

Headers:

clientApiId: <CLIENT_API_ID>

Curl:

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

Response (example):

{
  "mainLanguage": "PL",
  "secondLanguage": null,
  "type": "VAT",
  "title": "INV/12/09/2025",
  "invoiceDate": "2025-09-15",
  "sellDate": "2025-09-15",
  "invoiceCity": "Warsaw",
  "supplierId": null,
  "supplier": {
    "id": null,
    "supplierFirstname": null,
    "supplierName": "Example Company Ltd",
    "nip": "5250001009",
    "city": "Warsaw",
    "street": null,
    "postalCode": "00-001",
    "number": "1",
    "countryCode": "PL",
    "business": true,
    "email": null,
    "phone": null
  },
  "lines": [
    {
      "id": null,
      "name": "Web Development Service",
      "unit": "pcs",
      "quantity": 1,
      "unitPriceNetto": "100.00",
      "vatType": "VAT_23",
      "discountValue": null,
      "discountPercentage": null,
      "priceNetto": "100.00",
      "priceVat": "23.0000",
      "priceBrutto": "123.0000"
    }
  ],
  "currency": "PLN",
  "comments": "Payment due within 30 days",
  "paymentStatus": "TO_PAID",
  "paymentDate": "2025-10-01",
  "paymentType": "TRANSFER",
  "requestedAccountNumber": "12345678901234567890123456",
  "file": {
    "publicUrl": null
  }
}