openapi: '3.0.3'
info:
  version: '1.0'
  title: Payper APIs
  description: "Payper APIs are used to communicate with the various capabilities of the system. For example, generate different types of documents and publish them, pull expenses, check for inventory and
    stock, etc.  \n<div>All functions are accessed from <b>https://app.payper.co.il/api/...</b></div>\n\n### Before You Begin\nTo use the API, configure the following settings in the Payper system under
    **Api Settings**:  \n<ol>\n  <li>Obtain your Company <b>api_key</b>.</li>\n  <li>Define an <b>api_user</b>.</li>\n  <li>Add your <b>IP address</b> to the allowed IPs list.</li>\n</ol>\n\n### Sandbox/Tests\nSandbox
    mode (applicable only to document generation) has the following behavior:  \n<ul>\n  <li>Documents are assigned the number '1'.</li>\n  <li>Documents will not be emailed.</li>\n</ul>  \n<b>Note:</b>
    Sandbox mode is enabled by default. When ready to generate real documents via the API, disable it in the **Api Settings**.\n"
servers:
- url: https://app.payper.co.il/api
  description: Production
tags:
- name: Generate documents
  description: Create invoices, proformas, bids, receipts, credits, purchase orders, and donation receipts.
- name: Finance
  description: Financial operations - expense retrieval, daily income reports, document uploads, and proforma cancellation.
- name: Customers
  description: Customer lookup, details, invoice history, pricing, and general ledger.
- name: Inventory
  description: Inventory management - stock levels, item details, supplier data, and purchase costs.
- name: Reseller Management
  description: Provisioning endpoints for resellers - create managed sub-companies (customers) with their admin user, license, and default settings. Requires a reseller-scoped api_key (the company must have management_type=reseller).
