Top-Up API

1. Introduction

This document explains the process of using the Top-Up service in the HORISEN SMS Platform application. It provides detailed instructions of how to retrieve needed data before initiating a top-up request, creating a top-up, as well as described in details the APIs endpoints methods associated with the Top-Up feature.

The HORISEN Top-Up API is a standard REST HTTP API with JSON payload. The SMS Platform API authorization is implemented as the industry-standard OAuth 2.0 protocol. For more information, please refer to the OAuth2 Authentication Guidelines page.

1.1 API Call Examples

The following steps explains the process of retrieving needed data for initiating a top-up process, as well as creating clearing records and top-up invoices.

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

More details about the APIs endpoints methods can be found in 2. Methods Overview section of this document.

1. To start a top-up process, creditRecordType with codeName=TOP-UP is required for further API calls. The following example cURL API call retrieves details of Credit Record Types available in the system:

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/credit-record-types?sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

An example of a response is given below:

{
    "data": [
        {
            "id": 1,
            "typeUid": "string",
            "codeName": "TOP-UP",
            "name": "Prepaid Top Up",
            "billingTypeId": 1,
            "createInvoice": "yes",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        },
        {
            "id": 2,
            "typeUid": "string",
            "codeName": "TEST-CREDIT",
            "name": "Prepaid Test Credit",
            "billingTypeId": 1,
            "createInvoice": "no",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        },
        {
            "id": 3,
            "typeUid": "string",
            "codeName": "PART-PAYMENT",
            "name": "Postpaid Part Payment",
            "billingTypeId": 2,
            "createInvoice": "yes",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "totalPages": 1,
            "currentPage": 1,
            "perPage": 3,
            "count": 3
        }
    }
}

2. The next API call returns all Business Partners associated with the product:

curl 'https://api{separator}{platform_domain}/biz-core/v1/product-type-partners-lov?productCodeName=BULK-SMS&productTypeCodeName=BULK-SMS&relationTypeCodeName=CUSTOMER&sort=briefName&status=active' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Where productTypeCodeName=BULK-SMS indicates that 'BULK_SMS' is a product type.
relationTypeCodeName=CUSTOMER is used because the process will create a Customer Invoice.
status=active is used in order to retrieve all active Business Partners.

3. The following cURL call retrieves all valid prepaid total balances associated with the selected Business Partner.

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/valid-prepaid-total-balances?bizPartnerId=BIZ_PARTNER_ID&status=active&page_number=1&page_size=10000&sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Where bizPartnerId=BIZ_PARTNER_ID is the ID of the selected Business Partner.

4. For the selected Invoice Conditions (Total Balance), the next API call will retrieve Platform Owner Bank Accounts for the selected currency=CURRENCY_ID, which is retrieved from the previously selected Invoice Conditions:

curl 'https://api{separator}{platform_domain}/settings/v1/platform-owner-bank-accounts?all=yes&coOwnerId=0&currency=CURRENCY_ID&sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

5. The next API call creates a Credit Record and a Top-Up invoice with the given data for amount as the top-up total amount and creditAmount as allowed amount for the top-up:

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/credit-record-invoices' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{"balanceId": BALANCE_ID,"amount": 1500,"comment":"Test comment","payment":{"fullyPaid": true,"paymentType": 4,"bankAccountId": 0}}'

An example of a payload is given below:

{
  "balanceId": 83,
  "amount": 1500,
  "comment": "Test comment",
  "payment": {
    "fullyPaid": true,
    "paymentType": 4,
    "bankAccountId": 0
  }
}

and the response example would be:

{
    "id": 742,
    "creditUid": "e10963bf-40d5-b711-8085-f6da1dda261a",
    "balanceId": 83,
    "activationDate": "2024-04-25",
    "amount": 1500,
    "creditAmount": 1500,
    "paidAmount": 1500,
    "conditionalAmount": 0,
    "unpaidAmount": 0,
    "currency": 756,
    "description": "",
    "status": "active",
    "isAggregateRecord": "no",
    "aggregateFromDate": "0001-01-01",
    "comment": "Test comment",
    "invoiceId": 2860,
    "creationDate": "2024-04-25",
    "typeId": 1,
    "billingRecordId": 0,
    "orderingStatus": "off",
    "orderingStatusDt": "2024-04-25T13:23:15+02:00",
    "selectedPriceListId": 0,
    "ownerId": 0,
    "ownerBpName": "",
    "ownerBpBriefName": "",
    "currencyCode": "CHF",
    "currencyName": "Swiss Franc",
    "balanceName": "Test PetPrepaid",
    "bizPartnerId": 3000043,
    "bizPartnerName": "Test Partner",
    "bizPartnerShortName": "Test Partner",
    "billingType": 1,
    "type": "TOP-UP",
    "typeName": "Prepaid Top Up",
    "createInvoice": "yes",
    "invoice": {
        "id": 2860,
        "instanceID": 3000003,
        "custID": 3000043,
        "custName": "Mike T",
        "custAttn": "Mike test",
        "custAddress": "Test address",
        "custAddress2": "",
        "custPost": "11000",
        "custCity": "Belgrade",
        "custVatNumber": "123",
        "custShortName": "Mike",
        "custCountry": 756,
        "custPOBox": "",
        "invType": 1,
        "invTypeName": "Bulk Invoice - Prepaid Topup",
        "selfBilling": "no",
        "templateID": 1,
        "invDate": "2024-04-25",
        "invNumberFix": "250424-%d",
        "invNumberNum": 3,
        "invNumber": "250424-3",
        "invPeriod": "",
        "invDueDate": "2024-04-25",
        "overDueDate": 0,
        "ownerVatNumber": "12",
        "currency": 756,
        "currencyCode": "CHF",
        "amountNoVat": 1500,
        "amountVat": 1500,
        "vatPercent": 0,
        "rounding": 0,
        "total": 1500,
        "totalUnpaid": 0,
        "totalPaid": 1500,
        "vatInPrice": 0,
        "vatInTotal": 0,
        "status": "approved",
        "insertDt": "2024-04-25T11:23:15Z",
        "statusDt": "2024-04-25T11:23:15Z",
        "deliveryDate": "2024-04-25",
        "invPeriodStart": null,
        "invPeriodEnd": null,
        "docsDeliveryStatus": "none",
        "docsDeliveryStatusDate": null,
        "docsDeliveryDlrStatus": "none",
        "docsDeliveryDlrStatusDate": null,
        "classCodeName": "CUSTOMER_INVOICE",
        "classDomain": "invoice",
        "classArea": "sales",
        "lang": "en",
        "paymentStatus": "closed",
        "paymentStatusDate": "2024-04-25T11:23:15Z",
        "disputeStatus": "none",
        "disputeStatusDate": null,
        "nettingInvoiceId": 0,
        "nettingInvoiceNumber": "",
        "dataSourceId": 1,
        "dataSourceCodeName": "PREPAID",
        "domainId": 1,
        "domainCodeName": "BULK",
        "disputeNextId": 0,
        "collectionMode": "none",
        "collectionLeadId": 0,
        "processingStatus": "none",
        "dtsSelectorId": 0,
        "dtsSelectorCodeName": "",
        "ownerId": 0,
        "domesticCurrency": 0,
        "domesticCurrencyCode": "",
        "ownerName": "OwnerNameExample",
        "ownerBpName": "",
        "ownerBpBriefName": "",
        "customerType": "",
        "industryName": "",
        "domainName": "Bulk SMS",
        "domesticCurrencyAmountNoVAT": 0,
        "domesticCurrencyAmountVAT": 0,
        "domesticCurrencyTotal": 0,
        "collectionLeadNumber": "",
        "collectionLeadNettingInvoiceId": 0,
        "billingBalance": {
            "id": 83,
            "name": "Test PetPrepaid",
            "resourceUrl": "https://api{separator}{platform_domain}/bulk/billing/v2/total-balances/83"
        },
        "items": [
            {
                "id": 17945,
                "invoiceId": 2860,
                "ordNum": 1,
                "name": "{\"1\": \"Prepaid Bulk SMS Credit\", \"2\" : \"Test PetPrepaid\"}",
                "itemType": "ITEM-2",
                "quantity": 0,
                "quantityMore": 1,
                "quantityMode": 0,
                "measureUnit": 1,
                "price": 0,
                "vatInPrice": 0,
                "totalNoVat": 1500,
                "totalVat": 1500,
                "status": "active",
                "insertDt": "2024-04-25T11:23:15Z",
                "statusDt": "2024-04-25T11:23:15Z",
                "dataSourceId": 0,
                "dataSourceForeignKey": 0,
                "dtsSelectorId": 0,
                "dtsSelectorCodeName": ""
            }
        ]
    }
}

Where balanceId and currency are data retrieved from the selected Total Balance from the previous step.

This invoice is newly created Customer Prepaid Invoice with status approved. It can be retrieved by calling the following endpoint with specified INVOICE_ID:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

6. The following cURL call lists all invoices within the specific date range with status 'approved':

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices?between(invDate)=2024-01-01%2C2024-12-31&classCodeName=CUSTOMER_INVOICE&in(disputeStatus)=closed%2Cnone&lang=en&page_number=1&page_size=10&sort=-invDate%2C-id&status=approved' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

7. To view payment history data for INVOICE_ID, the following API call can be used:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

An example of a response is given below:

