### GET /products

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieve a list of products or details of a specific product.

```APIDOC
## GET /products.json

### Description
Retrieve a list of products, optionally filtered by warehouse.

### Method
GET

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/products.json

### Parameters
#### Query Parameters
- **api_token** (string) - Required - Your API authentication token
- **warehouse_id** (integer) - Optional - Filter products by warehouse ID

### Response
#### Success Response (200)
- **products** (array) - List of product objects
```

--------------------------------

### Retrieve Invoice Data

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Examples of how to fetch lists of invoices or specific invoice details using GET requests. Parameters like period, client_id, and include_positions allow for filtered results.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?period=this_month&api_token=API_TOKEN&page=1
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?include_positions=true&api_token=API_TOKEN&page=1
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?client_id=ID_KLIENTA&api_token=API_TOKEN
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.json?api_token=API_TOKEN
```

--------------------------------

### PHP Example: Course Purchase Workflow with BitFaktura

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

This outlines a workflow where a portal creates an invoice via BitFaktura API, sends it to a customer, and upon payment confirmation, issues a course ticket. The process involves API calls for invoice creation and payment status updates.

```php
// Portal collects customer data
// Portal calls BitFaktura API to create an invoice
// Portal sends PDF invoice with payment link to customer
// Customer pays the proforma invoice
// BitFaktura.com.ua processes payment, creates VAT invoice, notifies customer and portal API
// Portal receives payment confirmation via API and sends training ticket to customer
```

--------------------------------

### Manage Clients (GET, POST)

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Enables CRUD operations for managing client data, including listing clients with pagination, searching by name, email, or tax number, retrieving a client by ID, and creating new clients with detailed information. Requires API token.

```bash
# Список клієнтів з пагінацією
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&page=1"
```

```bash
# Пошук клієнтів
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&name=Компанія"
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&email=client@example.com"
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&tax_no=5252445767"
```

```bash
# Отримання клієнта за ID
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients/100.json?api_token=API_TOKEN"
```

```bash
# Отримання за зовнішнім ID
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?external_id=EXT123&api_token=API_TOKEN"
```

```bash
# Створення клієнта
curl https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "client": {
            "name": "ТОВ Новий Клієнт",
            "tax_no": "5252445767",
            "bank": "ПриватБанк",
            "bank_account": "UA213223130000026007233566001",
            "city": "Київ",
            "country": "UA",
            "email": "contact@newclient.ua",
            "person": "Іван Петренко",
            "post_code": "01001",
            "phone": "+380441234567",
            "street": "вул. Хрещатик 1"
        }
    }'
```

--------------------------------

### Handle Invoice Attachments (GET, POST)

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Provides endpoints for managing attachments to invoices. This includes downloading all attachments as a ZIP archive, obtaining credentials for uploading files, performing the upload, and finally linking the uploaded file to a specific invoice. Requires invoice ID and API token.

```bash
# Завантаження всіх вкладень у ZIP
curl -o attachments.zip "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100/attachments_zip.json?api_token=API_TOKEN"
```

```bash
# Крок 1: Отримання credentials для завантаження
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100/get_new_attachment_credentials.json?api_token=API_TOKEN"
```

```bash
# Крок 2: Завантаження файлу (використовуючи отримані credentials)
curl -F 'AWSAccessKeyId=received_AWSAccessKeyId' \
     -F 'key=received_key' \
     -F 'policy=received_policy' \
     -F 'signature=received_signature' \
     -F 'acl=received_acl' \
     -F 'success_action_status=received_success_action_status' \
     -F 'file=@/path/to/document.pdf' \
     received_url
```

```bash
# Крок 3: Прив'язка файлу до рахунка
curl -X POST "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100/add_attachment.json?api_token=API_TOKEN&file_name=document.pdf"
```

--------------------------------

### Account Management - Get Account Data

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieves data for the currently logged-in account. Requires the API token and optionally an integration token.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/account.json?api_token=API_TOKEN&integration_token=""
```

--------------------------------

### GET /clients

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieve a list of clients or search for specific clients by attributes.