security:
- ApiKeyAuth: []
paths:
  /generate_invoice:
    x-summary: Create Invoice
    post:
      description: "This endpoint creates an **Invoice** (חשבונית מס) in the Payper system.\n\n> **Customer Identification:** At least one of `customer_unique_id`, `customer_mail`,\n> or `customer_system_id`
        is required. If no matching customer is found,\n> a new one is created (requires `customer_name`).\n\n#### Request Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n
        \ <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_name</td><td>string</td><td>For
        new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum (hb, en)</td><td>No (default:
        hb)</td></tr>\n  <tr><td>document_payment_due_date</td><td>date</td><td>No</td></tr>\n  <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>discount</td><td>float</td><td>No</td></tr>\n
        \ <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>send_by_mail</td><td>bool</td><td>No (default:
        false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n  <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>invoice_lines[]</td><td>array</td><td>Yes</td></tr>\n</table>\n<hr/>\n"
      summary: Create Invoice
      operationId: generateInvoice
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                document_payment_due_date:
                  type: string
                  format: date
                  description: The Document payment due date
                document_no_vat:
                  type: boolean
                  default: false
                  description: Don't add vat to price (default-false)
                discount:
                  type: number
                  default: false
                  description: Document discount before vat (default-none)
                discount_with_vat:
                  type: number
                  default: false
                  description: Document discount with vat (default-none)
                document_rounded:
                  type: boolean
                  default: false
                  description: Rounded invoice total for payment (default-false)
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: Array of JSON objects - each with Item name, quantity, and price per unit before VAT
                  items:
                    type: object
                    required:
                    - description
                    - quantity
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Name of the item
                        example: Office Chair
                      quantity:
                        type: number
                        description: Quantity of the item, supports integers or decimals
                        example: 3
                      price_per_unit:
                        type: number
                        description: Price per unit before VAT, supports integers or decimals
                        example: 250.75
                      discount:
                        type: number
                        description: Per unit discount in NIS
                        example: 15.5
                      include_vat:
                        type: boolean
                        description: 'Whether VAT is included (default: false)'
                        example: false
                      catalog_id:
                        type: string
                        description: 'Catalog ID of the item (default: Null)'
                        example: CAT12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: ILS
                      conversion_rate:
                        type: number
                        description: 'Currency rate (default: based on the exchange rate on invoice date)'
                        example: 3.7
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                  example:
                  - description: Office Chair
                    quantity: 3
                    price_per_unit: 250.75
                    discount: 15.5
                    include_vat: false
                    catalog_id: CAT12345
                    currency_symbol: ILS
                    conversion_rate: 3.7
                    conversion_date: 24-12-2024
                  - description: Desk Lamp
                    quantity: 2
                    price_per_unit: 150.0
                    include_vat: true
                    catalog_id: CAT67890
                    currency_symbol: USD
                    conversion_rate: 3.9
                    conversion_date: 25-12-2024
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  pay_invoice_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 142=invoice lines invalid, 143=line items invalid, 146=creation error, 147=duplicate,
                      167=already invoiced'
                  description:
                    type: string
  /generate_proforma:
    x-summary: Create Proforma
    post:
      description: "This endpoint creates a **Proforma Invoice** (חשבון עסקה) in the Payper system.\nA proforma can later be converted to an invoice or invoice-receipt using `reference_document_id`.\n\n####
        Request Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n
        \ <tr><td>customer_name</td><td>string</td><td>For new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n  <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum
        (hb, en)</td><td>No (default: hb)</td></tr>\n  <tr><td>document_payment_due_date</td><td>date</td><td>No</td></tr>\n  <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n
        \ <tr><td>discount</td><td>float</td><td>No</td></tr>\n  <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n
        \ <tr><td>send_by_mail</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n  <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n
        \ <tr><td>invoice_lines[]</td><td>array</td><td>Yes</td></tr>\n</table>\n<hr/>\n"
      summary: Create Proforma
      operationId: generateProforma
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                document_payment_due_date:
                  type: string
                  format: date
                  description: The Document payment due date
                document_no_vat:
                  type: boolean
                  default: false
                  description: Don't add vat to price (default-false)
                discount:
                  type: number
                  default: false
                  description: Document discount before vat (default-none)
                discount_with_vat:
                  type: number
                  default: false
                  description: Document discount with vat (default-none)
                document_rounded:
                  type: boolean
                  default: false
                  description: Rounded invoice total for payment (default-false)
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: Array of JSON objects - each with Item name, quantity, and price per unit before VAT
                  items:
                    type: object
                    required:
                    - description
                    - quantity
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Name of the item
                        example: Office Chair
                      quantity:
                        type: number
                        description: Quantity of the item, supports integers or decimals
                        example: 3
                      price_per_unit:
                        type: number
                        description: Price per unit before VAT, supports integers or decimals
                        example: 250.75
                      discount:
                        type: number
                        description: Per unit discount in NIS
                        example: 15.5
                      include_vat:
                        type: boolean
                        description: 'Whether VAT is included (default: false)'
                        example: false
                      catalog_id:
                        type: string
                        description: 'Catalog ID of the item (default: Null)'
                        example: CAT12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: ILS
                      conversion_rate:
                        type: number
                        description: 'Currency rate (default: based on the exchange rate on invoice date)'
                        example: 3.7
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                  example:
                  - description: Office Chair
                    quantity: 3
                    price_per_unit: 250.75
                    discount: 15.5
                    include_vat: false
                    catalog_id: CAT12345
                    currency_symbol: ILS
                    conversion_rate: 3.7
                    conversion_date: 24-12-2024
                  - description: Desk Lamp
                    quantity: 2
                    price_per_unit: 150.0
                    include_vat: true
                    catalog_id: CAT67890
                    currency_symbol: USD
                    conversion_rate: 3.9
                    conversion_date: 25-12-2024
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  pay_invoice_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 142=invoice lines invalid, 143=line items invalid, 146=creation error, 147=duplicate,
                      167=already invoiced'
                  description:
                    type: string
  /generate_bid:
    x-summary: Create Bid
    post:
      description: "This endpoint creates a **Price Quote / Bid** (הצעת מחיר) in the Payper system.\n\n#### Request Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n
        \ <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_name</td><td>string</td><td>For
        new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum (hb, en)</td><td>No (default:
        hb)</td></tr>\n  <tr><td>document_payment_due_date</td><td>date</td><td>No</td></tr>\n  <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>discount</td><td>float</td><td>No</td></tr>\n
        \ <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>send_by_mail</td><td>bool</td><td>No (default:
        false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n  <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>invoice_lines[]</td><td>array</td><td>Yes</td></tr>\n</table>\n<hr/>\n"
      summary: Create Bid
      operationId: generateBid
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                document_payment_due_date:
                  type: string
                  format: date
                  description: The Document payment due date
                document_no_vat:
                  type: boolean
                  default: false
                  description: Don't add vat to price (default-false)
                discount:
                  type: number
                  default: false
                  description: Document discount before vat (default-none)
                discount_with_vat:
                  type: number
                  default: false
                  description: Document discount with vat (default-none)
                document_rounded:
                  type: boolean
                  default: false
                  description: Rounded invoice total for payment (default-false)
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: Array of JSON objects - each with Item name, quantity, and price per unit before VAT
                  items:
                    type: object
                    required:
                    - description
                    - quantity
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Name of the item
                        example: Office Chair
                      quantity:
                        type: number
                        description: Quantity of the item, supports integers or decimals
                        example: 3
                      price_per_unit:
                        type: number
                        description: Price per unit before VAT, supports integers or decimals
                        example: 250.75
                      discount:
                        type: number
                        description: Per unit discount in NIS
                        example: 15.5
                      include_vat:
                        type: boolean
                        description: 'Whether VAT is included (default: false)'
                        example: false
                      catalog_id:
                        type: string
                        description: 'Catalog ID of the item (default: Null)'
                        example: CAT12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: ILS
                      conversion_rate:
                        type: number
                        description: 'Currency rate (default: based on the exchange rate on invoice date)'
                        example: 3.7
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                  example:
                  - description: Office Chair
                    quantity: 3
                    price_per_unit: 250.75
                    discount: 15.5
                    include_vat: false
                    catalog_id: CAT12345
                    currency_symbol: ILS
                    conversion_rate: 3.7
                    conversion_date: 24-12-2024
                  - description: Desk Lamp
                    quantity: 2
                    price_per_unit: 150.0
                    include_vat: true
                    catalog_id: CAT67890
                    currency_symbol: USD
                    conversion_rate: 3.9
                    conversion_date: 25-12-2024
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 142=invoice lines invalid, 143=line items invalid, 146=creation error, 147=duplicate,
                      167=already invoiced'
                  description:
                    type: string
  /generate_receipt:
    x-summary: Create Receipt
    post:
      description: "This endpoint creates a **Receipt** (קבלה) in the Payper system.\nReceipts require `receipt_lines` (payment details). `invoice_lines` are optional and are **not** stored as document lines — a קבלה records payments, not products.\n\nWhen `invoice_lines` carry a `catalog_id`, every item they reference must be marked for receipt issuance in the catalog (store document type = קבלה), otherwise the request is rejected with result **148**. The names of those items then become the document subject, unless `document_subject` was supplied. Lines without a `catalog_id` are not checked. This validation is skipped when `reference_document_id` is used.\n\n#### Request Parameters  \n<table>\n
        \ <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n
        \ <tr><td>customer_name</td><td>string</td><td>For new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n  <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum
        (hb, en)</td><td>No (default: hb)</td></tr>\n  <tr><td>reference_document_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>send_by_mail</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>receipt_lines[]</td><td>array</td><td>Yes (receipts only)</td></tr>\n  <tr><td>invoice_lines[]</td><td>array</td><td>No (not stored; see above)</td></tr>\n</table>\n<hr/>\n"
      summary: Create Receipt
      operationId: generateReceipt
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                reference_document_id:
                  type: integer
                  description: System id of Proforma OR Invoice to close
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: >-
                    Optional. NOT stored as document lines - a receipt records payments, not
                    products. Used only to name purchase-voucher items in the document subject
                    and to validate them. Every line carrying a catalog_id must reference an item
                    marked for receipt issuance in the catalog, otherwise the request is rejected
                    with result 148. Lines without a catalog_id are not checked. This validation
                    is skipped when reference_document_id is used.
                  items:
                    type: object
                    properties:
                      catalog_id:
                        type: string
                        description: 'Catalog ID (makat) of the purchased item (default: Null)'
                        example: TOKEN100
                      description:
                        type: string
                        description: Free-text line description (accepted, not stored on a receipt)
                        example: Gift voucher 100
                      price_per_unit:
                        type: number
                        description: Accepted, not stored on a receipt
                        example: 100
                receipt_lines:
                  type: array
                  description: Array of JSON objects - each with payment type, date, and amount
                  items:
                    type: object
                    required:
                    - payment_type
                    - date
                    - amount
                    - bank_name
                    - branch_num
                    - account_num
                    - cheque_num
                    properties:
                      payment_type:
                        type: string
                        enum:
                        - Cash
                        - Cc
                        - Cheque
                        - Bank_Transfer
                        - Paypal
                        - Bit
                        - Paybox
                        description: Type of payment method
                      date:
                        type: string
                        format: date
                        example: 24-12-2024
                        description: Payment date in dd-mm-yyyy format
                      amount:
                        type: number
                        description: Payment amount, supports integers and decimals
                        example: 150.75
                      bank_name:
                        type: string
                        description: Bank name or number, required for payment_type='Cheque'
                        example: Bank Hapoalim
                      branch_num:
                        type: string
                        description: Branch number, required for payment_type='Cheque'
                        example: '123'
                      account_num:
                        type: string
                        description: Account number, required for payment_type='Cheque'
                        example: '456789'
                      cheque_num:
                        type: string
                        description: Cheque number, required for payment_type='Cheque'
                        example: '00012345'
                      currency_symbol:
                        type: string
                        description: Currency symbol (default ILS)
                        example: ILS
                      conversion_rate:
                        type: number
                        description: Currency exchange rate (default by exchange rate on payment date or on conversion_date if provided)
                        example: 3.5
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                      cc_num:
                        type: string
                        pattern: "^[0-9]{4}$"
                        description: Last 4 digits of the credit card only - never send the full card number. Relevant for payment_type='Cc'
                        example: '1234'
                      cc_validity:
                        type: string
                        pattern: "^(0[1-9]|1[0-2])/[0-9]{4}$"
                        description: Credit card validity in MM/YYYY format, required for payment_type='CC'
                        example: 12/2025
                      cc_type:
                        type: integer
                        enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        description: Credit card type (0-Unknown, 1-Isracard, 2-Visa, 3-MasterCard, 4-American Express, 5-Diners, 6-Maestro)
                        example: 1
                      cc_payment_type:
                        type: integer
                        enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        description: >
                          Credit transaction type for payment_type='Cc'
                          (1-Payments, 2-Credit, 3-Debit declined, 4-Other).
                          0 (Standard) is the default and is ignored if sent.
                        example: 1
                      num_of_payments:
                        type: integer
                        minimum: 1
                        description: >
                          Number of installments for payment_type='Cc'.
                          Only applied when cc_payment_type is 1 (Payments) or 2 (Credit);
                          otherwise it is forced back to 1.
                        example: 3
                      proof_number:
                        type: string
                        description: Proof number for payment_type='CC'
                        example: '123456789'
                      app_transaction:
                        type: string
                        description: >
                          External transaction reference, for payment_type='Paypal', 'Bit' or 'Paybox'.
                          Shown on the document as the payment asmachta.
                        example: 5F84T2R9CD1234567
                  example:
                  - payment_type: Cc
                    date: 24-12-2024
                    amount: 150.75
                    currency_symbol: ILS
                    conversion_rate: 3.5
                    conversion_date: 24-12-2024
                    cc_num: '1234'
                    cc_validity: 12/2025
                    cc_type: 1
                    proof_number: '123456789'
                  - payment_type: Cheque
                    date: 24-12-2024
                    amount: 150.75
                    bank_name: '99'
                    branch_num: '123'
                    account_num: '456789'
                    cheque_num: '00012345'
                    currency_symbol: ILS
                  - payment_type: Cash
                    date: 25-12-2024
                    amount: 200
                    currency_symbol: ILS
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 144=receipt lines missing, 145=receipt line invalid, 146=creation error, 147=duplicate,
                      148=catalog item not valid for a receipt (unknown makat, or item not marked for receipt issuance), 167=already invoiced.
                      NOTE: every response is returned with HTTP status 200 - branch on the `result` field, not on the HTTP status.'
                  description:
                    type: string
  /generate_invoice_receipt:
    x-summary: Create Invoice-Receipt
    post:
      description: "This endpoint creates an **Invoice-Receipt** (חשבונית מס / קבלה) in the Payper system.\nThis combines an invoice and receipt into a single document. Requires both `invoice_lines`\nand
        `receipt_lines`.\n\n#### Request Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n
        \ <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_name</td><td>string</td><td>For new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n  <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum (hb, en)</td><td>No (default: hb)</td></tr>\n  <tr><td>reference_document_id</td><td>integer</td><td>No</td></tr>\n
        \ <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>discount</td><td>float</td><td>No</td></tr>\n  <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n
        \ <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>send_by_mail</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>invoice_lines[]</td><td>array</td><td>Yes</td></tr>\n  <tr><td>receipt_lines[]</td><td>array</td><td>Yes (receipts only)</td></tr>\n</table>\n<hr/>\n"
      summary: Create Invoice-Receipt
      operationId: generateInvoiceReceipt
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                reference_document_id:
                  type: integer
                  description: System id of Proforma (Only) to close, in this case no invoice lines needed
                document_no_vat:
                  type: boolean
                  default: false
                  description: Don't add vat to price (default-false)
                discount:
                  type: number
                  default: false
                  description: Document discount before vat (default-none)
                discount_with_vat:
                  type: number
                  default: false
                  description: Document discount with vat (default-none)
                document_rounded:
                  type: boolean
                  default: false
                  description: Rounded invoice total for payment (default-false)
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: Array of JSON objects - each with Item name, quantity, and price per unit before VAT
                  items:
                    type: object
                    required:
                    - description
                    - quantity
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Name of the item
                        example: Office Chair
                      quantity:
                        type: number
                        description: Quantity of the item, supports integers or decimals
                        example: 3
                      price_per_unit:
                        type: number
                        description: Price per unit before VAT, supports integers or decimals
                        example: 250.75
                      discount:
                        type: number
                        description: Per unit discount in NIS
                        example: 15.5
                      include_vat:
                        type: boolean
                        description: 'Whether VAT is included (default: false)'
                        example: false
                      catalog_id:
                        type: string
                        description: 'Catalog ID of the item (default: Null)'
                        example: CAT12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: ILS
                      conversion_rate:
                        type: number
                        description: 'Currency rate (default: based on the exchange rate on invoice date)'
                        example: 3.7
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                  example:
                  - description: Office Chair
                    quantity: 3
                    price_per_unit: 250.75
                    discount: 15.5
                    include_vat: false
                    catalog_id: CAT12345
                    currency_symbol: ILS
                    conversion_rate: 3.7
                    conversion_date: 24-12-2024
                  - description: Desk Lamp
                    quantity: 2
                    price_per_unit: 150.0
                    include_vat: true
                    catalog_id: CAT67890
                    currency_symbol: USD
                    conversion_rate: 3.9
                    conversion_date: 25-12-2024
                receipt_lines:
                  type: array
                  description: Array of JSON objects - each with payment type, date, and amount
                  items:
                    type: object
                    required:
                    - payment_type
                    - date
                    - amount
                    - bank_name
                    - branch_num
                    - account_num
                    - cheque_num
                    properties:
                      payment_type:
                        type: string
                        enum:
                        - Cash
                        - Cc
                        - Cheque
                        - Bank_Transfer
                        - Paypal
                        - Bit
                        - Paybox
                        description: Type of payment method
                      date:
                        type: string
                        format: date
                        example: 24-12-2024
                        description: Payment date in dd-mm-yyyy format
                      amount:
                        type: number
                        description: Payment amount, supports integers and decimals
                        example: 150.75
                      bank_name:
                        type: string
                        description: Bank name or number, required for payment_type='Cheque'
                        example: Bank Hapoalim
                      branch_num:
                        type: string
                        description: Branch number, required for payment_type='Cheque'
                        example: '123'
                      account_num:
                        type: string
                        description: Account number, required for payment_type='Cheque'
                        example: '456789'
                      cheque_num:
                        type: string
                        description: Cheque number, required for payment_type='Cheque'
                        example: '00012345'
                      currency_symbol:
                        type: string
                        description: Currency symbol (default ILS)
                        example: ILS
                      conversion_rate:
                        type: number
                        description: Currency exchange rate (default by exchange rate on payment date or on conversion_date if provided)
                        example: 3.5
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                      cc_num:
                        type: string
                        pattern: "^[0-9]{4}$"
                        description: Last 4 digits of the credit card only - never send the full card number. Relevant for payment_type='Cc'
                        example: '1234'
                      cc_validity:
                        type: string
                        pattern: "^(0[1-9]|1[0-2])/[0-9]{4}$"
                        description: Credit card validity in MM/YYYY format, required for payment_type='CC'
                        example: 12/2025
                      cc_type:
                        type: integer
                        enum:
                        - 0
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        description: Credit card type (0-Unknown, 1-Isracard, 2-Visa, 3-MasterCard, 4-American Express, 5-Diners, 6-Maestro)
                        example: 1
                      cc_payment_type:
                        type: integer
                        enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        description: >
                          Credit transaction type for payment_type='Cc'
                          (1-Payments, 2-Credit, 3-Debit declined, 4-Other).
                          0 (Standard) is the default and is ignored if sent.
                        example: 1
                      num_of_payments:
                        type: integer
                        minimum: 1
                        description: >
                          Number of installments for payment_type='Cc'.
                          Only applied when cc_payment_type is 1 (Payments) or 2 (Credit);
                          otherwise it is forced back to 1.
                        example: 3
                      proof_number:
                        type: string
                        description: Proof number for payment_type='CC'
                        example: '123456789'
                      app_transaction:
                        type: string
                        description: >
                          External transaction reference, for payment_type='Paypal', 'Bit' or 'Paybox'.
                          Shown on the document as the payment asmachta.
                        example: 5F84T2R9CD1234567
                  example:
                  - payment_type: Cc
                    date: 24-12-2024
                    amount: 150.75
                    currency_symbol: ILS
                    conversion_rate: 3.5
                    conversion_date: 24-12-2024
                    cc_num: '1234'
                    cc_validity: 12/2025
                    cc_type: 1
                    proof_number: '123456789'
                  - payment_type: Cheque
                    date: 24-12-2024
                    amount: 150.75
                    bank_name: '99'
                    branch_num: '123'
                    account_num: '456789'
                    cheque_num: '00012345'
                    currency_symbol: ILS
                  - payment_type: Cash
                    date: 25-12-2024
                    amount: 200
                    currency_symbol: ILS
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 142=invoice lines invalid, 143=line items invalid, 146=creation error, 147=duplicate,
                      167=already invoiced'
                  description:
                    type: string
  /generate_credit:
    x-summary: Create Credit
    post:
      description: "This endpoint creates a **Credit Note** (חשבונית זיכוי) in the Payper system.\nUse `reference_document_id` to link the credit to the original invoice.\n\n#### Request Parameters  \n<table>\n
        \ <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>customer_unique_id</td><td>string</td><td>Conditional*</td></tr>\n  <tr><td>customer_mail</td><td>string</td><td>Conditional*</td></tr>\n
        \ <tr><td>customer_name</td><td>string</td><td>For new customer</td></tr>\n  <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>customer_business_phone</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>customer_address</td><td>string</td><td>No</td></tr>\n  <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum
        (hb, en)</td><td>No (default: hb)</td></tr>\n  <tr><td>reference_document_id</td><td>integer</td><td>No</td></tr>\n  <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n
        \ <tr><td>discount</td><td>float</td><td>No</td></tr>\n  <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n
        \ <tr><td>send_by_mail</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No</td></tr>\n  <tr><td>income_id</td><td>integer</td><td>No</td></tr>\n
        \ <tr><td>invoice_lines[]</td><td>array</td><td>Yes</td></tr>\n</table>\n<hr/>\n"
      summary: Create Credit
      operationId: generateCredit
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id
                customer_name:
                  type: string
                  description: The Customer full name, required for new customer
                customer_mobile:
                  type: string
                  description: The Customer mobile phone number
                customer_business_phone:
                  type: string
                  description: The Customer business phone number
                customer_address:
                  type: string
                  description: The Customer full address
                customer_city:
                  type: string
                  description: The Customer city
                customer_home_number:
                  type: string
                  description: The Customer house/building number
                customer_zip_code:
                  type: string
                  description: The Customer zip code
                customer_system_id:
                  type: integer
                  description: System ID of an existing customer (alternative to customer_unique_id)
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark customer as overseas (non-Israeli). Bypasses Israeli ID/business number validation, defaults document language to English, and defaults VAT to 0. Use this when the customer has no valid Israeli ID. When true, customer_unique_id can be left blank or contain any non-Israeli format.
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date in YYYY-MM-DD format (default today)
                  example: '2026-03-27'
                order_id:
                  type: string
                  description: External order reference ID for linking to source system
                document_subject:
                  type: string
                  description: The Document subject
                document_remarks:
                  type: string
                  description: The Document remarks
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: The Document language options are as follows | English-en | Hebrew-hb (default)
                reference_document_id:
                  type: integer
                  description: System id of Invoice OR Invoice-Receipt (Only) to close, in this case no reference document lines needed
                document_no_vat:
                  type: boolean
                  default: false
                  description: Don't add vat to price (default-false)
                discount:
                  type: number
                  default: false
                  description: Document discount before vat (default-none)
                discount_with_vat:
                  type: number
                  default: false
                  description: Document discount with vat (default-none)
                document_rounded:
                  type: boolean
                  default: false
                  description: Rounded invoice total for payment (default-false)
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send the document by mail to the customer NOTE customer must have email address (default-false)
                extra_recipients:
                  type: string
                  description: Add recipients to document mail comma separated (relevant if send_by_mail set to true)
                  example: test@test.com,test2@test.com
                income_id:
                  type: integer
                  description: Categories the invoice with income type (For supported company only, income id can be obtained from the system settings)
                invoice_lines:
                  type: array
                  description: Array of JSON objects - each with Item name, quantity, and price per unit before VAT
                  items:
                    type: object
                    required:
                    - description
                    - quantity
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Name of the item
                        example: Office Chair
                      quantity:
                        type: number
                        description: Quantity of the item, supports integers or decimals
                        example: 3
                      price_per_unit:
                        type: number
                        description: Price per unit before VAT, supports integers or decimals
                        example: 250.75
                      discount:
                        type: number
                        description: Per unit discount in NIS
                        example: 15.5
                      include_vat:
                        type: boolean
                        description: 'Whether VAT is included (default: false)'
                        example: false
                      catalog_id:
                        type: string
                        description: 'Catalog ID of the item (default: Null)'
                        example: CAT12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: ILS
                      conversion_rate:
                        type: number
                        description: 'Currency rate (default: based on the exchange rate on invoice date)'
                        example: 3.7
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                        example: 24-12-2024
                  example:
                  - description: Office Chair
                    quantity: 3
                    price_per_unit: 250.75
                    discount: 15.5
                    include_vat: false
                    catalog_id: CAT12345
                    currency_symbol: ILS
                    conversion_rate: 3.7
                    conversion_date: 24-12-2024
                  - description: Desk Lamp
                    quantity: 2
                    price_per_unit: 150.0
                    include_vat: true
                    catalog_id: CAT67890
                    currency_symbol: USD
                    conversion_rate: 3.9
                    conversion_date: 25-12-2024
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error (see result code for details)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: 'Error codes: 130=customer/provider missing, 133=new customer name required, 134=not found, 142=invoice lines invalid, 143=line items invalid, 146=creation error, 147=duplicate,
                      167=already invoiced'
                  description:
                    type: string
  /generate_purchase_order:
    x-summary: Create Purchase Order
    post:
      summary: Create Purchase Order
      operationId: generatePurchaseOrder
      description: "This endpoint creates a Purchase Order (PO) in the Payper system.\n#### Provider Identification\nAt least one of the following must be provided to identify the provider:\n- `provider_system_id`
        - Existing provider ID in the system\n- `provider_business_num` - Provider tax ID for lookup or creation\n- `provider_name` + `provider_business_num` - Required together to create a new provider\n\n####
        Request Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>provider_system_id</td><td>integer</td><td>One of provider identifiers required</td></tr>\n
        \ <tr><td>provider_business_num</td><td>string</td><td>Required for new provider</td></tr>\n  <tr><td>provider_name</td><td>string</td><td>Required for new provider</td></tr>\n  <tr><td>provider_email</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>provider_mobile</td><td>string</td><td>No</td></tr>\n  <tr><td>provider_business_phone</td><td>string</td><td>No</td></tr>\n  <tr><td>po_contact_name</td><td>string</td><td>No</td></tr>\n
        \ <tr><td>po_contact_phone</td><td>string</td><td>No</td></tr>\n  <tr><td>po_contact_email</td><td>string</td><td>No</td></tr>\n  <tr><td>po_contact_pid</td><td>string</td><td>No</td></tr>\n  <tr><td>document_lang</td><td>enum
        (hb, en)</td><td>No (default: hb)</td></tr>\n  <tr><td>document_remarks</td><td>string</td><td>No</td></tr>\n  <tr><td>document_subject</td><td>string</td><td>No</td></tr>\n  <tr><td>document_payment_due_date</td><td>date</td><td>No</td></tr>\n
        \ <tr><td>document_no_vat</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>document_rounded</td><td>bool</td><td>No (default: false)</td></tr>\n  <tr><td>discount</td><td>float</td><td>No
        (before vat)</td></tr>\n  <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>order_id</td><td>string</td><td>No (external order reference)</td></tr>\n  <tr><td>send_by_mail</td><td>bool</td><td>No
        (default: false)</td></tr>\n  <tr><td>extra_recipients</td><td>string</td><td>No (comma-separated emails)</td></tr>\n  <tr><td>invoice_lines</td><td>array</td><td>Yes</td></tr>\n</table>\n\n####
        Invoice Lines Parameters  \n<table>\n  <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>\n  <tr><td>description</td><td>string</td><td>Yes</td></tr>\n  <tr><td>price_per_unit</td><td>float</td><td>Yes</td></tr>\n
        \ <tr><td>quantity</td><td>float</td><td>No (default: 1)</td></tr>\n  <tr><td>no_vat</td><td>bool</td><td>No</td></tr>\n  <tr><td>include_vat</td><td>bool</td><td>No</td></tr>\n  <tr><td>discount</td><td>float</td><td>No
        (in NIS)</td></tr>\n  <tr><td>discount_with_vat</td><td>float</td><td>No</td></tr>\n  <tr><td>catalog_id</td><td>string</td><td>No (makat of catalog item)</td></tr>\n  <tr><td>currency_symbol</td><td>string</td><td>No
        (ILS, USD, EUR)</td></tr>\n  <tr><td>conversion_rate</td><td>float</td><td>No</td></tr>\n  <tr><td>conversion_date</td><td>date</td><td>No (dd-mm-yyyy)</td></tr>\n  <tr><td>supply_date</td><td>date</td><td>No
        (expected delivery date)</td></tr>\n</table>\n"
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              - invoice_lines
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings
                provider_system_id:
                  type: integer
                  description: System ID of an existing provider
                provider_business_num:
                  type: string
                  description: Provider tax ID (business number) for lookup or new provider creation
                provider_name:
                  type: string
                  description: Provider name (required when creating a new provider)
                provider_email:
                  type: string
                  description: Provider email address
                provider_mobile:
                  type: string
                  description: Provider mobile phone
                provider_business_phone:
                  type: string
                  description: Provider business phone
                po_contact_name:
                  type: string
                  description: PO contact person name
                po_contact_phone:
                  type: string
                  description: PO contact person phone
                po_contact_email:
                  type: string
                  description: PO contact person email
                po_contact_pid:
                  type: string
                  description: PO contact person ID number
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                  description: Document language (hb=Hebrew, en=English)
                document_remarks:
                  type: string
                  description: Document remarks
                document_subject:
                  type: string
                  description: Document subject line
                document_payment_due_date:
                  type: string
                  format: date
                  description: Payment due date
                invoice_date:
                  type: string
                  format: date
                  description: Invoice date (default today)
                document_no_vat:
                  type: boolean
                  default: false
                  description: No VAT on document (default false)
                discount:
                  type: number
                  description: Document discount before VAT in NIS
                discount_with_vat:
                  type: number
                  description: Document discount including VAT in NIS
                order_id:
                  type: string
                  description: External order reference ID
                send_by_mail:
                  type: boolean
                  default: false
                  description: Send document by email to the provider (default false)
                extra_recipients:
                  type: string
                  description: Comma-separated list of additional email recipients
                invoice_lines:
                  type: array
                  description: List of order line items (at least one required)
                  items:
                    type: object
                    required:
                    - description
                    - price_per_unit
                    properties:
                      description:
                        type: string
                        description: Line item description
                        example: Office Chair
                      price_per_unit:
                        type: number
                        description: Price per unit (required, must be numeric)
                        example: 250.75
                      quantity:
                        type: number
                        description: 'Quantity (default: 1)'
                        example: 10
                      no_vat:
                        type: boolean
                        description: 'No VAT on this line (default: false)'
                      include_vat:
                        type: boolean
                        description: 'Price includes VAT (default: false)'
                      discount:
                        type: number
                        description: Line discount in NIS
                        example: 15.5
                      discount_with_vat:
                        type: number
                        description: Line discount including VAT in NIS
                      catalog_id:
                        type: string
                        description: Catalog item ID (makat) to link this line to a product
                        example: SKU12345
                      currency_symbol:
                        type: string
                        description: 'Currency symbol (default: ILS)'
                        example: USD
                      conversion_rate:
                        type: number
                        description: 'Currency exchange rate (default: exchange rate on invoice date)'
                        example: 3.65
                      conversion_date:
                        type: string
                        format: date
                        description: Currency exchange date in dd-mm-yyyy format
                      supply_date:
                        type: string
                        format: date
                        description: Expected delivery date for this line item
                        example: 15-04-2026
                  example:
                  - description: Office Chair
                    quantity: 10
                    price_per_unit: 250.75
                    catalog_id: SKU12345
                    supply_date: 15-04-2026
                  - description: Monitor Stand
                    quantity: 5
                    price_per_unit: 89.9
                    currency_symbol: USD
                    conversion_rate: 3.65
      parameters:
      - name: API_KEY
        in: header
        required: true
        description: Company API key
        schema:
          type: string
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted PO document number
                  document_system_id:
                    type: integer
                    description: Internal system ID of the created PO
                  document_link:
                    type: string
                    description: Public URL to view/download the PO document
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /generate_donation_receipt:
    x-summary: Create Donation Receipt
    post:
      operationId: generateDonationReceipt
      description: |
        This endpoint creates a **Donation Receipt** (קבלה על תרומה) in the Payper system.
        Donation receipts are similar to standard receipts but are designated for charitable donations
        and comply with Israeli tax authority requirements for Section 46 donations.
        #### Customer Identification
        At least one of `customer_unique_id`, `customer_mail`, or `customer_system_id` is required.
        #### Request Parameters
        <table>
          <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>
          <tr><td>customer_unique_id</td><td>string</td><td>Yes (or customer_mail/customer_system_id)</td></tr>
          <tr><td>customer_mail</td><td>string</td><td>Yes (or customer_unique_id/customer_system_id)</td></tr>
          <tr><td>customer_name</td><td>string</td><td>Required for new customer</td></tr>
          <tr><td>customer_mobile</td><td>string</td><td>No</td></tr>
          <tr><td>customer_address</td><td>string</td><td>No</td></tr>
          <tr><td>customer_system_id</td><td>integer</td><td>No (alternative identifier)</td></tr>
          <tr><td>document_lang</td><td>enum (hb, en)</td><td>No (default: hb)</td></tr>
          <tr><td>document_subject</td><td>string</td><td>No</td></tr>
          <tr><td>document_remarks</td><td>string</td><td>No</td></tr>
          <tr><td>send_by_mail</td><td>bool</td><td>No (default: false)</td></tr>
          <tr><td>invoice_lines</td><td>array</td><td>Yes</td></tr>
          <tr><td>receipt_lines</td><td>array</td><td>Yes</td></tr>
        </table>
        <hr/>
      summary: Create Donation Receipt
      tags:
      - Generate documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              - invoice_lines
              - receipt_lines
              properties:
                api_user:
                  type: string
                  description: API user email
                customer_unique_id:
                  type: string
                  description: Donor business number or personal ID
                customer_mail:
                  type: string
                  description: Donor email address
                customer_name:
                  type: string
                  description: Donor full name (required for new donor)
                customer_system_id:
                  type: integer
                  description: Existing donor system ID
                customer_is_overseas:
                  type: boolean
                  default: false
                  description: Mark donor as overseas (non-Israeli). Bypasses Israeli ID validation. Use this when the donor has no valid Israeli ID.
                document_lang:
                  type: string
                  enum:
                  - hb
                  - en
                  default: hb
                document_subject:
                  type: string
                document_remarks:
                  type: string
                send_by_mail:
                  type: boolean
                  default: false
                invoice_lines:
                  type: array
                  description: Donation line items
                  items:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Donation
                      price_per_unit:
                        type: number
                        example: 500
                      quantity:
                        type: number
                        default: 1
                receipt_lines:
                  type: array
                  description: Payment details for the donation
                  items:
                    type: object
                    properties:
                      payment_type:
                        type: string
                        enum:
                        - cash
                        - cc
                        - cheque
                        - bank_transfer
                        - bit
                        - paypal
                      amount:
                        type: number
                      date:
                        type: string
                        format: date
                        description: Payment date (YYYY-MM-DD)
                      cc_num:
                        type: string
                        pattern: "^[0-9]{4}$"
                        description: >
                          Last 4 digits of the credit card only - never send the full card number.
                          Mandatory for payment_type='cc' on donation receipts: the value is reported
                          to the Tax Authority Open API as Last_4_credit_card_digits.
                        example: '1234'
                      cc_payment_type:
                        type: integer
                        enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        description: >
                          Credit transaction type for payment_type='cc'
                          (1-Payments, 2-Credit, 3-Debit declined, 4-Other).
                          0 (Standard) is the default and is ignored if sent.
                          Reported to the Tax Authority Open API as Credit_transaction_type.
                        example: 1
                      num_of_payments:
                        type: integer
                        minimum: 1
                        description: >
                          Number of installments for payment_type='cc'.
                          Only applied when cc_payment_type is 1 (Payments) or 2 (Credit);
                          otherwise it is forced back to 1.
                        example: 3
                      app_transaction:
                        type: string
                        description: >
                          External transaction reference, for payment_type='paypal' or 'bit'.
                          Shown on the document as the payment asmachta.
                        example: 5F84T2R9CD1234567
      responses:
        '200':
          description: Donation receipt created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: Formatted document number (e.g. "001-2026")
                  document_system_id:
                    type: integer
                  document_link:
                    type: string
                  thermal_link:
                    type: string
                    description: |
                      Direct link to an 80mm thermal-receipt PDF of the document.
                      Returned only when the issuing company has the
                      `enable_thermal_print` flag turned on in its invoice settings.
                      Suitable for printing directly to a thermal/POS receipt printer.
                      Append `&bw=1` (or `&bw=true`) to receive a monochrome/B&W
                      version of the same document — useful for thermal printers
                      that render colors as gray.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                  description:
                    type: string
  /invoice_upload:
    x-summary: Invoice Upload
    post:
      description: |
        This endpoint uploads an **expense document** (invoice scan, PDF, or image) to the Payper system
        for OCR processing. Accepted file types: **pdf**, **png**, **jpg**, **jpeg**.

        Either `file_url` (accessible URL) or `base64` (encoded content) must be provided.
        The document will be processed asynchronously via OCR.
        <hr/>
      summary: Send digital invoice
      operationId: invoiceUpload
      tags:
      - Finance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - file_name
              - file_url
              - base64
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                file_name:
                  type: string
                  description: 'The file name + extension (Can be one of the following: ''.pdf'',''.png'',''.jpg'',''.jpeg'')'
                file_url:
                  type: string
                  description: Accessible URL of the invoice (Not required if passing base64)
                base64:
                  type: string
                  description: The invoice as base64 string (Not required if passing file_url)
                remote_id:
                  type: string
                  description: ID to be returned on webhooks and pull_expenses end point
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_system_id:
                    type: integer
                    description: System ID of the uploaded document
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: |
                      Error codes:
                      - **909** — File name not valid (must be name.extension)
                      - **910** — File name missing
                      - **911** — File type not valid (accepts: pdf, png, jpg, jpeg)
                      - **912** — File URL or base64 content missing
                      - **915** — Error receiving/downloading file
                  description:
                    type: string
  /retrieve_customer:
    x-summary: Get customer system id
    post:
      description: "This endpoint retrieves a customer's Payper system ID using their email, mobile, or business number. Useful for verifying customer existence or for use in other API calls.  \n<hr/>\n"
      summary: Get customer system id
      operationId: retrieveCustomer
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_unique_id
              - customer_mail
              - customer_mobile
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail or customer_mobile
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id or customer_mobile
                customer_mobile:
                  type: string
                  description: The Customer main mobile phone, required if no customer_unique_id or customer_mail
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  customer_system_id:
                    type: string
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /get_customer_details:
    x-summary: Get customer details
    post:
      description: "This endpoint retrieves customer details using one identifier (system\
        \ ID, business number, email, or mobile) or searches active customers by partial\
        \ name.  \nProvide exactly ONE of: `system_id`, `customer_unique_id`, `customer_mail`,\
        \ `customer_mobile` — OR — `customer_name` (min 2 characters, partial match).\
        \  \nWhen `customer_name` is supplied the response returns a paginated list\
        \ (`result_type: \"list\"`); all other identifiers return a single record\
        \ (`result_type: \"single\"`).  \n<hr/>\n"
      summary: Get customer details
      operationId: getCustomerDetails
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                system_id:
                  type: string
                  description: The Customer system id (can be retrieved by 'retrieve_customer'
                    endpoint). Provide one identifier or customer_name.
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number.
                    Provide one identifier or customer_name.
                customer_mail:
                  type: string
                  description: The Customer main email address. Provide one identifier
                    or customer_name.
                customer_mobile:
                  type: string
                  description: The Customer main mobile phone. Provide one identifier
                    or customer_name.
                customer_name:
                  type: string
                  minLength: 2
                  description: Partial name search (min 2 chars). Active customers
                    only. Returns a paginated list. Use `page` to paginate (25 per
                    page).
                page:
                  type: integer
                  default: 1
                  description: Page number for customer_name list results (25 per
                    page).
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                oneOf:
                - title: Single customer result
                  type: object
                  properties:
                    result:
                      type: string
                      default: '200'
                    description:
                      type: string
                      default: Success
                    result_type:
                      type: string
                      enum:
                      - single
                      description: Indicates a single-customer response.
                    customer_system_id:
                      type: string
                    name:
                      type: string
                    business_num:
                      type: string
                    email:
                      type: string
                    mobile:
                      type: string
                    business_phone:
                      type: string
                    country:
                      type: string
                    city:
                      type: string
                    address:
                      type: string
                    home_number:
                      type: string
                    zip_code:
                      type: string
                    customer_contacts:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          phone_number:
                            type: string
                          email:
                            type: string
                          city:
                            type: string
                          address:
                            type: string
                          home_number:
                            type: string
                - title: Customer list result
                  type: object
                  properties:
                    result:
                      type: string
                      default: '200'
                    description:
                      type: string
                      default: Success
                    result_type:
                      type: string
                      enum:
                      - list
                      description: Indicates a paginated list response (returned when
                        searching by customer_name).
                    customers:
                      type: array
                      description: Active customers matching the name search. Empty
                        array when no matches found.
                      items:
                        type: object
                        properties:
                          customer_system_id:
                            type: string
                          name:
                            type: string
                          business_num:
                            type: string
                          city:
                            type: string
                          address:
                            type: string
                          business_phone:
                            type: string
                          mobile:
                            type: string
                          contacts:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                phone_number:
                                  type: string
                                email:
                                  type: string
                    total_results:
                      type: integer
                      description: Total number of matching active customers.
                    total_pages:
                      type: integer
                      description: Total pages (present when more than one page).
                    current_page:
                      type: integer
                      description: Current page number (present when more than one
                        page).
                discriminator:
                  propertyName: result_type
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /customer_invoices:
    x-summary: Get customer invoices from given date
    post:
      description: "This endpoint retrieves customer invoices from a specified date, identified by <b>customer_system_id</b> or <b>customer_unique_id</b>.  \nExactly one of the two must be supplied - a request with neither returns error 155 (Customer details missing).  \n<hr/>\n"
      summary: Get customer invoices
      operationId: customerInvoices
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                from_date:
                  type: string
                  format: date
                  description: The date from, Default beginning of current year
                customer_system_id:
                  type: string
                  description: >
                    The Customer system id (can be retrieved by the 'retrieve_customer' endpoint).
                    Required if no customer_unique_id. Note this endpoint expects customer_system_id -
                    the shorter 'system_id' accepted by 'get_customer_details' and 'customer_gl' is
                    NOT recognised here.
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_system_id
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  invoices:
                    type: array
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /customer_price_list:
    x-summary: Get customer price list
    post:
      description: "This endpoint retrieves the customer's item price list.  \n<hr/>\n"
      summary: Get customer price list
      operationId: customerPriceList
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_system_id
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_system_id:
                  type: string
                  description: The Customer system id (can be retrieve by 'retrieve_customer' end point)
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  price_list:
                    type: object
                    properties:
                      SKU:
                        type: number
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /customer_last_price:
    x-summary: Get customer last price for given item
    post:
      description: "Retrieves the best available price for a customer-item combination\
        \ using a fallback chain: last paid price → customer price list → catalog\
        \ default price.  \nAlways returns HTTP 200. When no price is available `price`\
        \ is `null` and `price_source` is `\"none\"`.  \n`purchase_date` and `purchase_quantity`\
        \ are only present when `price_source` is `\"last_paid\"`.  \n<hr/>\n"
      summary: Get customer last price for given item
      operationId: customerLastPrice
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customer_system_id
              - item_sku
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                customer_system_id:
                  type: string
                  description: The Customer system id (can be retrieved by 'retrieve_customer'
                    endpoint)
                item_sku:
                  type: string
                  description: The catalog item SKU
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  price:
                    type: number
                    nullable: true
                    description: Ex-VAT price. `null` when no price is found (`price_source:\
                      \ "none"`).
                  price_source:
                    type: string
                    enum:
                    - last_paid
                    - price_list
                    - catalog
                    - none
                    description: "Indicates which source the price was taken from:\
                      \ `last_paid` (most recent paid invoice line), `price_list`\
                      \ (customer price-list override), `catalog` (catalog item default),\
                      \ `none` (no price available)."
                  purchase_date:
                    type: string
                    description: "Date of the last purchase in DD/MM/YYYY format. Present
                      only when `price_source` is `\"last_paid\"`."
                    example: "25/06/2026"
                  purchase_quantity:
                    type: number
                    description: Quantity on the last purchase. Present only when
                      `price_source` is `"last_paid"`.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /customer_gl:
    x-summary: Get customer general ledger
    post:
      description: "This endpoint retrieves specific and public links to the customer's general ledger.  \n<hr/>\n"
      summary: Get customer general ledger
      operationId: customerGl
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - system_id
              - customer_unique_id
              - customer_mail
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                system_id:
                  type: string
                  description: The Customer Payper system id
                customer_unique_id:
                  type: string
                  description: The Customer business number OR Personal identity number, required if no customer_mail or system_id
                customer_mail:
                  type: string
                  description: The Customer main email address, required if no customer_unique_id or system_id
                from_date:
                  type: string
                  format: date
                  description: The date from, Default beginning of current year
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  gl_link:
                    type: string
                  archive_link:
                    type: string
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /cancel_proforma:
    x-summary: Cancel proforma invoice
    post:
      description: "This endpoint used to mark proforma invoice as canceled.  \n<hr/>\n"
      summary: Cancel proforma invoice
      operationId: cancelProforma
      tags:
      - Finance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - document_system_id
              - document_id
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                document_system_id:
                  type: integer
                  description: The proforma system id as you get from 'generate_proforma' end point. Not required if document_id is present.
                document_id:
                  type: string
                  description: The proforma document id as you get from 'generate_proforma' end point. Not required if document_id is present.
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /cancel_purchase_order:
    x-summary: Cancel purchase order
    post:
      description: |
        Cancels an existing **purchase order** (marks it as canceled) and returns its number for documentation.
        Send at least one of `document_system_id` or `document_id` (as returned by `generate_purchase_order`).
        A purchase order whose goods were already (partially) received cannot be canceled.

        #### Error codes (returned in the `result` field)
        <table>
          <tr><th>result</th><th>Meaning</th></tr>
          <tr><td>670</td><td>Missing locator (document_system_id / document_id)</td></tr>
          <tr><td>671</td><td>Purchase order not found</td></tr>
          <tr><td>672</td><td>More than one purchase order matched</td></tr>
          <tr><td>674</td><td>Can't cancel — goods already received</td></tr>
        </table>
        <hr/>
      summary: Cancel a purchase order
      operationId: cancelPurchaseOrder
      tags:
      - Finance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              properties:
                api_user:
                  type: string
                  description: API user email
                document_system_id:
                  type: integer
                  description: The PO system id from 'generate_purchase_order'. At least one of document_system_id or document_id is required.
                document_id:
                  type: string
                  description: The PO document number from 'generate_purchase_order'. At least one of document_system_id or document_id is required.
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  document_id:
                    type: string
                    description: The canceled PO's number (for documentation)
                  document_system_id:
                    type: integer
                    description: The canceled PO's internal system id
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /daily_income:
    x-summary: Get Daily Incomes
    post:
      description: "This endpoint retrieves daily incomes by payment type. Results are returned as a link to download an Excel file. If no parameters are provided, it defaults to the current day.  \nDates are accepted as `YYYY-MM-DD` (`DD/MM/YYYY` also works). An unparseable date returns `result` 8012 (from_date) or 8013 (to_date).  \n<hr/>\n"
      summary: Get Daily Incomes
      operationId: dailyIncome
      tags:
      - Finance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                from_date:
                  type: string
                  format: date
                  description: 'The date from. Default is today. Format: YYYY-MM-DD (DD/MM/YYYY is also accepted for backward compatibility).'
                  example: '2026-07-31'
                to_date:
                  type: string
                  format: date
                  description: 'The date to. Default is today. Format: YYYY-MM-DD (DD/MM/YYYY is also accepted for backward compatibility).'
                  example: '2026-07-31'
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  document_link:
                    type: string
                    description: A link to Excel file with the daily incomes
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /pull_expenses:
    x-summary: Get expenses
    post:
      description: "This endpoint retrieves expenses based on the provided query parameters.  \n<hr/>\n"
      summary: Get expenses
      operationId: pullExpenses
      tags:
      - Finance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_user:
                  type: string
                  description: The email defined as the api_user in the Api Settings. Required on every request, alongside the API_KEY header.
                  example: api@user
                query_options:
                  type: object
                  description: The query for the current request
                  properties:
                    updated_from:
                      type: string
                      description: Date Time, last update time on Payper system
                      format: date-time
                      example: 2026-01-01 00:00
                    updated_to:
                      type: string
                      description: Date Time, last update time on Payper system
                      format: date-time
                      example: 2026-01-01 00:00
                    created_from:
                      type: string
                      description: Date Time, creation time on Payper system
                      format: date-time
                      example: 2026-01-01 00:00
                    created_to:
                      type: string
                      description: Date Time, creation time on Payper system
                      format: date-time
                      example: 2026-01-01 00:00
                    document_date_from:
                      type: string
                      description: Date, document publish date
                      format: dd/mm/yyyy
                    document_date_to:
                      type: string
                      description: Date, document publish date
                      format: dd/mm/yyyy
                    document_id:
                      type: string
                      description: The document number
                    system_id:
                      type: integer
                      description: The document system id
                    order:
                      type: string
                      description: 'The results order, Can be one of: document_date | created_at'
                      default: document_date
                    page:
                      type: integer
                      description: The results desirable page
                      minimum: 1
                    per_page:
                      type: integer
                      description: The size of the results
                      minimum: 1
                      maximum: 50
                      default: 50
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  total_entries:
                    type: string
                    description: The total size of the query
                  total_pages:
                    type: string
                    description: The total pages of the query
                  next_page:
                    type: string
                    description: The next available page
                  previous_page:
                    type: string
                    description: The previous available page
                  expenses:
                    type: array
                    items:
                      type: object
                    description: An array of JSON of the search
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /get_inventories:
    x-summary: Get list of inventory
    post:
      description: |
        This endpoint retrieves a paginated list of inventory items with stock levels,
        supplier data, purchase costs, and sales metrics.

        Optionally filter by partial name/SKU with `search`, or look up an exact SKU
        with `item_sku`. With neither filter, the full list is returned.

        #### Request Parameters
        <table>
          <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>
          <tr><td>page</td><td>integer</td><td>No (default: 1, 100 items per page)</td></tr>
          <tr><td>search</td><td>string</td><td>No — partial match on product name or makat/SKU</td></tr>
          <tr><td>item_sku</td><td>string</td><td>No — exact makat lookup</td></tr>
        </table>
        <hr/>
      summary: Get list of inventory
      operationId: getInventories
      tags:
      - Inventory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_user:
                  type: string
                  description: API user email
                page:
                  type: integer
                  default: 1
                  description: Page number (100 items per page)
                search:
                  type: string
                  description: Partial text search — matches product name or makat
                    (SKU). Optional.
                item_sku:
                  type: string
                  description: Exact makat (SKU) lookup. Optional. Takes priority
                    over `search`.
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  total_items:
                    type: integer
                  total_pages:
                    type: integer
                  current_page:
                    type: integer
                  inventories:
                    type: array
                    items:
                      type: object
                      properties:
                        item_id:
                          type: integer
                          description: Internal item ID (used in products/show_item/{item_id})
                          example: 1234
                        catalog_item_id:
                          type: string
                          description: Item SKU / makat
                        name:
                          type: string
                          description: Product name (Hebrew)
                        name_en:
                          type: string
                          description: Product name (English) for foreign supplier portal
                        category_name:
                          type: string
                          description: Catalog category name (from Category model via type_cat_id)
                        quantity:
                          type: number
                          description: Current stock quantity
                        is_active:
                          type: boolean
                          description: Whether the product is active
                        is_package:
                          type: boolean
                          description: Whether this is a bundle/package
                        provider_name:
                          type: string
                          description: Primary provider name
                        provider_email:
                          type: string
                          description: Provider email address
                        provider_tax_id:
                          type: string
                          description: Provider business number
                        provider_invoice_lang:
                          type: string
                          description: Provider invoice language (hb/en)
                        purchase_cost:
                          type: number
                          description: Unit purchase cost
                        purchase_currency:
                          type: string
                          description: Purchase currency (ILS, USD, EUR)
                        open_orders_qty:
                          type: number
                          description: "Quantity on open purchase orders (unfulfilled). Present only in the full-list response; absent when using `search` or `item_sku` filters."
                        delivery_days:
                          type: integer
                          description: Average delivery days from supplier
                        daily_sales:
                          type: number
                          description: Average daily sales quantity
                        monthly_sales:
                          type: number
                          description: Average monthly sales quantity
                        min_per_order:
                          type: number
                          description: Minimum order quantity
                        product_age_days:
                          type: integer
                          description: Days since product first stocked
                        price:
                          type: number
                          description: Ex-VAT sale price
                        cost:
                          type: number
                          description: Total cost of the item
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /get_stock_for_item:
    x-summary: Get quantity for item
    post:
      description: |
        This endpoint retrieves the quantity of a specific item in the inventory by its catalog item ID (SKU/makat).
        #### Request Parameters
        <table>
          <tr><th>Attributes</th><th>Parameter</th><th>Required</th></tr>
          <tr><td>catalog_item_id</td><td>string</td><td>Yes</td></tr>
        </table>
        <hr/>
      summary: Get quantity of a certain item in the inventory
      operationId: getStockForItem
      tags:
      - Inventory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              - catalog_item_id
              properties:
                api_user:
                  type: string
                  description: API user email
                catalog_item_id:
                  type: string
                  description: Item SKU / makat to look up
                  example: SKU12345
      responses:
        '200':
          description: Request accepted and processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  catalog_item_id:
                    type: string
                  catalog_item_name:
                    type: string
                  quantity:
                    type: integer
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /update_catalog_item:
    x-summary: Update Product
    post:
      description: |
        Updates an existing **product** (CatalogItem) for the authenticated company.
        This is a **partial update** — only the fields you send are changed; everything else is left as-is.

        > **Locating the product:** send at least one of `catalog_item_id` (SKU / makat) or `item_id`
        > (the internal system id returned by `get_inventories`). `catalog_item_id` takes priority.
        > The SKU itself is the locator and is **not** modified by this endpoint.

        > **Not updatable here:** the product's supplier and its live stock level.

        #### Pricing & VAT
        To change the sale price, send `price` together with `vat_mode`:
        <table>
          <tr><th>vat_mode</th><th>Meaning</th></tr>
          <tr><td>2</td><td>price is BEFORE VAT (VAT added on top) — most common</td></tr>
          <tr><td>1</td><td>price INCLUDES VAT</td></tr>
          <tr><td>0</td><td>VAT exempt</td></tr>
        </table>
        Sending `vat_mode` without `price` is ignored. `price_with_vat` is always recomputed at the current VAT rate.

        #### Image
        Optionally send <b>one</b> of `image_url` or `image_base64` to replace the product's main image.
        The image is fetched/stored in the background (the response returns `image_status: "queued"`).
        Remote URLs are validated against SSRF (no internal/loopback hosts) and capped in size.

        #### Error codes (returned in the `result` field)
        <table>
          <tr><th>result</th><th>Meaning</th></tr>
          <tr><td>310</td><td>Product not found for the given locator</td></tr>
          <tr><td>311</td><td>Missing or ambiguous locator</td></tr>
          <tr><td>312</td><td>Validation failed (e.g. duplicate name, invalid category/measure unit)</td></tr>
          <tr><td>313</td><td>Invalid status (allowed: 0 or 1)</td></tr>
          <tr><td>314</td><td>Invalid vat_mode (allowed: 0, 1, 2)</td></tr>
          <tr><td>315</td><td>Invalid image input</td></tr>
        </table>
        <hr/>
      summary: Update an existing product's data
      operationId: updateCatalogItem
      tags:
      - Inventory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              properties:
                api_user:
                  type: string
                  description: API user email
                catalog_item_id:
                  type: string
                  description: "Locator: product SKU / makat (primary). At least one of catalog_item_id or item_id is required."
                  example: SKU12345
                item_id:
                  type: integer
                  description: "Locator: internal system id (fallback), as returned by get_inventories."
                  example: 6424
                name:
                  type: string
                  description: Product name (unique per company)
                en_name:
                  type: string
                  description: Product name in English
                internal_makat:
                  type: string
                  description: Internal SKU
                internal_name:
                  type: string
                  description: Internal name
                price:
                  type: number
                  description: Sale price (send together with vat_mode)
                  example: 199.9
                vat_mode:
                  type: integer
                  description: "VAT mode for the sale price: 2=before VAT, 1=includes VAT, 0=exempt"
                  example: 2
                currency_symbol:
                  type: string
                  description: Sale currency code
                  example: ILS
                po_cost:
                  type: number
                  description: Purchase cost
                cost:
                  type: number
                  description: Total cost
                po_currency_symbol:
                  type: string
                  description: Purchase currency code
                  example: USD
                min_order_amount:
                  type: number
                  description: Minimum order quantity
                alert_quantity:
                  type: number
                  description: Low-stock reorder alert threshold
                supply_period:
                  type: integer
                  description: Days to supply / prepare
                status:
                  type: integer
                  description: "Product status: 1=active, 0=inactive"
                  example: 1
                type_cat_id:
                  type: integer
                  description: Category id (must belong to the company)
                measure_unit_id:
                  type: integer
                  description: Measure unit id
                description:
                  type: string
                  description: Product description
                supply_remarks:
                  type: string
                  description: Supply remarks
                manufacturer_name:
                  type: string
                  description: Manufacturer name
                manufacturer_item_name:
                  type: string
                  description: Manufacturer's item name
                quantity_factor:
                  type: number
                  description: Quantity conversion factor
                quantity_in_package:
                  type: string
                  description: Quantity in a package
                item_measurements:
                  type: string
                  description: Free-text item measurements
                image_url:
                  type: string
                  description: Public http(s) URL of an image to set as the product's main image
                image_base64:
                  type: string
                  description: Base64-encoded image to set as the product's main image (max 5 MB)
      responses:
        '200':
          description: Product updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    default: '200'
                  description:
                    type: string
                    default: Success
                  item_id:
                    type: integer
                    description: Internal system id of the updated product
                  makat:
                    type: string
                    description: Product SKU / makat
                  image_status:
                    type: string
                    description: Present only when an image was sent
                    example: queued
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '110'
                  description:
                    type: string
                    example: Unknown credentials
  /create_reseller_customer:
    x-summary: Create Managed Customer
    post:
      description: "Creates a new managed customer account under your reseller account, together with an admin user. The new account is fully provisioned and ready to use immediately.\n\n> **Auth:** Your `api_key` must belong to a reseller account. Regular customer api_keys cannot call this endpoint and will receive `110`.\n\nYour reseller defaults (welcome-email template, default allowed IPs, default API test mode) are applied automatically. Pass `company[allowed_ips]` or `company[invoice_api_test]` to override your defaults for a specific customer.\n\nIf you supply `user[first_name]` and `user[login]`, an admin user is created and receives a welcome email with auto-generated login credentials.\n"
      summary: Create Managed Customer
      operationId: createResellerCustomer
      tags:
      - Reseller Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - api_user
              - company
              properties:
                api_user:
                  type: string
                  description: The reseller's api_user (same field used by every other Payper API endpoint).
                  example: api@reseller.com
                activity_start:
                  type: string
                  description: Activity start month in **MM/YYYY** format. Parsed as the 1st of that month.
                  example: 05/2026
                company:
                  type: object
                  required:
                  - name
                  - business_num
                  properties:
                    name:
                      type: string
                      description: The new customer's full company name (required).
                      example: New Customer Ltd
                    business_num:
                      type: string
                      description: Business number / VAT number / personal ID — depending on association_type (required).
                      example: '123456789'
                    email:
                      type: string
                      format: email
                      description: The new company's main email address.
                      example: info@newcustomer.com
                    association_type:
                      type: integer
                      description: 'Association type. Defaults to authorized_dealer. Common values: 0=company, 1=authorized_dealer, 2=exempt_dealer, 3=ngo.'
                      example: 1
                    is_own_invoices:
                      type: integer
                      description: 1=this customer produces its own invoices, 0=invoices are produced on its behalf. Default depends on association_type.
                      example: 1
                    is_section_46:
                      type: integer
                      description: 1=NGO eligible for Section 46 donation receipts (only meaningful when association_type=ngo).
                      example: 0
                    lead_source:
                      type: string
                      description: Free-text customer code / lead-source field (קוד לקוח). Used by the reseller for their own bookkeeping.
                      example: ABC-123
                    phone:
                      type: string
                      description: Company landline phone.
                    mobile:
                      type: string
                      description: Company mobile phone.
                    address:
                      type: string
                      description: Company address (Hebrew).
                    english_name:
                      type: string
                      description: Company name for English-language documents.
                    english_address:
                      type: string
                      description: Company address for English-language documents.
                    site_URL:
                      type: string
                      description: Company website URL.
                    allowed_ips:
                      type: string
                      description: 'Comma-separated IP whitelist for the new customer''s OWN api_key. Overrides the reseller''s default *allowed_ips* setting when supplied. Example: ''1.2.3.4,5.6.7.8''.'
                      example: 1.2.3.4,5.6.7.8
                    invoice_api_test:
                      type: integer
                      description: 1=new customer starts in API sandbox/test mode, 0=production mode. Overrides the reseller's default *invoice_api_test* setting when supplied.
                      example: 0
                user:
                  type: object
                  description: 'Admin user to create alongside the company. Optional — if `user[first_name]` is blank, no user is created and the company is provisioned without an admin (the reseller can add one later via the UI). When supplied, `user[login]` becomes required.'
                  properties:
                    first_name:
                      type: string
                      description: Admin user's first name (required when creating a user).
                      example: John
                    last_name:
                      type: string
                      description: Admin user's last name.
                      example: Doe
                    login:
                      type: string
                      format: email
                      description: Admin user's email (= login). Must be unique across Payper. Required when `user[first_name]` is supplied.
                      example: john@newcustomer.com
                    mobile1:
                      type: string
                      description: Admin user's mobile phone.
                      example: '0501234567'
                    business_phone:
                      type: string
                      description: Admin user's business phone.
                      example: '037654321'
      responses:
        '200':
          description: Company created
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: '200'
                  description:
                    type: string
                    example: Success
                  company_id:
                    type: integer
                    description: The system id of the newly-created managed company.
                    example: 12345
                  access_key:
                    type: string
                    description: The new company's API key. Use this together with the new admin user's login (api_user) for subsequent calls on the new customer's behalf.
                    example: 9b0452845ec0a37c9594b0452845ec0a37c95949b0452845ec0a37c9594abcd
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: '`110`=bad api_key/api_user or company is not a reseller. `111`=request IP not in reseller''s allowed_ips.'
                    example: '110'
                  description:
                    type: string
                    example: Unauthorized credentials
        '422':
          description: Validation or input error
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    description: '`130`=invalid activity_start format (expected MM/YYYY). `131`=Company/User validation failure (full Rails error messages joined). `132`=missing required params (e.g. company[name], company[business_num], user[login]).'
                    example: '131'
                  description:
                    type: string
                    example: 'Missing required params: company[name], company[business_num]'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: API_KEY
      in: header
      description: |
        All requests must include an <b>api_key</b> in the header and an <b>api_user</b> in the request parameters.  
        <br/>**Example:**  
        ```plaintext
        request.headers["API_KEY"] = '9b0452845ec0a37c9594'
        request.body["api_user"] = 'api@user'