{
    "data": [
        {
            "id": 2544,
            "clearingId": 1276,
            "clearingTypeId": 1,
            "clearingTypeCodeName": "INVOICE",
            "recordDate": "2024-04-19",
            "paymentTypeId": 0,
            "paymentTypeName": "",
            "amountIncrement": 200,
            "paidAmount": 0,
            "paymentReference": "",
            "comment": "Invoice: 190424-3",
            "status": "active",
            "statusDate": "2024-04-19T11:54:22Z",
            "bankAccountId": 0,
            "bankAccountName": "",
            "bankAccountNumber": "",
            "bankAccountIban": "",
            "bankAccountSwiftBic": ""
        }
    ],
    "meta": {
        "pagination": {
            "total": 1,
            "totalPages": 1,
            "currentPage": 1,
            "perPage": 1000,
            "count": 1
        }
    }
}

8. To add a Payment for the invoice with id=INVOICE_ID, the following API call can be made:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{"clearingTypeId":2,"recordDate":"2024-04-22","paymentTypeId":1,"bankAccountId":BANK_ACCOUNT_ID,"paidAmount":100}'

where "clearingTypeId":2 is for payment, "paymentTypeId":1 is for 'Bank Account' selected type, "bankAccountId":BANK_ACCOUNT_ID is Platform Owner Bank Account ID retrieved in the previous API call.

9. The example of the API call for listing all clearing records for the invoice with INVOICE_ID, is given below:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

2. Methods Overview

2.1 Invoices

These endpoints allow retrieving a list of payable invoices and top-up invoices.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

The following endpoint is used for a top-up or part payment invoice creation.

The API endpoint belongs to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

2.2 Invoice Clearing

The following endpoints allow performing operations with invoices clearing records.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

2.3 Payment Type

The endpoint described in this section allows retrieving a list of payment types that can be used in invoices payment process.

The API endpoint belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

2.4 Total Balances

The following endpoints are used for listing Total Balances.

The API endpoints belong to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

2.5 Credit Record Types

This endpoint is used to get all Credit Records Types.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

2.6 Product Type Partners LOV

The endpoint described in this section allows retrieving a list of Product Type Partners LOV.

The API endpoint belong to the Biz-core domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/biz-core/v1

2.7 Platform Owner Bank Accounts

The following endpoint is used for listing data of platform owner bank accounts.

The API endpoint belong to the Settings domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/settings/v1

3. Methods Details

3.1 Invoices

These endpoints allow retrieving a list of payable invoices and top-up invoices.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

GET/payable-invoices

Returns a list of all payable invoices.Up

Method Overview

The method returns a list of payable invoices.

Payable invoices are invoices whose status is 'approved' and whose payment status is 'open'.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: privilege used in this endpoint is finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters

Name	Type	Description
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: custShortName, custName, invNumber, invDate, invoicingDate, invoicingDatePolicy, invDueDate, invTypeName, invPeriod, disputeStatus, ownerId, ownerBpName, ownerBpBriefName.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

Responses

Code	Description	Links
200	List of invoices.	No links
default	Unexpected Error.	No links

Success Response 200: List of Invoices