```APIDOC
## GET /clients.json

### Description
Retrieve a list of clients or search by specific criteria.

### Method
GET

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json

### Parameters
#### Query Parameters
- **api_token** (string) - Required - Your API authentication token
- **page** (integer) - Optional - Page number for pagination
- **name** (string) - Optional - Search by client name
- **email** (string) - Optional - Search by email address
- **tax_no** (string) - Optional - Search by tax identification number

### Response
#### Success Response (200)
- **clients** (array) - List of client objects
```

--------------------------------

### Manage Departments - Get by ID

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Fetches details for a specific department using its unique identifier. Authentication is done via API token.

```bash
curl "http://YOUR_DOMAIN.bitfaktura.com.ua/departments/100.json?api_token=API_TOKEN"
```

--------------------------------

### Manage Recurring Invoices (GET, POST, PUT)

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Facilitates the management of recurring invoices, including retrieving a list, creating new ones with specified schedules (e.g., '1m' for monthly), and updating the next invoice date. Requires API token.

```bash
# Отримання списку періодичних рахунків
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings.json?api_token=API_TOKEN"
```

```bash
# Створення періодичного рахунка
curl https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "recurring": {
            "name": "Щомісячна підписка",
            "invoice_id": 1,
            "start_date": "2024-02-01",
            "every": "1m",
            "issue_working_day_only": false,
            "send_email": true,
            "buyer_email": "client@example.com",
            "end_date": null
        }
    }'
```

```bash
# Оновлення дати наступного рахунка
curl https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings/111.json \
    -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "recurring": {
            "next_invoice_date": "2024-03-01"
        }
    }'
```

--------------------------------

### Get Product by ID - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Fetches a specific product's details using its ID from the Bitfaktura API. Can also retrieve product information with warehouse stock levels by specifying a warehouse ID.

```bash
# Отримання продукту за ID
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products/100.json?api_token=API_TOKEN"

# Продукт з рівнем складу
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products/100.json?api_token=API_TOKEN&warehouse_id=1"
```

--------------------------------

### Manage Products via Bitfaktura API

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Demonstrates how to list, retrieve, create, and update product records. Note that net price is calculated automatically based on gross price and tax.

```shell
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products.json?api_token=API_TOKEN&page=1"
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products/100.json?api_token=API_TOKEN"
curl -X POST https://YOUR_DOMAIN.bitfaktura.com.ua/products.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "product": {"name": "PoroductAA", "price_net": "100", "tax": "23"}}'
curl -X PUT https://YOUR_DOMAIN.bitfaktura.com.ua/products/333.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "product": {"name": "PoroductAA2", "price_gross": "102", "tax": "23"}}'
```

--------------------------------

### Create Product - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new product in the Bitfaktura catalog via the API. Requires product details such as name, code, price, and tax. The net price is used for calculations.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/products.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "product": {
            "name": "Консалтингові послуги",
            "code": "CONS001",
            "price_net": "1000",
            "tax": "20"
        }
    }'
```

--------------------------------

### Get Recurring Invoices

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieves a list of defined recurring invoices.

```APIDOC
## GET /recurrings.json

### Description
Retrieves a list of recurring invoice definitions.

### Method
GET

### Endpoint
`https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings.json`

### Parameters
#### Query Parameters
- **api_token** (string) - Required - Your API token.

### Response
(Success response details not provided in the source text)
```

--------------------------------

### POST /products

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Create a new product record.

```APIDOC
## POST /products.json

### Description
Add a new product to the catalog.

### Method
POST

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/products.json

### Request Body
- **api_token** (string) - Required - Your API authentication token
- **product** (object) - Required - Product details including name, code, price_net, and tax.

### Request Example
{
  "api_token": "API_TOKEN",
  "product": {
    "name": "ProductAA",
    "code": "A001",
    "price_net": "100",
    "tax": "23"
  }
}
```

--------------------------------

### GET /invoices/{id}.json

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieve a specific invoice by its ID.

```APIDOC
## GET /invoices/{id}.json

### Description
Retrieves a single invoice specified by its unique identifier.

### Method
GET

### Endpoint
`/invoices/{id}.json`

### Path Parameters
- **id** (integer) - Required - The unique identifier of the invoice.

### Query Parameters
- **api_token** (string) - Required - Your API authentication token.

### Request Example
```json
GET /invoices/100.json?api_token=API_TOKEN
```

### Response
#### Success Response (200)
- **invoice** (object) - The invoice object with all its details.

#### Response Example
```json
{
  "invoice": {
    "id": 100,
    "number": "INV-001",
    "client_id": 1,
    "issue_date": "2023-01-01",
    "total_price_gross": 120.50,
    "positions": [
      {
        "name": "Product A1",
        "total_price_gross": 10.23,
        "quantity": 1
      }
    ]
  }
}
```
```

--------------------------------

### Create Price List - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new price list in Bitfaktura via the API. Includes details like name, description, currency, and associated product pricing. Supports defining multiple price list positions.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/price_lists.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "price_list": {
            "name": "Оптовий прайс",
            "description": "Ціни для оптових покупців",
            "currency": "UAH",
            "price_list_positions_attributes": {
                "0": {
                    "priceable_id": "1",
                    "priceable_name": "Продукт А",
                    "priceable_type": "Product",
                    "use_percentage": "0",
                    "percentage": "",
                    "price_net": "800.0",
                    "price_gross": "960.0",
                    "use_tax": "1",
                    "tax": "20"
                }
            }
        }
    }'
```

--------------------------------

### GET /invoices.json

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieve a list of invoices with various filtering and inclusion options.

```APIDOC
## GET /invoices.json

### Description
Retrieves a list of invoices. Supports filtering by period, inclusion of positions, and client ID.

### Method
GET

### Endpoint
`/invoices.json`

### Query Parameters
- **period** (string) - Optional - Filters invoices by a specified period (e.g., `this_month`).
- **include_positions** (boolean) - Optional - If true, includes detailed positions for each invoice.
- **client_id** (integer) - Optional - Filters invoices by a specific client ID.
- **api_token** (string) - Required - Your API authentication token.
- **page** (integer) - Optional - Specifies the page number for pagination.

### Request Example
```json
GET /invoices.json?period=this_month&api_token=API_TOKEN&page=1
GET /invoices.json?include_positions=true&api_token=API_TOKEN&page=1
GET /invoices.json?client_id=ID_KLIENTA&api_token=API_TOKEN
```

### Response
#### Success Response (200)
- **invoices** (array) - An array of invoice objects.
- **invoice** (object) - An invoice object containing details like ID, number, dates, client info, and positions (if `include_positions` is true).

#### Response Example
```json
{
  "invoices": [
    {
      "id": 100,
      "number": "INV-001",
      "client_id": 1,
      "issue_date": "2023-01-01",
      "total_price_gross": 120.50
    }
  ]
}
```
```

--------------------------------

### BitFaktura API Integration Overview

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

General guidelines and best practices for implementing the BitFaktura API for invoicing and synchronization.

```APIDOC
## API Integration Guidelines

### Description
This section outlines the best practices for integrating with the BitFaktura platform to ensure data integrity and smooth user experience.

### Implementation Best Practices
- **Unique Identification**: Always use the `oid_unique` field for orders to prevent duplicate invoice generation.
- **Status Tracking**: Configure webhook notifications to monitor payment statuses in real-time.
- **Error Handling**: Implement robust error handling with retry logic for network or API-level failures.
- **Seamless Auth**: Utilize `integration_fast_login` for partner integrations to allow users to access BitFaktura features without separate registration.

### Use Cases
- Automated invoicing for e-commerce orders.
- CRM synchronization for client management.
- Recurring billing and subscription management.
- Inventory and stock level synchronization.
```

--------------------------------

### GET /invoices

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieve a list of invoices from the system with support for pagination and filtering.

```APIDOC
## GET /invoices

### Description
Retrieve a list of invoices. Supports pagination and filtering by period or type.

### Method
GET

### Endpoint
/invoices.json?api_token={TOKEN}

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination (default: 1).
- **period** (string) - Optional - Filter by time period (e.g., 'this_month', 'last_year', 'all').
- **include_positions** (boolean) - Optional - Include invoice line items in the response.
- **income** (string) - Optional - Set to 'no' to retrieve expense invoices.

### Request Example
GET /invoices.json?api_token=YOUR_TOKEN&period=this_month&page=1

### Response
#### Success Response (200)
- **invoices** (array) - List of invoice objects.

#### Response Example
{
  "invoices": [
    {
      "id": 12345,
      "number": "FV/1/2023",
      "total": 100.00
    }
  ]
}
```

--------------------------------