{
  "data": [
    {
      "id": 0,
      "invUid": "string",
      "instanceID": 0,
      "custID": 0,
      "custName": "string",
      "custShortName": "string",
      "custAttn": "string",
      "custAddress": "string",
      "custAddress2": "string",
      "custPost": "string",
      "custCity": "string",
      "custCountry": 0,
      "custPOBox": "string",
      "customerType": "string",
      "custVatNumber": "string",
      "invType": 0,
      "invTypeName": "string",
      "templateID": 0,
      "invDate": "2024-02-29",
      "invoicingDate": "2024-02-29",
      "invoicingDatePolicy": "delivery",
      "invNumberFix": "string",
      "invNumberNum": 0,
      "invNumber": "string",
      "invPeriod": "string",
      "invDueDate": "2024-02-29",
      "overDueDate": 0,
      "ownerVatNumber": "string",
      "currency": 0,
      "currencyCode": "string",
      "amountNoVat": 0,
      "amountVat": 0,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0,
      "totalUnpaid": 0,
      "totalPaid": 0,
      "vatInPrice": 0,
      "vatInTotal": 0,
      "status": "draft",
      "insertDt": "2024-02-29T13:52:05.633Z",
      "statusDt": "2024-02-29T13:52:05.633Z",
      "deliveryDate": "2024-02-29",
      "invPeriodStart": "2024-02-29",
      "invPeriodEnd": "2024-02-29",
      "docsDeliveryStatus": "string",
      "docsDeliveryStatusDate": "2024-02-29T13:52:05.633Z",
      "docsDeliveryDlrStatus": "string",
      "docsDeliveryDlrStatusDate": "2024-02-29T13:52:05.633Z",
      "classCodeName": "string",
      "classDomain": "string",
      "classArea": "string",
      "lang": "string",
      "paymentStatus": "none",
      "paymentStatusDate": "2024-02-29T13:52:05.633Z",
      "disputeStatus": "string",
      "disputeStatusDate": "2024-02-29T13:52:05.633Z",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "nettingInvoiceId": 0,
      "nettingInvoiceNumber": "string",
      "selfBilling": "yes",
      "domainId": 0,
      "domainCodeName": "string",
      "domainName": "string",
      "domainProduct": 0,
      "accountManagerId": 0,
      "accountManagerName": "string",
      "disputeNextId": 0,
      "collectionMode": "none",
      "collectionLeadId": 0,
      "collectionLeadNumber": "string",
      "collectionLeadNettingInvoiceId": 0,
      "collectionLeadNettingInvoiceNumber": "string",
      "collectionLeadNettingInvoiceStatus": "string",
      "collectionLeadNettingInvoicePaymentStatus": "string",
      "collectionLeadNettingInvoiceTotal": "string",
      "collectionLeadNettingInvoiceTotalPaid": "string",
      "collectionLeadNettingInvoiceTotalUnpaid": "string",
      "processingStatus": "none",
      "comment": "string",
      "nettingInvoiceStatus": "draft",
      "nettingPaymentStatus": "none",
      "nettingTotal": 0,
      "nettingTotalUnpaid": 0,
      "nettingTotalPaid": 0,
      "dtsSelectorId": 0,
      "dtsSelectorCodeName": "string",
      "sitInvoiceEmailImportId": 0,
      "billingBalance": {
        "id": 0,
        "name": "string",
        "resourceUrl": "string"
      },
      "billingTypeName": "string",
      "smsCount": 0,
      "syncStatus": "none",
      "syncStatusDt": "2024-02-29T13:52:05.633Z",
      "syncMode": "disabled",
      "reminderStatus": "enabled",
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyAmountNoVAT": 0,
      "domesticCurrencyAmountVAT": 0,
      "domesticCurrencyTotal": 0,
      "domesticCurrencyRounding": 0,
      "domesticCurrencyRate": 0,
      "industryName": "string",
      "ownerName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {}
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

GET/topup-invoices

Returns a list of top-up Invoices.Up

Method Overview

The method returns a list of top-up Invoices.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters

Name	Type	Description
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: custShortName, custName, invNumber, invDate, invoicingDate, invoicingDatePolicy, invDueDate, invTypeName, invPeriod, disputeStatus, ownerId, ownerBpName, ownerBpBriefName.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

Success Response 200: List of Invoices

{
  "data": [
    {
      "id": 0,
      "invUid": "string",
      "instanceID": 0,
      "custID": 0,
      "custName": "string",
      "custShortName": "string",
      "custAttn": "string",
      "custAddress": "string",
      "custAddress2": "string",
      "custPost": "string",
      "custCity": "string",
      "custCountry": 0,
      "custPOBox": "string",
      "customerType": "string",
      "custVatNumber": "string",
      "invType": 0,
      "invTypeName": "string",
      "templateID": 0,
      "invDate": "2024-05-07",
      "invoicingDate": "2024-05-07",
      "invoicingDatePolicy": "delivery",
      "invNumberFix": "string",
      "invNumberNum": 0,
      "invNumber": "string",
      "invPeriod": "string",
      "invDueDate": "2024-05-07",
      "overDueDate": 0,
      "ownerVatNumber": "string",
      "currency": 0,
      "currencyCode": "string",
      "amountNoVat": 0,
      "amountVat": 0,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0,
      "totalUnpaid": 0,
      "totalPaid": 0,
      "vatInPrice": 0,
      "vatInTotal": 0,
      "status": "draft",
      "insertDt": "2024-05-07T12:10:38.923Z",
      "statusDt": "2024-05-07T12:10:38.923Z",
      "deliveryDate": "2024-05-07",
      "invPeriodStart": "2024-05-07",
      "invPeriodEnd": "2024-05-07",
      "docsDeliveryStatus": "string",
      "docsDeliveryStatusDate": "2024-05-07T12:10:38.923Z",
      "docsDeliveryDlrStatus": "string",
      "docsDeliveryDlrStatusDate": "2024-05-07T12:10:38.923Z",
      "classCodeName": "string",
      "classDomain": "string",
      "classArea": "string",
      "lang": "string",
      "paymentStatus": "none",
      "paymentStatusDate": "2024-05-07T12:10:38.923Z",
      "disputeStatus": "string",
      "disputeStatusDate": "2024-05-07T12:10:38.923Z",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "nettingInvoiceId": 0,
      "nettingInvoiceNumber": "string",
      "selfBilling": "yes",
      "domainId": 0,
      "domainCodeName": "string",
      "domainName": "string",
      "domainProduct": 0,
      "accountManagerId": 0,
      "accountManagerName": "string",
      "disputeNextId": 0,
      "collectionMode": "none",
      "collectionLeadId": 0,
      "collectionLeadNumber": "string",
      "collectionLeadNettingInvoiceId": 0,
      "collectionLeadNettingInvoiceNumber": "string",
      "collectionLeadNettingInvoiceStatus": "string",
      "collectionLeadNettingInvoicePaymentStatus": "string",
      "collectionLeadNettingInvoiceTotal": "string",
      "collectionLeadNettingInvoiceTotalPaid": "string",
      "collectionLeadNettingInvoiceTotalUnpaid": "string",
      "processingStatus": "none",
      "comment": "string",
      "nettingInvoiceStatus": "draft",
      "nettingPaymentStatus": "none",
      "nettingTotal": 0,
      "nettingTotalUnpaid": 0,
      "nettingTotalPaid": 0,
      "dtsSelectorId": 0,
      "dtsSelectorCodeName": "string",
      "sitInvoiceEmailImportId": 0,
      "billingBalance": {
        "id": 0,
        "name": "string",
        "resourceUrl": "string"
      },
      "billingTypeName": "string",
      "smsCount": 0,
      "syncStatus": "none",
      "syncStatusDt": "2024-05-07T12:10:38.923Z",
      "syncMode": "disabled",
      "reminderStatus": "enabled",
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyAmountNoVAT": 0,
      "domesticCurrencyAmountVAT": 0,
      "domesticCurrencyTotal": 0,
      "domesticCurrencyRounding": 0,
      "domesticCurrencyRate": 0,
      "industryName": "string",
      "ownerName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {}
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

POST/credit-record-invoices

Creates a top-up or part payment invoice.Up

This endpoint will create Customer Part Payment Invoices for Postpaid Total Balances and Customer Top-Up Invoices, for Prepaid Total Balances.

The API endpoint belongs to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Method Overview

The method creates a top-up or part payment invoice creation. For a top-up process, it is used to create new credit record with related invoice.

Parameters

Name	Type	Description
credit record create (required)	object (body)	New credit record with invoice to store.
fields	string (query)	Comma separated list of attributes that needs to be returned in partial response.

Data Parameters

post data object

{
  "balanceId": 0,
  "amount": 0,
  "comment": "string",
  "payment": {
    "fullyPaid": true,
    "paymentType": 0,
    "bankAccountId": 0
  }
}

Responses

Code	Description	Links
200	Credit record object with related invoice is created.	No links
default	Unexpected Error.	No links

{
  "id": 0,
  "creditUid": "string",
  "balanceId": 0,
  "activationDate": "2024-04-25",
  "creationDate": "2024-04-25",
  "amount": 0,
  "currency": 0,
  "creditAmount": 0,
  "conditionalAmount": 0,
  "paidAmount": 0,
  "unpaidAmount": 0,
  "status": "string",
  "isAggregateRecord": "string",
  "aggregateFromDate": "2024-04-25",
  "invoiceId": 0,
  "bizPartnerName": "string",
  "bizPartnerShortName": "string",
  "bizPartnerId": 0,
  "balanceName": "string",
  "typeId": 0,
  "billingRecordId": 0,
  "type": "string",
  "typeName": "string",
  "createInvoice": "yes",
  "billingType": 0,
  "currencyCode": "string",
  "currencyName": "string",
  "orderingStatus": "off",
  "orderingStatusDt": "2024-04-25T14:04:05.979Z",
  "selectedPriceListId": 0,
  "ownerId": 0,
  "ownerBpName": "string",
  "ownerBpBriefName": "string",
  "description": "string",
  "comment": "string",
  "invoice": {
    "id": 0,
    "instanceID": 0,
    "custID": 0,
    "custName": "string",
    "custShortName": "string",
    "custAttn": "string",
    "custAddress": "string",
    "custAddress2": "string",
    "custPost": "string",
    "custCity": "string",
    "custCountry": 0,
    "custPOBox": "string",
    "custVatNumber": "string",
    "invType": 0,
    "invTypeName": "string",
    "templateID": 0,
    "invDate": "string",
    "invNumberFix": "string",
    "invNumberNum": 0,
    "invNumber": "string",
    "invPeriod": "string",
    "invDueDate": "string",
    "overDueDate": 0,
    "ownerVatNumber": "string",
    "currency": 0,
    "currencyCode": "string",
    "amountNoVat": 0,
    "amountVat": 0,
    "vatPercent": 0,
    "rounding": 0,
    "total": 0,
    "totalUnpaid": 0,
    "vatInPrice": 0,
    "vatInTotal": 0,
    "status": "string",
    "insertDt": "string",
    "statusDt": "string",
    "deliveryDate": "string",
    "invPeriodStart": "string",
    "invPeriodEnd": "string",
    "docsDeliveryStatus": "string",
    "docsDeliveryStatusDate": "string",
    "docsDeliveryDlrStatus": "string",
    "docsDeliveryDlrStatusDate": "string",
    "selfBilling": "yes",
    "totalPaid": 0,
    "classCodeName": "string",
    "classDomain": "string",
    "classArea": "string",
    "lang": "string",
    "paymentStatus": "none",
    "paymentStatusDate": "2024-04-25T14:04:05.979Z",
    "disputeStatus": "string",
    "disputeStatusDate": "2024-04-25T14:04:05.979Z",
    "dataSourceId": 0,
    "dataSourceCodeName": "string",
    "nettingInvoiceId": 0,
    "nettingInvoiceNumber": "string",
    "domainId": 0,
    "domainCodeName": "string",
    "disputeNextId": 0,
    "collectionMode": "none",
    "collectionLeadId": 0,
    "processingStatus": "none",
    "dtsSelectorId": 0,
    "dtsSelectorCodeName": "string",
    "ownerId": 0,
    "items": [
      {
        "id": 0,
        "invoiceId": 0,
        "ordNum": 0,
        "name": "string",
        "itemType": "string",
        "quantity": 0,
        "quantityMore": 0,
        "quantityMode": 0,
        "measureUnit": 0,
        "price": 0,
        "vatInPrice": 0,
        "totalNoVat": 0,
        "totalVat": 0,
        "status": "string",
        "insertDt": "string",
        "statusDt": "string",
        "dataSourceId": 0,
        "dataSourceForeignKey": 0,
        "dtsSelectorId": 0,
        "dtsSelectorCodeName": "string"
      }
    ]
  }
}

Error Response Unexpected Error: Default

{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.2 Invoice Clearing

The following endpoints allow performing operations with invoices clearing records.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

GET/invoices/{invoiceid}/clearingrecords

Returns a list of all invoice Clearing Records for a given invoiceId.Up

Method Overview

The method returns a list of all invoice clearing records for a given invoice ID.

Returned InvoiceClearingRecords belong to InvoiceClearing.
InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
By default, only clearing records with 'active' status will be returned.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: the privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

If clearing records with other statuses should be returned, it should be used query parameter status with operator in and value containing a comma separated list of statuses (in(status)=active,canceled). For the time being, only 'active' and 'canceled' status are available as clearing record status values.

Parameters

Name	Type	Description
invoiceid (required)	integer (path)	Invoice ID to get Clearing Records.
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses

Code	Description	Links
200	List of InvoiceClearingRecords.	No links
default	Unexpected Error.	No links

Success Response 200: List of InvoiceClearingRecords

{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T10:35:26.862Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

POST/invoices/{invoiceid}/clearingrecords

Adds an invoice Clearing Record for a given InvoiceId.Up

Method Overview

The method adds an invoice clearing record for a given invoice ID.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
Approved supplier invoices with payment status 'on-hold', do not have clearing created. Clearing record for supplier invoice is created when a supplier invoice is approved for payment.
Invoice clearing record can not be added if an invoice does not have Clearing created.
When totalUnpaid is 0, invoice.paymentStatus is set to 'closed'.

clearingType type can be:
1 - Invoice = amount increment, is auto-generated when Invoice status is changed to 'approved',
2 - Payment = paidAmount - must be <> 0,
3 - Interest = amount increment - must be <> 0,
4 - Reminder = amount increment - must be <> 0.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal JSON body parameters

{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}

Parameters

Name	Type	Description
invoiceID (required)	string (path)	Invoice ID to get.
post data (required)	object (body)	Post data. If status is used, it must be in (active, deleted). `recordDate` must be in format 2006-01-02.

Data Parameters

Clearing Record post data object example

{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}

Responses

Code	Description	Links
200	InvoiceClearingRecord added.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord added

{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T10:11:27.765Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

GET/invoices-by-number/{invoiceNumber}/clearingrecords

Returns a list of all invoice Clearing Records for a given invoiceNumber.Up

Method Overview

The method returns a list of all invoice clearing records for a given invoice number.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

List of all InvoiceClearingRecords is returned that belongs to InvoiceClearing.
InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
By default, only clearing records with active status will be returned.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters

Name	Type	Description
invoiceNumber (required)	string (path)	Invoice number to get Clearing Records. If the invoice number contains slashes, it must be encoded. Example: For invoiceNumber = 00033/E/2021 value 00033%2FE%2F2021 should be in URL as invoiceNumber parameter (/ = %2F).
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range. Operator can be omitted and in that case, it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses

Code	Description	Links
200	List of InvoiceClearingRecords.	No links
default	Unexpected Error.	No links

Success Response 200: List of InvoiceClearingRecords

{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T10:50:05.688Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

POST/invoices-by-number/{invoiceNumber}/clearingrecords

Adds an invoice Clearing Record for a given invoiceNumber.Up

Method Overview

The method adds an invoice clearing record for a given invoice number.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal JSON body parameters

{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}

Parameters

Name	Type	Description
invoiceNumber (required)	string (path)	Invoice number to get Clearing Records. If the invoice number contains slashes, it must be encoded. Example: For invoiceNumber = 00033/E/2021 value 00033%2FE%2F2021 should be in URL as invoiceNumber parameter (/ = %2F).
post data (required)	object (body)	Post data. The recordDate must be in format 2006-01-02.

Post Data Parameters

{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}

Responses

Code	Description	Links
200	InvoiceClearingRecord added.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord added

{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T10:56:49.498Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

GET/invoices-by-uid/{invoiceUid}/clearingrecords

Returns a list of invoice Clearing Records for a given invoiceUid.Up

Method Overview

The method returns a list of invoice clearing records for a given invoice UID.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters

Name	Type	Description
invoiceUid (required)	string (path)	Invoice UID to get Clearing Records.
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses

Code	Description	Links
200	List of InvoiceClearingRecords.	No links
default	Unexpected Error.	No links

Success Response 200: List of InvoiceClearingRecords

{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T12:19:07.845Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

POST/invoices-by-uid/{invoiceUid}/clearingrecords

Adds an invoice Clearing Record for a given invoiceUid.Up

Method Overview

The method adds an invoice clearing record for a given invoice UID.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal Json body parameters

{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}

Parameters

Name	Type	Description
invoiceUID (required)	integer (path)	Invoice UID to get Clearing Records.
post data (required)	object (body)	Post data. If it is used, status must be in (active, deleted). The recordDate must be in format YYYY-MM-DD.

Post Data Parameters

{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}

Responses

Code	Description	Links
200	InvoiceClearingRecord added.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord added

{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T12:26:30.255Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

GET/invoices/{invoiceid}/clearingrecords/{recordid}

Returns an invoice clearing record with given recordid, which belongs to an invoice identified with invoiceid.Up

Method Overview

The method returns an invoice clearing record with given recordid, which belongs to invoice identified with invoiceid.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: privilege used in this endpoint is finance-invoices-own.view.

Parameters

Name	Type	Description
invoiceid (required)	integer (path)	Invoice ID.
recordid (required)	integer (path)	ID of invoiceClearingRecord to get.

Responses

Code	Description	Links
200	InvoiceClearingRecord returned successfully.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord returned successfully

{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2024-01-23T12:32:51.796Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

PUT/invoices/{invoiceid}/clearingrecords/{recordid}

Updates an existing InvoiceClearingRecord.Up

Method Overview

The method updates an existing InvoiceClearingRecord.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

After this operation, requested invoice clearing record will be marked as 'canceled' and new clearing record will be created and returned instead of the original.
InvoiceClearing value will be recalculated.
Canceled clearing records will be listed in the clearing records list, unlike deleted credit records, which are not listed.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be applied to billing balance. When corrected payment value is less than original payment value, it may happen that applying payment change will result in block balance, because funds are already spent. In that case the following error with HTTP status code 409 will be returned.

{
  "error":
    {
      "code": "CHANGE_PAYMENT_BLOCK_BALANCE",
      "message": "after delete of edit payment balance will be blocked because of insufficient funds available"
    }
}

If the API user still wants to edit a payment, the same API call should be used but with the parameter force=yes, effectively forcing the payment deletion.

Parameters

Name	Type	Description
invoceid (required)	integer (path)	Invoice ID.
recordid (required)	integer (path)	ID of invoiceClearingRecord to update.
force	string (query)	Forces edit of a payment for customer invoices even if operation will lead to customer balance blocking. Available values: yes, no. Default value: no.
corrected clearing record data (required)	object (body)	Corrects clearing record date for a clearing. See below an example.

Example object for correcting clearing record date for a clearing:

{
  "clearingTypeId": 0,
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0
}

Responses

Code	Description	Links
200	InvoiceClearingRecord updated successfully.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord updated successfully

{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2024-01-23T12:44:02.373Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

DELETE/invoices/{invoiceid}/clearingrecords/{recordid}

Deletes an invoice clearing record with given recordid.Up

Method Overview

The method deletes an invoice clearing record with given recordid.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

Deletion of Invoice Clearing records performs logical delete. Record's status will be set to delete. After this, clearing record will not be presented when listing.
InvoiceClearing value will be recalculated.
If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, deleting payment will be applied to billing balance resulting decreasing balance amount and increasing unpaid amount. It may happen that applying payment change will result in blocking balance, because the funds are already spent. In that case, the following error with HTTP status code 409 and body will be returned:

{
  "error":
    {
      "code": "CHANGE_PAYMENT_BLOCK_BALANCE",
      "message": "after delete of edit payment balance will be blocked because of insufficient funds available"
    }
}

If the API user still wants to delete a payment, the same API call should be used but with the parameter force=yes effectively forcing the payment deletion. In that case, after a payment is deleted, balance and account will be blocked for use because of insufficient funds.

Parameters

Name	Type	Description
invoceid (required)	integer (path)	Invoice ID.
recordid (required)	integer (path)	ID of invoiceClearingRecord to be deleted.
force	string (query)	Forces deletion of a payment for customer invoices, even if operation will lead to customer balance blocking. Available values: yes, no. Default value: no.

Responses

Code	Description	Links
200	InvoiceClearingRecord deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 200: InvoiceClearingRecord deleted successfully

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

3.3 Payment Type

The endpoint described in this section allows retrieving a list of payment types that can be used in invoices payment process.

The API endpoint belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

GET/payment-types

Returns a list of Payment TypesUp

Method Overview

The method returns a list of all available payment types.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters

Name	Type	Description
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, name, status, statusDt. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q	string (query)	General search criteria. Available fields: name, status.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: id, name, status, statusDt.

Responses

Code	Description	Links
200	List of Payment Types.	No links
default	Unexpected Error.	No links

Success Response 200: List of Payment Types

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "status": "active",
      "statusDt": "2021-03-11T12:29:43.054Z"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

3.4 Total Balances

The following endpoints are used for listing Total Balances.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

GET/total-balances

Returns a list of total balances.Up

Method Overview

The method returns a list of total balances with filtering and pagination features. Balance amounts(balance, accountsTotal, usage, availableAmount) and smsCount run-time value instead of snapshot values.

Parameters

Name	Type	Description
all	string (query)	Returns all data for given criteria. Available values: yes, no. Default value: no
page_size	integer (query)	Page size. Default value: 10.
page_number	integer (query)	Page number. Default value: 1.
paging	string (query)	Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields	string (query)	Comma separated list of attributes that needs to be returned in partial response.
sort	string (query)	Sort criteria: Format propertyName for ASC sorting, -propertyName for DESC sorting. Example: name = "name ASC", -name = "name DESC". Sort available properties: id, bizPartnerId, isDefault, currency, billingType, name, status, alertsPolicyId, alertsBaseAmount, amount, paidTotal, unpaidTotal, billedTotal, accountsTotal, smsCount, creditLimit, debitLimit, overdraftLimit, debitBalanceThreshold, bizPartnerName, bizPartnerShortName, usage, availableAmount, totalCredit, debitTotal, ownerId, ownerBpName, ownerBpBriefName, blockOnOutOfCredit.
operator(propertyName)	string (query)	Search criteria using following operators: isnull,isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, isDefault, currency, billingType, name, status, alertsPolicyId, alertsBaseAmount, amount, paidTotal, unpaidTotal, billedTotal, accountsTotal, smsCount, creditLimit, debitLimit, overdraftLimit, debitBalanceThreshold, bizPartnerName, bizPartnerShortName, usage, availableAmount, totalCredit, debitTotal, ownerId, ownerBpName, ownerBpBriefName, blockOnOutOfCredit. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If propertyName is 'q' and operator is eq or omitted, the property value will be used in general search across multiple attributes.

Responses

Code	Description	Links
200	Total Balances collection.	No links
default	Unexpected Error.	No links

Success Response 200: Total Balances Collection

{
  "data": [
    {
      "id": 0,
      "instanceId": 0,
      "bizPartnerId": 0,
      "isDefault": "string",
      "amount": 0,
      "currency": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "creditTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "billingType": 0,
      "status": "string",
      "name": "string",
      "smsCount": 0,
      "billingCreditLimit": 0,
      "billingDebitLimit": 0,
      "billingOverdraftLimit": 0,
      "billingDebitThreshold": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsBaseAmount": 0,
      "billingTypeName": "string",
      "billingTypeCodeName": "string",
      "billingModeName": "string",
      "currencyCode": "string",
      "currencyName": "string",
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "debitLimitTotal": 0,
      "availableAmount": 0,
      "usage": 0,
      "totalCredit": 0,
      "lastOpenEventHistoryId": 0,
      "billingCycleUnitId": 0,
      "billingCycle": 0,
      "billingStartDate": "2024-04-23",
      "nextBillingDate": "2024-04-23",
      "lastBillingRecordId": 0,
      "billingTriggerAmount": 0,
      "limitsCurrency": 0,
      "creditLimit": 0,
      "overdraftLimit": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "orderedPrepaidMode": "on",
      "overdraftPriceListId": 0,
      "firstCreditRecordId": 0,
      "currentCreditRecordId": 0,
      "invoiceCreation": "off",
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "reportCycleUnitId": 0,
      "reportCycleUnit": "string",
      "reportCycle": 0,
      "reportStartDate": "2024-04-23",
      "nextReportDate": "2024-04-23",
      "lastBillingReportId": 0,
      "invoiceSettings": {
        "extentNote": "string",
        "extentVatNote": "string",
        "extentAdditionalEmails": {
          "to": "string",
          "cc": "string",
          "bcc": "string"
        },
        "reminderMode": "disabled"
      },
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "alertsLanguage": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

GET/valid-prepaid-total-balances

Returns a prepaid total balance list.Up

Method Overview

The method lists active and blocked prepaid total balances with filtering and pagination features.

URL Parameters

Name	Type	Description
all	string (query)	Returns all data for given criteria.
page_size	integer (query)	Page size. Default value is 10.
page_number	integer (query)	Page number. Default value is 1.
paging	string (query)	Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields	string (query)	Comma separated list of attributes that needs to be returned in partial response.
sort	string (query)	Sort criteria: Format propertyName for ASC sorting, -propertyName for DESC sorting. Example: name = "name ASC", -name = "name DESC". Sort available properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault.
operator(propertyName)	string (query)	Search criteria using following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault. If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted. If operator is in or notin, a field value must be a comma separated list of values. If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range. Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.

Success Response 200: Total Balances collection

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "billingTypeCodeName": "PREPAID",
      "billingTypeName": "string",
      "status": "active",
      "smsCount": 0,
      "amount": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "creditTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "usage": 0,
      "totalCredit": 0,
      "availableAmount": 0,
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "overdraftLimit": 0,
      "billingCreditLimit": 0,
      "billingOverdraftLimit": 0,
      "limitsCurrency": 0,
      "billingDebitThreshold": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "overdraftPriceListId": 0,
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "reportCycleUnit": "string",
      "reportCycle": 0,
      "reportStartDate": "2024-04-26T12:12:25.264Z",
      "nextReportDate": "2024-04-26T12:12:25.264Z",
      "lastBillingReportId": 0,
      "alertsBaseAmount": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsLanguage": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "isDefault": "yes"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

GET/valid-postpaid-total-balances

Returns a postpaid total balance list.Up

Method Overview

The method lists active and blocked postpaid total balances with filtering and pagination features.

URL Parameters

Name	Type	Description
all	string (query)	Returns all data for given criteria.
page_size	integer (query)	Page size. Default value is 10.
page_number	integer (query)	Page number. Default value is 1.
paging	string (query)	Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields	string (query)	Comma separated list of attributes that needs to be returned in partial response.
sort	string (query)	Sort criteria: Format propertyName for ASC sorting, -propertyName for DESC sorting. Example: name = "name ASC", -name = "name DESC". Sort available properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault.
operator(propertyName)	string (query)	Search criteria using following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, debitLimit, debitTotal, isDefault. If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted. If operator is in or notin, a field value must be a comma separated list of values. If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range. Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.

Success Response 200: Total Balances collection

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "billingTypeCodeName": "PREPAID",
      "billingTypeName": "string",
      "status": "active",
      "smsCount": 0,
      "amount": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "usage": 0,
      "debitLimitTotal": 0,
      "availableAmount": 0,
      "billingTriggerAmount": 0,
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "creditLimit": 0,
      "overdraftLimit": 0,
      "billingDebitLimit": 0,
      "billingOverdraftLimit": 0,
      "limitsCurrency": 0,
      "billingDebitThreshold": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "overdraftPriceListId": 0,
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "billingCycleUnit": "string",
      "billingCycle": 0,
      "billingStartDate": "2024-04-26T12:12:25.277Z",
      "nextBillingDate": "2024-04-26T12:12:25.277Z",
      "lastBillingRecordId": 0,
      "alertsBaseAmount": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsLanguage": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "isDefault": "yes"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.5 Credit Record Types

This endpoint is used to get all Credit Records Types.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

GET/credit-record-types

Returns a list of supported credit record types.Up

Method Overview

The method returns a list of supported credit record types

Parameters

No parameters.

Responses

Code	Description	Links
200	Credit Record Types Collection.	No links
default	Unexpected Error.	No links

Success Response 200: Credit Record Types Collection

{
  "data": [
    {
      "id": 0,
      "typeUid": "string",
      "codeName": "string",
      "name": "string",
      "billingTypeId": 0,
      "createInvoice": "yes",
      "status": "active",
      "statusDt": "2024-04-22T08:53:30.940Z",
      "comment": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.6 Product Type Partners LOV

The endpoint described in this section allows retrieving a list of Product Type Partners LOV.

The API endpoint belong to the Biz-core domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/biz-core/v1

GET/product-type-partners-lov

Returns a list of Product Type Partners LOV.Up

Method Overview

The method returns a list of Product Type Partners LOV, i.e. all Business Partners associated with the product.

The required privileges: biz-core.view or biz-core.own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

URL Parameters

Name	Type	Description
all	string (query)	Returns all data for a given criteria. Available values: yes, no. Default value: no.
page_size	integer (query)	Page size. Default value: 10.
page_number	integer (query)	Page number. Default value: 1.
paging	string (query)	Paging options in the form of &paging=page_num,page_size, e.g. paging=1,10.
sort	string (query)	Sort options in the form of sort=-attribute1,attribute2,-attribute3.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, includeIds and by following attributes: id, name, country, countryName, vatNumber, vatApply, regNumber, legalFormId, language, status, languageName, legalForm, briefName, industryId, companySizeId, eMail, phone, fax, taxExempt, dunsNumber, industryName, companySize, ownerBpId, ownerBpName, ownerBpBriefName, instanceRole. Sort allowed attributes: id, name, country, countryName, vatNumber, vatApply, regNumber, legalFormId, language, status, languageName, legalForm, briefName, industryId, companySizeId, eMail, phone, fax, taxExempt, dunsNumber, industryName, companySize, ownerBpId, ownerBpName, ownerBpBriefName, instanceRole. If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted. If operator is in or notin, a field value must be a comma separated list of values. If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range. Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.

Responses

Code	Description	Links
200	A list of Product Type Partners LOV.	No links
default	Unexpected error.	No links

Success Response 200: List of Product Type Partners LOV

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "instanceRole": "string",
      "country": 0,
      "countryName": "string",
      "vatNumber": "string",
      "vatApply": "string",
      "regNumber": "string",
      "legalAddressId": 0,
      "status": "string",
      "parentId": 0,
      "legalFormId": 0,
      "language": "string",
      "languageName": "string",
      "legalForm": "string",
      "instanceOwnerName": "string",
      "briefName": "string",
      "detailsId": 0,
      "hasAttributes": "yes",
      "externalRefId": 0,
      "bizPartnerInstanceUid": "string",
      "statusActiveDt": "2021-01-26T09:51:36.318Z",
      "statusDt": "2021-01-26T09:51:36.318Z",
      "industryId": 0,
      "companySizeId": 0,
      "eMail": "string",
      "phone": "string",
      "fax": "string",
      "taxExempt": "string",
      "foundingD": "2021-01-26T09:51:36.318Z",
      "dunsNumber": "string",
      "industryName": "string",
      "companySize": "string",
      "ownerBpId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "selfOwner": "yes",
      "isIntercompany": "yes",
      "partnerTypeId": 0,
      "partnerTypeName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "totalPages": 0,
      "currentPage": 0,
      "perPage": 0,
      "count": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

3.7 Platform Owner Bank Accounts

The following endpoint is used for listing data of platform owner bank accounts.

The API endpoint belong to the Settings domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/settings/v1

GET/platform-owner-bank-accounts

Returns a list of bank accounts of a platform owner or a co-owner.Up

Method Overview

The method returns a list of bank accounts of a platform owner or a co-owner.

Authorization privilege needed for this endpoint: biz-core.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

When co-owners are enabled on the platform level, coOwnerId parameter should be sent. If coOwnerId is not sent, bank accounts for platform owner will be returned. If co-owners are disabled, coOwnerId should not be sent.

Parameters

Name	Type	Description
all	string (query)	Returns all data for a given criteria. Available values: yes, no. Default value: no.
page_number	integer (query)	Page number. Default value: 1.
page_size	integer (query)	Page size. Default value: 10.
paging	string (query)	Paging options in form of &paging=page_num page_size e.g. paging=1,10.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3.
operator(fieldName)	string (query)	Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, coOwnerId, bizPartnerId, bizPartnerName, bizPartnerBriefName, bizBankId, bizBankName, currency, currencyCode, currencyName, accountNumber, iban, isDefaultPerCurrency, status, name, swiftBic, accountType, countryName, ownerId, ownerBpName, ownerBpBriefName. If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted. If the operator is in or notin, the field value must be a comma separated list of values. If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range. Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue). Example: startswith(clientName)=hor, starts with hor in field 'clientName'. If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.

Responses

Code	Description	Links
200	List of bank accounts.	No links
default	Unexpected Error.	No links

Success Response 200: List of bank accounts

{
  "data": [
    {
      "id": 0,
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerBriefName": "string",
      "bizBankId": 0,
      "bizBankName": "string",
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "accountNumber": "string",
      "iban": "string",
      "isDefaultPerCurrency": "yes",
      "status": "active",
      "statusDt": "2021-03-11T12:56:00.268Z",
      "name": "string",
      "swiftBic": "string",
      "accountType": "account number",
      "countryName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

4. Data Models

Data Models define the structure of a JSON document and describe data related to the Top-Up API.

4.1 InvoiceCollection

InvoiceCollection object properties:

Name	Type	Description
data (required)	array	Array of Invoice objects.
meta (required)	object	CollectionMeta object.

4.2 Invoice

Invoice object properties:

Name	Type	Description
id	integer	Invoice ID.
invUid	string	Invoice UID.
instanceID	integer	Instance ID.
custID	integer	Customer ID.
custName	string	Customer name.
custShortName	string	Customer short name.
custAttn	string	Customer Attn. data.
custAddress	string	Customer address.
custAddress2	string	Customer address2.
custPost	string	Customer address postcode.
custCity	string	Customer address city.
custCountry	integer	Customer address country.
custPOBox	string	Customer address PO Box.
customerType	string	Customer type.
custVatNumber	string	Customer VAT number.
invType	integer	Invoice type.
invTypeName	string	Invoice type name.
templateID	integer	Template ID.
invDate	string($date)	Invoice date.
invoicingDate	string($date)	Invoicing date.
invoicingDatePolicy	string	Possible values: delivery, creation, approval.
invNumberFix	string	The fixed part of the invoice number, based on this field system will define next invoice number.
invNumberNum	integer	The invoice number (variable part) - it counts invoices for the same invNumberFix.
invNumber	string	Invoice number.
invPeriod	string	Invoice period.
invDueDate	string($date)	Invoice due date.
overDueDate	integer	Number of days over due date.
ownerVatNumber	string	Owner VAT number.
currency	integer	Currency.
currencyCode	string	Currency code.
amountNoVat	number($float)	Invoice amount without VAT (net amount). It can be negative when selfBilling is 'yes'.
amountVat	number($float)	Invoice amount including VAT. It can be negative when selfBilling is 'yes'.
vatPercent	number($float)	VAT percent.
vat	number($float)	Value added tax.
rounding	number($float)	Difference between an invoice total and amount including VAT value.
total	number($float)	Invoice gross amount. It can be negative when selfBilling is 'yes'.
totalUnpaid	number($float)	Invoice unpaid amount.
totalPaid	number($float)	Invoice paid amount.
vatInPrice	integer	VAT in price.
vatInTotal	integer	VAT in total.
status	string	Invoice status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived, imported.
insertDt	string($date‑time)	Date and time of insertion.
statusDt	string($date‑time)	Date and time of status.
deliveryDate	string($date)	Delivery date.
invPeriodStart	string($date)	Start of invoice period.
invPeriodEnd	string($date)	End of invoice period.
docsDeliveryStatus	string	Document delivery status.
docsDeliveryStatusDate	string($date‑time)	Document delivery status date and time.
docsDeliveryDlrStatus	string	Status of DLR.
docsDeliveryDlrStatusDate	string($date‑time)	DLR status date and time.
classCodeName	string	Class code name.
classDomain	string	Class domain.
classArea	string	Class area.
lang	string	Language.
paymentStatus	string	Possible values: none, open, on-hold, closed.
paymentStatusDate	string($date‑time)	Payment status date and time.
disputeStatus	string	DisputeStatus indicates whether the invoice is in dispute process or not.
disputeStatusDate	string($date‑time)	Dispute status date and time.
dataSourceId	integer	Data source ID.
dataSourceCodeName	string	Data source code name.
nettingInvoiceId	integer	Netting statement ID.
nettingInvoiceNumber	string	Netting statement number.
selfBilling	string	Indicator if an invoice is a credit note or not. If value is 'yes', when the document is in netting statement, it indicates that the document is in favor of a buyer, but issued by the seller. Also, if the document class is CREDIT_DEBIT_NOTE, it indicates that the document is a credit note, which is also in favor of buyer, but issued by the seller. Possible values: yes, no.
domainId	integer	Domain ID.
domainCodeName	string	Domain code name.
domainName	string	Domain name.
domainProduct	integer	Domain product.
accountManagerId	integer	Account manager ID.
accountManagerName	string	Account manager name.
disputeNextId	integer	Dispute ID.
collectionMode	string	Document collection mode. If member, the document is member of a collection. If lead, the document is a collection lead. By default collection mode is 'none', which indicates that the document is not a member of a collection nor collection lead. Possible values: none, member, lead.
collectionLeadId	integer	If document is a member of collection, this value contains id of collection lead document.
collectionLeadNumber	string	If document is a member of collection, this value contains number of collection lead document.
collectionLeadNettingInvoiceId	integer	Netting statement ID of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceNumber	string	Netting statement number of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceStatus	string	Netting statement status of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoicePaymentStatus	string	Netting statement payment status of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotal	string	Netting statement total amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalPaid	string	Netting statement total paid amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalUnpaid	string	Netting statement total unpaid amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
processingStatus	string	Indicates processing status of document if document has been assigned recalculation task(s) or some other kind of processing tasks. Possible values: none, scheduled, running, done, canceled.
comment	string	Description or comment in case invoice is a credit or debit note. Comment is not available when the invoice list is returned as a result of request, regardless of invoice class code name.
nettingInvoiceStatus	string	If invoice netting statement's member, this property contains netting statement status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived.
nettingPaymentStatus	string	If invoice is netting statement's member, this property is netting's payment status. Possible values: none, open, closed.
nettingTotal	number($float)	If invoice is netting statement's member, this property is netting's gross amount. It can be negative when selfBilling is 'yes'.
nettingTotalUnpaid	number($float)	If invoice is netting statement's member this property is netting's unpaid amount.
nettingTotalPaid	number($float)	If invoice is netting statement's member this property is netting's paid amount.
dtsSelectorId	integer	ID reference to DTS selector, e.g. for part payment invoice.
dtsSelectorCodeName	string	DTS selector code name.
sitInvoiceEmailImportId	integer	ID of an invoice email import.
billingBalance	object	BillingBalance object.
billingTypeName	string	Required and returned for control invoice.
smsCount	integer	Amount of messages. Required and returned for postpaid and control invoices.
syncStatus	string	SyncStatus is an invoice synchronization status. Possible values: none, waiting, syncing, done, error, misc, exported.
syncStatusDt	string($date‑time)	Synchronization status date and time.
syncMode	string	Synchronization mode. Possible values: disabled, primary, secondary.
reminderStatus	string	Reminder status. Possible values: enabled, disabled, open, closed, misc.
domesticCurrency	integer	Domestic currency.
domesticCurrencyCode	string	Domestic currency code.
domesticCurrencyAmountNoVAT	number($float)	Invoice amount in domestic currency without VAT.
domesticCurrencyAmountVAT	number($float)	Invoice amount in domestic currency with VAT.
domesticCurrencyTotal	number($float)	Invoice total amount in domestic currency.
domesticCurrencyRounding	number($float)	Invoice rounding, difference between domestic currency total and domestic currency amount with VAT.
domesticCurrencyRate	number($float)	Domestic currency rate is used to calculate domestic currency amounts.
industryName	string	Industry name.
ownerName	string	Owner name.
ownerId	integer	Owner ID.
ownerBpName	string	Owner business partner name.
ownerBpBriefName	string	Owner business partner brief name.
documentSync	object	An arbitrary JSON object, holding the document synchronization data. It is returned if syncStatus is done, error, misc, exported or invalid. Example: "documentSync": { "propertyA": "value A", "propertyB": "value B" }.

4.3 BillingBalance

BillingBalance object properties:

BillingBalance is Invoice Conditions which an invoice is associated to.

Name	Type	Description
id	integer	ID is the unique key for the Invoice Condition.
name	string	Invoice Condition name.
resourceUrl	string	Billing API URL that should be used to load billing balance resource.

4.4 CreditRecordInvoice

CreditRecordInvoice object properties:

Name	Type	Description
id	integer	Invoice ID.
creditUid	string	Credit UUID.
balanceId	integer	Balance ID.
activationDate	string($date)	Activation date.
creationDate	string($date)	Date of creation.
amount	number($double)	Amount.
currency	integer	Currency.
creditAmount	number($double)	Credit amount.
conditionalAmount	number($double)	Conditional amount.
paidAmount	number($double)	Paid amount.
unpaidAmount	number($double)	Unpaid amount.
status	string	Status.
isAggregateRecord	string	If record is aggregate record.
aggregateFromDate	string($date)	From Date for aggregate record.
invoiceId	integer	Invoice ID.
bizPartnerName	string	Business partner name.
bizPartnerShortName	string	Business partner short name.
bizPartnerId	integer	Business partner ID.
balanceName	string	Balance name.
typeId	integer	Type ID.
billingRecordId	integer	Billing record ID.
type	string	Type.
typeName	string	Type name.
createInvoice	string	Possible values: yes, no.
billingType	integer	Billing type.
currencyCode	string	Currency code.
currencyName	string	Currency name.
orderingStatus	string	Possible values: off, available, in-use, used.
orderingStatusDt	string($date‑time)	Ordering status date-time.
selectedPriceListId	integer	Selected price list ID.
ownerId	integer	Owner ID.
ownerBpName	string	Owner Business Partner ID.
ownerBpBriefName	string	Owner Business Partner brief name.
description	string	Description.
comment	string	Comment.
invoice	object	Invoice object.

4.5 CreditRecordInvoiceCreate

CreditRecordInvoiceCreate object properties:

Name	Type	Description
balanceId (required)	integer	Balance ID.
amount (required)	number($double)	Amount.
comment	string	Comment.
payment	object	PaymentData object.

4.6 PaymentData

PaymentData object properties:

Name	Type	Description
fullyPaid	boolean	If invoice is fully paid.
paymentType	integer	Payment type can be 1 - bank transfer, 2 - credit card, 3 - PayPal, 4 - Cash.
bankAccountId	integer	Bank account.

4.7 InvoiceClearingRecordCollection

InvoiceClearingRecordCollection object properties:

Name	Type	Description
data (required)	array	Array of InvoiceClearingRecord objects.
meta (required)	object	CollectionMeta object.

4.8 InvoiceClearingRecord

InvoiceClearingRecord object properties:

Name	Type	Description
id	integer	Invoice ID.
clearingId	integer	Clearing ID.
clearingTypeId	integer	Clearing type ID. Possible values: 1, 2, 3, 4.
clearingTypeCodeName	string	Clearing type code name. Possible values: Invoice, Payment, Interest, Reminder.
recordDate	string($date)	Clearing record date.
paymentTypeId	integer	Payment type ID, reference to paymentTypeName. Possible values: 1, 2, 3, 4.
paymentTypeName	string	Payment type name. Possible values: Bank Transfer, Credit Card, Paypal, Cash.
amountIncrement	number($float)	Amount increment.
paidAmount	number($float)	Paid amount.
paymentReference	string	Payment reference.
comment	string	Comment.
status	string	Clearing record status.
statusDate	string($date‑time)	Status date.
revokeUserId	string	Revoke user ID.
revokeUserName	string	Revoke username.
revokeComment	string	Comment on revocation.
bankAccountId	integer	Reference to bank account.
bankAccountName	string	Bank account name.
bankAccountNumber	string	Bank account number.
bankAccountIban	string	Bank account IBAN.
bankAccountSwiftBic	string	Bank account SWIFT/BIC code.

4.9 InvoiceClearingRecordPost

InvoiceClearingRecordPost object properties:

Name	Type	Description
clearingTypeId	integer	Clearing type ID.
recordDate	string($date)	Clearing record date.
paymentTypeId	integer	Payment type ID.
amountIncrement	number($float)	Amount increment.
paidAmount	number($float)	Paid amount.
paymentReference	string	Payment reference.
comment	string	Comment.
bankAccountId	integer	Reference to bank account which money was received or paid to.

4.10 InvoiceClearingRecordUpdate

InvoiceClearingRecordUpdate object properties:

Name	Type	Description
clearingTypeId	integer	Clearing type ID.
recordDate	string($date)	Clearing record date.
paymentTypeId	integer	Payment type ID.
amountIncrement	number($float)	Amount increment.
paidAmount	number($float)	Paid amount.
paymentReference	string	Payment reference.
comment	string	Comment.
revokeUserId	string	Revoke user ID.
revokeUserName	string	Revoke username.
revokeComment	string	Comment on revocation.
bankAccountId	integer	Reference to bank account which money was received or paid to.

JSON Example

{
  "clearingTypeId": 0,
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0
}

4.11 PaymentTypeCollection

PaymentTypeCollection object properties:

Name	Type	Description
data (required)	array	Array of PaymentType objects.
meta (required)	object	CollectionMeta object.

4.12 PaymentType

PaymentType object properties:

Name	Type	Description
id	integer	Payment type ID.
name	string	Payment type name.
status	string	Payment status. Possible values: active, inactive.
statusDt	string($date‑time)	Date and time of payment status.

JSON Example

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "status": "active",
      "statusDt": "2021-03-11T12:29:43.054Z"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

4.13 CreditRecordTypeCollection

CreditRecordTypeCollection object properties:

Name	Type	Description
data (required)	array	Array of CreditRecordType objects.
meta (required)	object	CollectionMeta object.

4.14 CreditRecordType

CreditRecordType object properties:

Name	Type	Description
id (required)	integer	Credit Record Type ID.
typeUid (required)	string	Credit Record Type type UID.
codeName (required)	string	Credit Record Type code name.
name (required)	string	Credit Record Type name.
billingTypeId (required)	integer	Credit Record Type billing type ID.
createInvoice (required)	string	If Credit Record Type create an invoice. Possible values: yes, no.
status	string	Credit Record Type status. Possible values: active, inactive.
statusDt	string($date‑time)	Date and time of a status.
comment	string	Comment.

JSON Example

{
  "data": [
    {
      "id": 0,
      "typeUid": "string",
      "codeName": "string",
      "name": "string",
      "billingTypeId": 0,
      "createInvoice": "yes",
      "status": "active",
      "statusDt": "2024-04-22T08:53:30.940Z",
      "comment": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

4.15 TotalBalancePrepaidCollection

TotalBalancePrepaidCollection object properties:

Name	Type	Description
data (required)	array	Array of Total Balance Prepaid objects.
meta (required)	object	CollectionMeta object.

4.16 TotalBalancePrepaid

TotalBalancePrepaid object properties:

Name	Type	Description
id	integer	Total Balance Prepaid ID.
name	string	Total Balance Prepaid name.
bizPartnerId	integer	Business partner ID.
bizPartnerName	string	Business partner name.
bizPartnerShortName	string	Business partner short name.
billingTypeCodeName	string	Billing type code name. Possible values: PREPAID, POSTPAID.
billingTypeName	string	Billing type name.
status	string	Possible values: active, blocked.
smsCount	integer	Amount of messages. Required and returned for postpaid and control invoices.
amount	number($double)	Amount.
accountsTotal	number($double)	Accounts total.
billedTotal	number($double)	Billed total.
creditTotal	number($double)	Credit total.
paidTotal	number($double)	Paid total.
unpaidTotal	number($double)	Unpaid total.
usage	number($double)	Usage.
totalCredit	number($double)	Total credit.
availableAmount	number($double)	Available amount.
currency	integer	Currency.
currencyCode	string	Currency code.
currencyName	string	Currency name.
overdraftLimit	number($double)	Overdraft limit.
billingCreditLimit	number($double)	Billing credit limit.
billingOverdraftLimit	number($double)	Billing overdraft limit.
limitsCurrency	integer	Limit currency.
billingDebitThreshold	number($double)	Billing debit threshold.
disputePercent	number($float)	Dispute percent.
disputeValue	number($double)	Dispute value.
paymentTermsDays	integer	Payment terms days.
pricePackageMode	string	Price package mode. Possible values: on, off.
pricePackageId	integer	Price package ID.
overdraftPriceListId	integer	Over draft price list ID.
invoiceSending	string	Invoice sending. Possible values: on, off.
blockOnOutOfCredit	string	Indicator if balance and corresponding accounts will be blocked on out of credit event. For prepaid balance default value is 'on' and for postpaid and other billing types, default value is 'off'. Possible values: on, off.
minUsageAmount	number($double)	Postpaid setting about minimum usage amount on total balance level (considering billing_record.amount). This is always positive value or zero, which means there is no min_usage_amount. If usage amount is less than min_usage_amount, then additional surcharge will be added on invoice to provide that invoice amount (without VAT) is not less than min_usage_amount. If there is min_usage_amount on total_balance level then all such amounts on billing accounts are ignored.
reportCycleUnit	string	Report cycle unit code name.
reportCycle	integer	The length of prepaid reporting cycle, the default is zero. This field goes in pair with reportCycleUnit, example 2 month(s), 1 week, etc.
reportStartDate	string($date‑time)	Represents start date of first prepaid reporting cycle. If both fields, reportCycle and reportCycleUnit are greater than 0 then prepaid reporting is turned ON, otherwise it is considered to be OFF. If value for reportStartDate is not supplied and prepaid reporting is ON, API will calculate report start date automatically based on reporting period.
nextReportDate	string($date‑time)	Represents date when next prepaid report should be crated for current balance.
lastBillingReportId	integer	ID of last created billing report.
alertsBaseAmount	number($double)	Alerts base amount.
alertsPolicyId	integer	Alerts policy ID.
alertsPolicyName	string	Alerts policy name.
alertsLanguage	string	alerts language.
ownerId	integer	Owner ID.
ownerBpName	string	Owner Business Partner name.
ownerBpBriefName	string	Business Partner brief name.
isDefault	string	Possible values: on, off.

4.17 TotalBalancePostpaidCollection

TotalBalancePostpaidCollection object properties:

Name	Type	Description
data (required)	array	Array of Total Balance Postpaid objects.
meta (required)	object	CollectionMeta object.

4.18 TotalBalancePostpaid

TotalBalancePostpaid object properties:

Name	Type	Description
id	integer	Total Balance Postpaid ID.
name	string	Total Balance Postpaid name.
bizPartnerId	integer	Business partner ID.
bizPartnerName	string	Business partner name.
bizPartnerShortName	string	Business partner short name.
billingTypeCodeName	string	Billing type code name. Possible values: PREPAID, POSTPAID.
billingTypeName	string	Billing type name.
status	string	Possible values: active, blocked.
smsCount	integer	Amount of messages. Required and returned for postpaid and control invoices.
amount	number($double)	Amount.
accountsTotal	number($double)	Accounts total.
billedTotal	number($double)	Billed total.
paidTotal	number($double)	Paid total.
unpaidTotal	number($double)	Unpaid total.
usage	number($double)	Usage.
debitLimitTotal	number($double)	Debit limit total amount.
availableAmount	number($double)	Available amount.
billingTriggerAmount	number($double)	Billing trigger amount.
currency	integer	Currency.
currencyCode	string	Currency code.
currencyName	string	Currency name.
creditLimit	number($double)	Credit limit.
overdraftLimit	number($double)	Overdraft limit.
billingDebitLimit	number($double)	Billing debit limit.
billingOverdraftLimit	number($double)	Billing overdraft limit.
limitsCurrency	integer	Limit currency.
billingDebitThreshold	number($double)	Billing debit threshold.
disputePercent	number($float)	Dispute percent.
disputeValue	number($double)	Dispute value.
paymentTermsDays	integer	Payment terms days.
pricePackageMode	string	Price package mode. Possible values: on, off.
pricePackageId	integer	Price package ID.
overdraftPriceListId	integer	Over draft price list ID.
invoiceSending	string	Invoice sending. Possible values: on, off.
blockOnOutOfCredit	string	Indicator if balance and corresponding accounts will be blocked on out of credit event. For prepaid balance default value is 'on' and for postpaid and other billing types, default value is 'off'. Possible values: on, off.
minUsageAmount	number($double)	Postpaid setting about minimum usage amount on total balance level (considering billing_record.amount). This is always positive value or zero, which means there is no min_usage_amount. If usage amount is less than min_usage_amount, then additional surcharge will be added on invoice to provide that invoice amount (without VAT) is not less than min_usage_amount. If there is min_usage_amount on total_balance level then all such amounts on billing accounts are ignored.
reportCycle	integer	The length of prepaid reporting cycle, the default is zero. This field goes in pair with reportCycleUnit, example 2 month(s), 1 week, etc.
billingCycle	integer	The length of postpaid billing cycle, the default is zero. This field goes in pair with billingCycleUnit, example 2 month(s), 1 week, etc.
billingStartDate	string($date‑time)	Represents start date of first postpaid billing cycle.
nextBillingDate	string($date‑time)	Represents date when next postpaid billing record should be crated for current balance.
lastBillingReportId	integer	ID of last created billing record.
alertsBaseAmount	number($double)	Alerts base amount.
alertsPolicyId	integer	Alerts policy ID.
alertsPolicyName	string	Alerts policy name.
alertsLanguage	string	alerts language.
ownerId	integer	Owner ID.
ownerBpName	string	Owner Business Partner name.
ownerBpBriefName	string	Business Partner brief name.
isDefault	string	Possible value: yes.

4.19 ProductTypePartnersLovCollection

ProductTypePartnersLovCollection object properties:

Name	Type	Description
data (required)	array	An array of ProductTypePartnersLov objects.
meta (required)	object	CollectionMeta object.

4.20 ProductTypePartnersLov

ProductTypePartnersLov object properties:

Name	Type	Description
id	integer	ProductTypePartnersLov ID.
name	string	ProductTypePartnersLov name.
instanceRole	string	Instance role.
country	integer	Country code.
countryName	string	Country name.
vatNumber	string	VAT number.
vatApply	string	Possible values: yes, no, unknown.
regNumber	string	Registration number.
legalAddressId	integer	Legal address ID.
status	string	Status.
parentId	integer	Parent ID.
legalFormId	integer	Legal form ID.
language	string	Language.
languageName	string	Language name.
legalForm	string	Legal form.
instanceOwnerName	string	Instance owner name.
briefName	string	Brief name.
detailsId	integer	Details ID.
hasAttributes	string	Possible values: yes, no.
externalRefId	integer	External reference ID.
bizPartnerInstanceUid	string	BizPartnerInstance UID.
statusActiveDt	string($date‑time)	Date of active status.
statusDt	string($date‑time)	Status date.
industryId	integer	Industry ID.
companySizeId	integer	Company size ID.
eMail	string	E-mail.
phone	string	Phone.
fax	string	Fax.
taxExempt	string	Tax exemption.
foundingD	string($date‑time)	Founding date.
dunsNumber	string	DUNS number.
industryName	string	Industry name.
companySize	string	Company size.
ownerBpId	integer	Owner business partner ID.
ownerBpName	string	Business Partner name.
ownerBpBriefName	string	Business Partner brief name.
selfOwner	string	Possible values: yes, no.
isIntercompany	string	Possible values: yes, no.
partnerTypeId	integer	Partner type ID.
partnerTypeName	string	Partner type name.

4.21 BankAccountCollection

BankAccountCollection object properties:

Name	Type	Description
data (required)	array	Array of BankAccount objects.
meta (required)	object	CollectionMeta object.

4.22 BankAccount

BankAccount object properties:

Name	Type	Description
id	integer	Bank account ID.
bizPartnerId	integer	Business partner ID. maxLength: 10.
bizPartnerName	string	Business partner name.
bizPartnerBriefName	string	Business partner brief name.
bizBankId	integer	Bank ID. maxLength: 10.
bizBankName	string	Bank name.
currency	integer	Currency. maxLength: 5.
currencyCode	string	Currency code.
currencyName	string	Currency name.
accountNumber	string	Account number. maxLength: 40.
iban	string	Account IBAN. maxLength: 50.
isDefaultPerCurrency	string	Determines if an account will be default for bizPartnerId and currency. Only one account can be default. Possible values: yes, no.
status	string	Bank account status.
statusDt	string($date‑time)	Bank account status date and time.
name	string	Bank account name.
swiftBic	string	Bank account SWIFT/BIC code. maxLength: 30.
accountType	string	Account type. Possible values: account number, iban.
countryName	string	Country name.
ownerId	integer	Owner ID.
ownerBpName	string	Owner business partner name.
ownerBpBriefName	string	Owner business partner brief name.

JSON Example

{
  "data": [
    {
      "id": 0,
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerBriefName": "string",
      "bizBankId": 0,
      "bizBankName": "string",
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "accountNumber": "string",
      "iban": "string",
      "isDefaultPerCurrency": "yes",
      "status": "active",
      "statusDt": "2021-03-11T12:56:00.268Z",
      "name": "string",
      "swiftBic": "string",
      "accountType": "account number",
      "countryName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

4.23 Error

Error object properties:

Name	Type	Description
code (required)	integer($int32)	Error code.
message (required)	string	Error message.

JSON Example

{
  "Code": 0,
  "Message": "string"
}

4.24 CollectionMeta

CollectionMeta object properties:

Name	Type	Description
pagination (required)	object	CollectionMetaPagination object.

4.25 CollectionMetaPagination

CollectionMetaPagination object properties:

Name	Type	Description
total (required)	integer	Total number of rows.
count (required)	integer	A number of rows in the current page.
perPage (required)	integer	The maximum rows per page.
currentPage (required)	integer	The current page number.
totalPages (required)	integer	Total number of pages.
links (required)	object	CollectionMetaPaginationLinks object.

4.26 CollectionMetaPaginationLinks

CollectionMetaPaginationLinks object properties:

Name	Type	Description
first	string	Link to the first page.
last	string	Link to the last page.
prev	string	Link to the previous page.
next	string	Link to the next page.

JSON Example

"meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }

Top-Up API

1. Introduction

1.1 API Call Examples

2. Methods Overview

2.1 Invoices

2.2 Invoice Clearing

2.3 Payment Type

2.4 Total Balances

2.5 Credit Record Types

2.6 Product Type Partners LOV

2.7 Platform Owner Bank Accounts

3. Methods Details

3.1 Invoices

Method Overview

Parameters

Responses

Success Response 200: List of Invoices

Error Response Unexpected Error: Default

Method Overview

Parameters

Success Response 200: List of Invoices

Error Response Unexpected Error: Default

Method Overview

Parameters

Data Parameters

Responses

Success Response: 200 Created Credit Record Object with Related Invoice

Error Response Unexpected Error: Default

3.2 Invoice Clearing

Method Overview

Parameters

Responses

Success Response 200: List of InvoiceClearingRecords

Error Response Unexpected Error: Default

Method Overview

Minimal JSON body parameters

Parameters

Data Parameters

Responses

Success Response 200: InvoiceClearingRecord added

Error Response Unexpected Error: Default

Method Overview

Parameters

Responses

Success Response 200: List of InvoiceClearingRecords

Error Response Unexpected Error: Default

Method Overview

Minimal JSON body parameters

Parameters

Post Data Parameters

Responses

Success Response 200: InvoiceClearingRecord added

Error Response Unexpected Error: Default

Method Overview

Parameters

Responses

Success Response 200: List of InvoiceClearingRecords

Error Response Unexpected Error: Default

Method Overview

Minimal Json body parameters

Parameters

Post Data Parameters

Responses

Success Response 200: InvoiceClearingRecord added

Error Response Unexpected Error: Default

Method Overview

Parameters

Responses

Success Response 200: InvoiceClearingRecord returned successfully

Error Response Unexpected Error: Default

Method Overview

Parameters

Responses

Success Response 200: InvoiceClearingRecord updated successfully

Error Response Unexpected Error: Default

Method Overview

Parameters

Responses

Success Response 200: InvoiceClearingRecord deleted successfully

Error Response Unexpected Error: Default