### GET /invoices/{id}.pdf

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Download a PDF version of a specific invoice. Various print options are available.

```APIDOC
## GET /invoices/{id}.pdf

### Description
Download a PDF version of a specific invoice. Various print options are available.

### Method
GET

### Endpoint
/invoices/{id}.pdf

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the invoice to download.

#### Query Parameters
- **api_token** (string) - Required - Your API access token.
- **print_option** (string) - Optional - Specifies the print format. Allowed values: `original`, `copy`, `original_and_copy`, `duplicate`.

### Request Example
```bash
# Download PDF version
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.pdf?api_token=API_TOKEN" -o invoice.pdf

# PDF with different print options
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.pdf?api_token=API_TOKEN&print_option=original" -o original.pdf
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.pdf?api_token=API_TOKEN&print_option=copy" -o copy.pdf
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.pdf?api_token=API_TOKEN&print_option=original_and_copy" -o both.pdf
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.pdf?api_token=API_TOKEN&print_option=duplicate" -o duplicate.pdf
```
```

--------------------------------

### Update Recurring Invoice Definition

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Updates an existing recurring invoice definition, for example, to change the next issue date.

```APIDOC
## PUT /recurrings/{id}.json

### Description
Updates a recurring invoice definition.

### Method
PUT

### Endpoint
`https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings/{id}.json`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the recurring invoice definition to update.

#### Request Body
- **api_token** (string) - Required - Your API token.
- **recurring** (object) - Required - Details to update.
  - **next_invoice_date** (string) - Optional - The next date to issue the invoice (YYYY-MM-DD).

### Request Example
```json
{
    "api_token": "API_TOKEN",
    "recurring": {
        "next_invoice_date": "2016-02-01"
    }
}
```

### Response
(Success response details not provided in the source text)
```

--------------------------------

### Manage Clients via Bitfaktura API

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Demonstrates how to list, search, retrieve, create, update, and delete client records using cURL requests. Authentication is handled via an API token passed as a query parameter.

```shell
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&page=1"
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json?api_token=API_TOKEN&name=CLIENT_NAME"
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/clients/100.json?api_token=API_TOKEN"
curl -X POST https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "client": {"name": "Klient1", "tax_no": "5252445767"}}'
curl -X PUT https://YOUR_DOMAIN.bitfaktura.com.ua/clients/111.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "client": {"name": "Klient2"}}'
curl -X DELETE "https://YOUR_DOMAIN.bitfaktura.com.ua/clients/CLIENT_ID.json?api_token=API_TOKEN"
```

--------------------------------

### Programmatic Account Creation for Partners

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Create new BitFaktura accounts programmatically for partner integrations. Includes account, user, and company details.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/account.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "account": {"prefix": "newcompany", "lang": "ua", "integration_fast_login": true, "integration_logout_url": "https://yourportal.com/"}, "user": {"login": "admin", "email": "admin@newcompany.ua", "password": "securepassword123", "from_partner": "PARTNER_CODE"}, "company": {"name": "Нова Компанія ТОВ", "tax_no": "5252445700", "post_code": "01001", "city": "Київ", "street": "вул. Хрещатик 1", "person": "Іван Директор", "bank": "ПриватБанк", "bank_account": "UA213223130000026007233566001"}, "integration_token": ""}'

# Load account data
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/account.json?api_token=API_TOKEN&integration_token="
```

--------------------------------

### Authentication - User Login

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Authenticates a user with BitFaktura and retrieves an API token and account details. Requires login credentials and optionally an integration token.

```bash
curl https://app.bitfaktura.com.ua/login.json \
    -H 'Accept: application/json'  \
    -H 'Content-Type: application/json' \
    -d '{
            "login": "login_or_email",
            "password": "password",
	    "integration_token": ""
    }'
```

--------------------------------

### Get Category by ID - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Fetches details of a specific category using its unique ID. Requires the category ID and API token.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/categories/100.json?api_token=API_TOKEN"
```

--------------------------------

### POST /clients

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Create a new client record.

```APIDOC
## POST /clients.json

### Description
Add a new client to the system.

### Method
POST

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json

### Request Body
- **api_token** (string) - Required - Your API authentication token
- **client** (object) - Required - Client details including name, tax_no, email, etc.

### Request Example
{
  "api_token": "API_TOKEN",
  "client": {
    "name": "Klient1",
    "tax_no": "5252445767",
    "email": "email@gmail.com"
  }
}
```

--------------------------------

### Get Payment by ID - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Fetches details of a specific payment using its unique ID. Requires the payment ID and API token.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/banking/payment/100.json?api_token=API_TOKEN"
```

--------------------------------

### Manage Departments - List All

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Retrieves a list of all departments associated with your BitFaktura account. Requires your API token for authentication.

```bash
curl "http://YOUR_DOMAIN.bitfaktura.com.ua/departments.json?api_token=API_TOKEN"
```

--------------------------------

### Create Minimal Invoice

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new invoice using existing client and product IDs. It automatically sets the current date and payment deadline.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "invoice": {
            "payment_to_kind": 5,
            "client_id": 1,
            "department_id": 1,
            "positions": [
                {"product_id": 1, "quantity": 2},
                {"product_id": 2, "quantity": 1}
            ]
        }
    }'
```

--------------------------------

### GET /invoices.json

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Retrieve a list of invoices with support for pagination and filtering by period. You can also include invoice positions or filter by client ID.

```APIDOC
## GET /invoices.json

### Description
Retrieve a list of invoices with support for pagination and filtering by period. You can also include invoice positions or filter by client ID.

### Method
GET

### Endpoint
/invoices.json

### Parameters
#### Query Parameters
- **period** (string) - Optional - Filters invoices by a specific period. Allowed values: `this_month`, `last_month`, `this_year`, `last_year`, `last_30_days`, `last_12_months`, `all`, `more`.
- **include_positions** (boolean) - Optional - If true, includes detailed positions for each invoice.
- **client_id** (integer) - Optional - Filters invoices for a specific client.
- **date_from** (string) - Optional - Start date for filtering when `period` is `more`. Format: YYYY-MM-DD.
- **date_to** (string) - Optional - End date for filtering when `period` is `more`. Format: YYYY-MM-DD.
- **api_token** (string) - Required - Your API access token.
- **page** (integer) - Optional - Page number for pagination.

### Request Example
```bash
# Invoices for the current month
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?period=this_month&api_token=API_TOKEN&page=1"

# Invoices with positions
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?include_positions=true&api_token=API_TOKEN&page=1"

# Invoices for a specific client
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?client_id=123&api_token=API_TOKEN"

# Invoices for a specified date range
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json?period=more&date_from=2024-01-01&date_to=2024-01-31&api_token=API_TOKEN"
```

### Response
#### Success Response (200)
- **(Array of Invoice Objects)** - A list of invoice objects matching the query parameters.
```

--------------------------------

### GET /invoices/{id}.json

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Retrieve a specific invoice by its ID. This endpoint returns full invoice details, including a token for public access.

```APIDOC
## GET /invoices/{id}.json

### Description
Retrieve a specific invoice by its ID. This endpoint returns full invoice details, including a token for public access.

### Method
GET

### Endpoint
/invoices/{id}.json

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the invoice to retrieve.

#### Query Parameters
- **api_token** (string) - Required - Your API access token.

### Request Example
```bash
# Get invoice data in JSON format
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.json?api_token=API_TOKEN"
```

### Response
#### Success Response (200)
- **(Invoice Object)** - A detailed object representing the invoice.

#### Public Access
- **Preview**: `https://YOUR_DOMAIN.bitfaktura.com.ua/invoice/{token}`
- **PDF**: `https://YOUR_DOMAIN.bitfaktura.com.ua/invoice/{token}.pdf`
```

--------------------------------

### Account Management - Create New Account

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Creates a new BitFaktura account, typically for partners integrating their systems. Requires an API token and details for the account, user, and company.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/account.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
            "api_token": "API_TOKEN",
            "account": {
                "prefix": "prefix1",
		"lang": "pl"
            },
            "user": {
                "login": "login1",
                "email": "email1@email.pl",
                "password": "password1",
                "from_partner": "PARTNER_CODE"
            },
            "company": {
                "name": "Company1",
                "tax_no": "5252445700",
                "post_code": "00-112",
                "city": "Warsaw",
                "street": "Street 1/10",
                "person": "Jan Nowak",
                "bank": "Bank1",
                "bank_account": "111222333444555666111"
            },
	    "integration_token": ""
        }'
```

--------------------------------

### List Recurring Invoices using cURL

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

This snippet shows how to retrieve a list of all defined recurring invoices. It requires an API token and makes a GET request to the recurrings endpoint.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings.json?api_token=API_TOKEN
```

--------------------------------

### Get Warehouse Document by ID - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Fetches a specific warehouse document by its unique ID from Bitfaktura using the API. Requires the document ID and an API token.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/warehouse_documents/555.json?api_token=API_TOKEN"
```

--------------------------------

### Manage Departments - Create New

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Adds a new department to your BitFaktura account. This operation requires sending a JSON payload with department details and your API token.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/departments.json \
		-H 'Accept: application/json' \
		-H 'Content-Type: application/json' \
		-d '{
		"api_token": "API_TOKEN",
		"department": {
			"name":"my_warehouse",
			"shortcut": "short_name",
			"tax_no": "-"
		}}'
```

--------------------------------

### Create New Invoices

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Methods for creating invoices, ranging from full data submission to minimal creation using existing IDs for products and clients.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "invoice": {"kind":"vat", "positions":[{"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}]}}'
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "invoice": {"payment_to_kind": 5, "client_id": 1, "positions":[{"product_id": 1, "quantity":2}]}}'
```

--------------------------------

### Create Recurring Invoice Definition using cURL

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

This cURL command creates a new definition for a recurring invoice. It includes details such as the name, start date, frequency, and recipient information. An API token is required.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/recurrings.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"api_token": "API_TOKEN",
        "recurring": {
            "name": "Nazwa cyklicznosci",
            "invoice_id": 1,
            "start_date": "2016-01-01",
            "every": "1m",
            "issue_working_day_only": false,
            "send_email": true,
            "buyer_email": "mail1@mail.pl, mail2@mail.pl",
            "end_date": "null"
        }}'
```

--------------------------------

### Manage Price Lists via API

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Operations to list, create, update, and delete price lists. Requires an API token for authentication.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/price_lists.json?api_token=API_TOKEN"
```

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/price_lists.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "price_list": {"name": "Nazwa cennika", "description": "Opis", "currency": "PLN", "price_list_positions_attributes": {"0": {"priceable_id": "ID produktu", "priceable_name": "Nazwa produktu", "priceable_type": "Product", "use_percentage": "0", "percentage": "", "price_net": "111.0", "price_gross": "136.53", "use_tax": "1", "tax": "23"}}}}'
```

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/price_lists/100.json -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "price_list": {"name": "Nazwa cennika", "description": "Opis", "currency": "PLN"}}'
```

```bash
curl -X DELETE "https://YOUR_DOMAIN.bitfaktura.com.ua/price_lists/100.json?api_token=API_TOKEN"
```

--------------------------------

### POST /clients.json

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new client record in the database.

```APIDOC
## POST /clients.json

### Description
Adds a new client to the CRM database with detailed contact and billing information.

### Method
POST

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/clients.json

### Request Body
- **api_token** (string) - Required - Authentication token.
- **client** (object) - Required - Client details including name, tax_no, email, etc.

### Request Example
{
  "api_token": "API_TOKEN",
  "client": {
    "name": "Company Name",
    "email": "contact@example.com"
  }
}
```

--------------------------------

### Create Category - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new category for organizing data. Requires API token and category details, including name and description.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/categories.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "category": {
            "name": "IT послуги",
            "description": "Категорія для IT-послуг"
        }
    }'
```

--------------------------------

### List Products - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Retrieves a list of products from the Bitfaktura API. Supports pagination and filtering by warehouse ID to view products with stock levels.

```bash
# Список продуктів
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products.json?api_token=API_TOKEN&page=1"

# Продукти з залишками на складі
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/products.json?api_token=API_TOKEN&warehouse_id=1&page=1"
```

--------------------------------

### Authenticate with BitFaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Authenticates the user to obtain an API token and account URL. Requires login credentials and returns user details along with the necessary API token for subsequent requests.

```bash
curl https://app.bitfaktura.com.ua/login.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
            "login": "login_or_email",
            "password": "password",
            "integration_token": ""
    }'
```

--------------------------------

### Generate Invoice Preview and PDF Links (cURL)

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

This command fetches invoice data, including a token used to generate public links for invoice preview and PDF download. These links do not require user authentication.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/100.json?api_token=API_TOKEN
```

--------------------------------

### List All Categories - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Retrieves a list of all categories used for organizing invoices and products. Requires API token.

```bash
curl "https://YOUR_DOMAIN.bitfaktura.com.ua/categories.json?api_token=API_TOKEN"
```

--------------------------------

### Create Payment Linked to Invoices - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a payment and links it to one or more invoices, applying the payment sequentially to the specified invoices. Requires API token and payment details including invoice IDs.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/banking/payments.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "banking_payment": {
            "name": "Оплата за рахунки",
            "price": 7500.00,
            "invoice_ids": [555, 666],
            "paid": true,
            "kind": "api"
        }
    }'
```

--------------------------------

### Create Advanced Invoices

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

Creating invoices based on existing documents, including advance payments (by percentage or amount) and final invoices linked to previous advance payments.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "invoice": {"copy_invoice_from": ID_ZAMOWIENIA, "kind": "advance", "advance_creation_mode": "percent", "advance_value": "10"}}'
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"api_token": "API_TOKEN", "invoice": {"copy_invoice_from": ID_ZAMOWIENIA, "kind": "final", "invoice_ids": [ID_ZALICZKI_1, ID_ZALICZKI_2]}}'
```

--------------------------------

### Create Simple Payment - API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Registers a new payment record. Can be a standalone payment or linked to an invoice. Requires API token and payment details.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/banking/payments.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "banking_payment": {
            "name": "Оплата від клієнта",
            "price": 5000.00,
            "invoice_id": null,
            "paid": true,
            "kind": "api"
        }
    }'
```

--------------------------------

### Create Warehouse Document (Receipt) - Bitfaktura API

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Creates a new warehouse document of type 'pz' (receipt) in Bitfaktura via the API. This operation records the intake of goods and requires details like warehouse ID, issue date, supplier information, and a list of products with their purchase details.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/warehouse_documents.json \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "api_token": "API_TOKEN",
        "warehouse_document": {
            "kind": "pz",
            "number": null,
            "warehouse_id": "1",
            "issue_date": "2024-01-20",
            "department_name": "Основний відділ",
            "client_name": "Постачальник ТОВ",
            "warehouse_actions": [
                {"product_name": "Товар А", "purchase_tax": 20, "purchase_price_net": 100.00, "quantity": 50},
                {"product_name": "Товар Б", "purchase_tax": 20, "purchase_price_net": 200.00, "quantity": 30}
            ]
        }
    }'
```

--------------------------------

### Upload Attachment Credentials and File (cURL)

Source: https://github.com/bitfaktura-com-ua/api/blob/main/README.md

This process involves two steps: first, obtaining credentials to upload a file, and second, uploading the actual file using the obtained credentials. The file upload uses a multipart/form-data request.

```bash
curl https://YOUR_DOMAIN.bitfaktura.com.ua/invoices/INVOICE_ID/get_new_attachment_credentials.json?api_token=API_TOKEN
```

```bash
curl -F 'AWSAccessKeyId=received_AWSAccessKeyId' \
     -F 'key=received_key' \
     -F 'policy=received_policy' \
     -F 'signature=received_signature' \
     -F 'acl=received_acl' \
     -F 'success_action_status=received_success_action_status' \
     -F 'file=@/file_path/name.ext' \
     received_url
```

--------------------------------

### POST /invoices (Copy/Advance/Final)

Source: https://context7.com/bitfaktura-com-ua/api/llms.txt

Create invoices based on existing documents, including copying, advance, and final invoice generation.

```APIDOC
## POST /invoices.json

### Description
Generates new invoices based on existing ones (e.g., proforma to VAT, advance, or final invoices).

### Method
POST

### Endpoint
https://YOUR_DOMAIN.bitfaktura.com.ua/invoices.json

### Request Body
- **api_token** (string) - Required - Authentication token
- **invoice** (object) - Required - Contains 'copy_invoice_from' ID and 'kind' (vat, advance, final).

### Request Example
{
  "api_token": "API_TOKEN",
  "invoice": {
    "copy_invoice_from": 12345,
    "kind": "advance",
    "advance_creation_mode": "percent",
    "advance_value": "30"
  }
}
```