Finance Documents API

1. Introduction

The HORISEN Finance Documents API provides you with endpoints that give you access to all your financial documents. It returns a list of documents for given parameters with all their items.

The HORISEN Finance Documents API belongs to the Finance domain and the endpoint URL is:

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

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.

It uses the HORISEN implementation of the OAuth 2.0 protocol. For more information, refer to OAuth2 Authentication Guidelines page.

2. Methods Overview

2.1 Document

The endpoint for financial documents.

2.2 Invoice

The endpoints for updating the status of financial documents.

2.3 Invoice Files

The endpoint to work with invoices' files.

3. Methods Details

3.1 Document

The endpoint for financial documents.

Method Overview

The method returns a list of documents for export.

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.

Traffic Reports are possible only for Customer Postpaid and Control Invoices. To get Traffic Reports for those invoice types, add trafficReports for the embed URL query parameter.

Parameters

Name	Type	Description
embed	string (query)	Embed options in the form of embed=field1,field2,field3 (comma-separated list). Currently supported value is: trafficReports.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Maximum value for page size is 50. Default value is 10.
paging	string (query)	Paging options in form of &paging=page_num,page_size. Example: If we put "paging=1,10" as query parameter, the API will return the first ten items.
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: documentUuid, id, instanceId, bizPartnerId, bizPartnerCountry, bizPartnerExternalRefId, bizPartnerName, bizPartnerBriefName, bizPartnerType, bizPartnerAttn, bizPartnerAddress, bizPartnerPost, bizPartnerCity, bizPartnerVatNumber, documentDate, deliveryDate, documentNumber, documentNumberMask, documentNumberNum, dueDate, periodStart, periodEnd, currency, currencyCode, amountNoVat, amountVat, vatPercent, vat, rounding, total, totalUnpaid, totalPaid, domesticCurrency, domesticCurrencyCode, domesticCurrencyRate, domesticAmountNoVat, domesticAmountVat, domesticRounding, domesticTotal, status, insertDt, statusDt, paymentStatus, paymentStatusDate, lang, documentType, documentTypeName, selfBilling, domainId, domainCodeName, dataSourceId, dataSourceCodeName, documentClassCodeName, documentClassDomain, documentClassArea, dataSourceSelector, syncStatus, syncStatusDt, disputeStatus, docsDeliveryStatus, docsDeliveryStatusDate, ownerId, ownerBpName, ownerBpBriefName, documentSync. If the operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted. If the operator is in or notin, a field value must be a comma separated list of values. If the 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.
q	string (query)	General search criteria. Available fields: documentUuid, bizPartnerExternalRefId, bizPartnerName, bizPartnerBriefName, bizPartnerType, bizPartnerAttn, bizPartnerAddress, bizPartnerPost, bizPartnerCity, bizPartnerVatNumber, documentNumber, documentNumberMask, currencyCode, domesticCurrencyCode, status, paymentStatus, lang, documentTypeName, domainCodeName, dataSourceCodeName, documentClassCodeName, documentClassDomain, documentClassArea, dataSourceSelector, syncStatus, disputeStatus, docsDeliveryStatus, ownerId, ownerBpName, ownerBpBriefName.
sort	string (query)	Sorting options in form of sort=-attribute1,attribute2,-attribute3. Sorting available fields: documentUuid, id, instanceId, bizPartnerId, bizPartnerCountry, bizPartnerExternalRefId, bizPartnerName, bizPartnerBriefName, bizPartnerType, bizPartnerAttn, bizPartnerAddress, bizPartnerPost, bizPartnerCity, bizPartnerVatNumber, documentDate, deliveryDate, documentNumber, documentNumberMask, documentNumberNum, dueDate, periodStart, periodEnd, currency, currencyCode, amountNoVat, amountVat, vatPercent, vat, rounding, total, totalUnpaid, totalPaid, domesticCurrency, domesticCurrencyCode, domesticCurrencyRate, domesticAmountNoVat, domesticAmountVat, domesticRounding, domesticTotal, status, insertDt, statusDt, paymentStatus, paymentStatusDate, lang, documentType, documentTypeName, selfBilling, domainId, domainCodeName, dataSourceId, dataSourceCodeName, documentClassCodeName, documentClassDomain, documentClassArea, dataSourceSelector, syncStatus, syncStatusDt, disputeStatus, docsDeliveryStatus, docsDeliveryStatusDate, ownerId, ownerBpName, ownerBpBriefName, documentSync.

Responses

Code	Description	Links
200	List of documents.	No links
default	Unexpected error. List of errors.	No links

Success Response 200: List of Documents

{
  "data": [
    {
      "documentUuid": "string",
      "id": 0,
      "instanceId": 0,
      "bizPartnerId": 0,
      "bizPartnerCountry": 0,
      "bizPartnerExternalRefId": "string",
      "bizPartner": {
        "name": "string",
        "briefName": "string",
        "partnerType": "string",
        "attn": "string",
        "address": "string",
        "post": "string",
        "city": "string",
        "vatNumber": "string",
        "customAttributes": [
          {
            "codeName": "string",
            "value": "string"
          }
        ]
      },
      "documentDate": "2025-02-12",
      "deliveryDate": "2025-02-12",
      "documentNumber": "string",
      "documentNumberMask": "string",
      "documentNumberNum": 0,
      "dueDate": "2025-02-12",
      "periodStart": "2025-02-12",
      "periodEnd": "2025-02-12",
      "currency": 0,
      "currencyCode": "string",
      "amountNoVat": 0,
      "amountVat": 0,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0,
      "totalUnpaid": 0,
      "totalPaid": 0,
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyRate": 0,
      "domesticAmountNoVat": 0,
      "domesticAmountVat": 0,
      "domesticRounding": 0,
      "domesticTotal": 0,
      "status": "draft",
      "insertDt": "2025-02-12T09:19:47.640Z",
      "statusDt": "2025-02-12T09:19:47.640Z",
      "paymentStatus": "none",
      "paymentStatusDate": "2025-02-12T09:19:47.640Z",
      "domainId": 0,
      "domainCodeName": "string",
      "documentClassCodeName": "string",
      "documentClassDomain": "string",
      "documentClassArea": "string",
      "selfBilling": "yes",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "dataSourceSelector": "string",
      "dataSource": {
        "id": 0,
        "billingTotalBalance": {
          "id": 0,
          "instanceId": 0,
          "bizPartnerId": 0,
          "currency": 0,
          "currencyCode": "string",
          "billingTypeCodeName": "string",
          "name": "string",
          "customAttributes": [
            {
              "codeName": "string",
              "value": "string"
            }
          ]
        }
      },
      "lang": "string",
      "documentType": 0,
      "documentTypeName": "string",
      "syncStatus": "none",
      "syncStatusDt": "2025-02-12T09:19:47.641Z",
      "disputeStatus": "none",
      "docsDeliveryStatus": "none",
      "docsDeliveryStatusDate": "2025-02-12T09:19:47.641Z",
      "note": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {},
      "items": [
        {
          "id": 0,
          "documentId": 0,
          "ordNum": 0,
          "name": "string",
          "quantity": 0,
          "measureUnit": "string",
          "price": 0,
          "totalNoVat": 0,
          "totalVat": 0,
          "dataSourceId": 0,
          "dataSourceCodeName": "string",
          "dataSourceForeignKey": 0,
          "dataSourceSelector": "string",
          "dataSource": {
            "id": 0,
            "documentId": 0,
            "billingAccount": {
              "id": 0,
              "instanceId": 0,
              "bizPartnerId": 0,
              "currency": 0,
              "currencyCode": "string",
              "billingTypeCodeName": "string",
              "name": "string",
              "customAttributes": [
                {
                  "codeName": "string",
                  "value": "string"
                }
              ],
              "smsConnections": [
                {
                  "id": 0,
                  "instanceId": 0,
                  "name": "string",
                  "authName": "string",
                  "protocol": "string"
                }
              ],
              "mnpConnections": [
                {
                  "id": 0,
                  "instanceId": 0,
                  "name": "string",
                  "authName": "string",
                  "protocol": "string"
                }
              ]
            }
          }
        }
      ],
      "trafficReports": [
        {
          "bizPartnerId": 0,
          "bizPartnerBriefName": "string",
          "bizPartnerExtRefId": "string",
          "billingAccountId": 0,
          "billingAccountName": "string",
          "countryId": 0,
          "countryName": "string",
          "countryCode2": "string",
          "operatorId": 0,
          "operatorName": "string",
          "mcc": "string",
          "mnc": "string",
          "startDt": "2025-02-12T09:19:47.641Z",
          "endDt": "2025-02-12T09:19:47.641Z",
          "priceSinceDt": "2025-02-12T09:19:47.641Z",
          "smsCnt": 0,
          "currency": 0,
          "currencyCode": "string",
          "price": 0,
          "totalAmount": 0
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

Error Response Unexpected Error: Default

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

3.2 Invoice

The endpoints for updating the status of financial documents.

Method Overview

This method is used to change the sync status of an invoice - this is a document synchronization status.
The synchronization is done between our system and some independent financial software. There is extent DocumentSync object with more details about the process. The status value can be one of: none, waiting, syncing, done, error, misc, invalid or exported.

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

Possible Errors

Name	Description
INVOICE_NOTFOUND	Invoice is not found.
UNKNOWN_STATUS	Unknown status.
Invalid value	The status value can be one of: none, waiting, syncing, done, error, misc, exported or invalid.

Parameters

Name	Type	Description
invoiceid (required)	integer (path)	Invoice ID.
post data (required)	object (body)	Possible values are: none - syncing is never done nor in schedule, waiting - waiting to start syncing, syncing - syncing in progress, done - successfully done, exported - document is exported, file to be imported into the external system is successfully created, error - some error happened during syncing, invalid - syncing was "done" but after that source document is changed, so target document is out of sync (example: source document is canceled), misc - temporary status for internal use.

Data Parameters

post data object example

{
  "status": "none",
  "reportData": {},
  "documentSync": {}
}

Responses

Code	Description	Links
200	Invoice sync status changed.	No links
default	Unexpected Error	No links

Success Response 200: Invoice sync status changed

{
  "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": "2022-02-22",
  "invoicingDate": "2022-02-22",
  "invoicingDatePolicy": "delivery",
  "invNumberFix": "string",
  "invNumberNum": 0,
  "invNumber": "string",
  "invPeriod": "string",
  "invDueDate": "2022-02-22",
  "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": "2022-02-22T14:35:48.657Z",
  "statusDt": "2022-02-22T14:35:48.657Z",
  "deliveryDate": "2022-02-22",
  "invPeriodStart": "2022-02-22",
  "invPeriodEnd": "2022-02-22",
  "docsDeliveryStatus": "string",
  "docsDeliveryStatusDate": "2022-02-22T14:35:48.657Z",
  "docsDeliveryDlrStatus": "string",
  "docsDeliveryDlrStatusDate": "2022-02-22T14:35:48.657Z",
  "classCodeName": "string",
  "classDomain": "string",
  "classArea": "string",
  "lang": "string",
  "paymentStatus": "none",
  "paymentStatusDate": "2022-02-22T14:35:48.657Z",
  "disputeStatus": "string",
  "disputeStatusDate": "2022-02-22T14:35:48.657Z",
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "nettingInvoiceId": 0,
  "nettingInvoiceNumber": "string",
  "selfBilling": "yes",
  "domainId": 0,
  "domainCodeName": "string",
  "domainName": "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": "2022-02-22T14:35:48.657Z",
  "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": {}
}

Error Response Unexpected Error: Default

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

Extensions

Field	Value
x-codegen-request-body-name	"sync data"

Method Overview

This method is used to change the sync status of invoice for a list of invoices. Status can be in (none, waiting, syncing, error, misc, exported).

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

Parameters

Name	Type	Description
invoices-list (required)	integer (path)	List of invoice IDs separated by comma.
sync data (required)	object (body)	Sync status must be in (none, waiting, syncing, error, misc, exported).

Data Parameters

post data object example

{
  "status": "none",
  "reportData": {},
  "documentSync": {}
}

Responses

Code	Description	Links
200	Invoices docs status changed.	No links
default	Unexpected Error	No links

Success Response 200: Invoices docs status changed

{
  "result": [
    {
      "id": "string",
      "opStatus": "OK",
      "error": {
        "Code": 0,
        "Message": "string"
      }
    }
  ]
}

Error Response Unexpected Error: Default

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

Method Overview

This method is used to change the docs delivery status of an invoice.

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

Possible Errors

Name	Description
INVOICE_NOTFOUND	Invoice is not found.
Invalid value	The status value can be one of: none, waiting, sending, sent, error or misc.

Parameters

Name	Type	Description
invoiceid (required)	integer (path)	Invoice ID.
docs delivery status data (required)	object (body)	Data required to change docs delivery status - status of delivering invoice documents for customer (via certain communication channel as e-mail or mail). The status value can be: none - document is not ready for delivery, i.e. it is not approved nor canceled, waiting - document is ready for sending, sending - the sending is in progress, sent - document is sent, error - sending failed, misc - this is temporary status, document should not be considered for sending until this status is changed (probably by manual intervention in db).

Data Parameters

post data object example

{
  "status": "none"
}

Responses

Code	Description	Links
200	Invoice docs delivery status changed.	No links
default	Unexpected Error	No links

Success Response 200: Invoice docs delivery status changed

{
  "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": "2022-02-22",
  "invoicingDate": "2022-02-22",
  "invoicingDatePolicy": "delivery",
  "invNumberFix": "string",
  "invNumberNum": 0,
  "invNumber": "string",
  "invPeriod": "string",
  "invDueDate": "2022-02-22",
  "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": "2022-02-22T14:45:45.286Z",
  "statusDt": "2022-02-22T14:45:45.286Z",
  "deliveryDate": "2022-02-22",
  "invPeriodStart": "2022-02-22",
  "invPeriodEnd": "2022-02-22",
  "docsDeliveryStatus": "string",
  "docsDeliveryStatusDate": "2022-02-22T14:45:45.286Z",
  "docsDeliveryDlrStatus": "string",
  "docsDeliveryDlrStatusDate": "2022-02-22T14:45:45.286Z",
  "classCodeName": "string",
  "classDomain": "string",
  "classArea": "string",
  "lang": "string",
  "paymentStatus": "none",
  "paymentStatusDate": "2022-02-22T14:45:45.286Z",
  "disputeStatus": "string",
  "disputeStatusDate": "2022-02-22T14:45:45.286Z",
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "nettingInvoiceId": 0,
  "nettingInvoiceNumber": "string",
  "selfBilling": "yes",
  "domainId": 0,
  "domainCodeName": "string",
  "domainName": "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": "2022-02-22T14:45:45.286Z",
  "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": {}
}

Error Response Unexpected Error: Default

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

Extensions

Field	Value
x-codegen-request-body-name	"docs delivery status data"

3.3 Invoice Files

The endpoint to work with invoices' files.

The method returns a list of all registered files related to the invoice for a given Invoice ID.

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

Parameters

Name	Type	Description
invoiceid (required)	integer (path)	Invoice ID.

Responses

Code	Description	Links
200	List of Invoice files.	No links
default	Unexpected error.	No links

Success Response 200: List of Invoice files

{
  "data": [
    {
      "id": 0,
      "invoiceId": 0,
      "dataSourceFileTypeId": 0,
      "filename": "string",
      "fileSystemFileFilename": "string",
      "size": 0,
      "status": "available",
      "fileSystemFileStatus": "stored",
      "statusInfo": "string",
      "statusDt": "2024-01-30T11:46:48.506Z",
      "fileSystemFileStatusDt": "2024-01-30T11:46:48.506Z",
      "insertDt": "2024-01-30T11:46:48.506Z",
      "dataSourceFileTypeCodeName": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

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

4. Data Models

Data Models define the structure of a JSON document and describe the data related to the Finance Documents.

4.1 DocumentCollection

DocumentCollection object properties:

Name	Type	Description
data (required)	array	Array of Document objects.
meta (required)	object	Meta object.

4.2 Document

Document object properties:

Name	Type	Description
documentUuid	string	DocumentUuid is the unique UUID per document that each document will have.
id	integer	The ID is the unique key for the document in the table in which that document type is stored.
instanceId	integer	The application instance represents the "logical installation" of a particular application. The instance has an owner and belongs to one and only one context of the same owner. The context defines a "group" of application instances of the same owner which represent an application platform. InstanceId determines which platform and application the document belongs to.
bizPartnerId	integer	Business Partner ID.
bizPartnerCountry	integer	Business Partner Country.
bizPartnerExternalRefId	string	BizPartnerExternalRefId is an optional foreign key to external DB (independent reseller's system).
bizPartner	object	Business Partner Object.
documentDate	string($date)	Document date.
deliveryDate	string($date)	Delivery date.
documentNumber	string	Invoice number in the invoice.
documentNumberMask	string	Invoice number fix - from what number numeration will start.
documentNumberNum	integer	Ordinal number of the invoice.
dueDate	string($date)	Document due date.
periodStart	string($date)	Start period date.
periodEnd	string($date)	End period date.
currency	integer	Currency number.
currencyCode	string	Name of the currency, e.g. "EUR".
amountNoVat	number($float)	Document amount without VAT (net amount). It can be negative when selfBilling is 'yes'.
amountVat	number($float)	Document amount including VAT. It can be negative when selfBilling is 'yes'.
vatPercent	number($float)	Percentage of the value added tax.
vat	number($float)	Value of the value added tax.
rounding	number($float)	Difference between document total and amount including VAT value.
total	number($float)	Document gross amount. It can be negative when selfBilling is 'yes'.
totalUnpaid	number($float)	Document unpaid amount.
totalPaid	number($float)	Document paid amount.
domesticCurrency	integer	Domestic currency.
domesticCurrencyCode	string	Domestic currency code, e.g. "CHD".
domesticCurrencyRate	number($float)	Domestic currency rate used to calculate domestic currency amounts.
domesticAmountNoVat	number($float)	Document amount in domestic currency without VAT.
domesticAmountVat	number($float)	Document amount in domestic currency with VAT.
domesticRounding	number($float)	Document rounding, difference between domestic currency total and domestic currency amount with VAT.
domesticTotal	number($float)	Document total amount in domestic currency.
status	string	Possible values: draft, approved, rejected, canceled, archived, imported.
insertDt	string($date‑time)	Date-time of the insert.
statusDt	string($date-time)	Status date-time.
paymentStatus	string	Possible values: none, open, on-hold, closed.
paymentStatusDate	string($date-time)	Payment status date.
domainId	integer	The ID of domain which represents business area, which further contains business processes that are related with data-sources. The "business area" is very wide definition, here in our case, we can map it to product or product_type (SMS and MNP).
domainCodeName	string	DomainCodeName is code name of domain with given domainId. It can be BULK (for bulk SMS) and BULK-MNP (for bulk MNP).
documentClassCodeName	string	Unique code name for easier recognition.
documentClassDomain	string	The group/section of documents (for now we only know for "invoice" domain).
documentClassArea	string	The business area/section, i.e. sales or purchase.
selfBilling	string	Possible values: yes, no. SelfBilling indicates if certain document type represents self billing invoice. In case of customer invoice, self billing means that invoice owner has to pay to customer, not vice versa (this is so called credit note). Self billing document is paired with exactly one document type for "regular" document, on that way system exactly knows when during creating invoice gets negative total how to switch document type.
dataSourceId	integer	Datasource ID.
datasourceCodeName	string	Code name from which this document originates.
dataSourceSelector	string	Data source selector.
dataSource	object	DataSourceDocument Object.
lang	string	Language.
documentType	string	Every document has to have document type. Document types are defined on instance level because they hold settings on platform level. One documentType has only one documentTypeName. Examples for documentTypeNames: 'Bulk Invoices' 'Bulk Invoice - Prepaid Topup' 'Bulk Invoice - Postpaid' 'Prepaid Supplier Invoice' 'Netting Invoice' 'Self Billing of Netting Invoice' 'Bulk Postpaid Control Invoice' 'Invoice Debit Note' ...
documentTypeName	string	The document type name.
syncStatus	string	SyncStatus is the document synchronization status. The synchronization is done between our system and some independent financial software. Possible values are: None - syncing is never done nor in schedule, Waiting - waiting to start syncing, Syncing - syncing in progress, Done - successfully done, Exported - document is exported, file to be imported into the external system is successfully created, Error - some error happened during syncing, Invalid - syncing was "done" but after that source document is changed, so target document is out of sync (example: source document is canceled), Misc - temporary status for internal use.
syncStatusDt	string($date-time)	Sync status date and time.
disputeStatus	string	DisputeStatus indicates whether the invoice is in dispute process or not. Possible values are: None - the invoice is not in dispute process, Open - the invoice is in dispute process and it is still not resolved, Closed - the invoice was in dispute process but it is resolved so invoice is again valid.
docsDeliveryStatus	string	Possible statuses are: none, waiting, sending, sent, error, misc.
docsDeliveryStatusDate	string($date-time)	Document delivery status date.
note	string	Note field defined in Invoice Condition Settings.
ownerId	integer	Co-owner ID.
ownerBpName	string	Co-owner name.
ownerBpBriefName	string	Co-owner brief name.
documentSync	object	Document synchronization data object.
items	array	A list of DocumentItem objects.
trafficReports	array	Array of TrafficReport objects. Traffic Reports are returned if embed=trafficReports is provided in the request.

4.3 BizPartner

BizPartner object properties:

Contains all the data related to the Business Partner.

Name	Type	Description
name	string	Business Partner name.
briefName	string	Business Partner short name.
partnerType	string	Business Partner type.
attn	string	attn is property "Attention to Person" from biz partner address.
address	string	Partner address.
post	string	Postal Code.
city	string	Name of the city.
vatNumber	string	Value added tax.
customAttributes	array	A list of CustomAttribute object.

4.4 CustomAttribute

CustomAttribute object properties:

Custom attributes are attributes that the user can define at the business partner level. They are used to enrich basic data in many sections (areas) of the business partners model.

Example: We can define a custom attribute Contract No. and then save some values for that field for some biz partners. For the partner that has value for this field, we will get in the CustomAttributes list object as follows:

JSON Example

{
    "codeName": "CONTRACT_NO",
    "value": "123456"
}

Name	Type	Description
codeName	string	Custom attribute code name.
value	object	Value can be a string or a json object.

4.5 DataSourceDocument

DataSourceDocument object properties:

If document dataSourceCodeName is POSTPAID and dataSourceSelector is empty or dataSourceCodeName is POSTPAID-CONTROL, DataSourceDocument will contain id which is the ID of related billing record and object billingTotalBalance.

If document dataSourceCodeName is POSTPAID and dataSourceSelector is PART-PAYMENT or dataSourceCodeName is PREPAID, DataSourceDocument will contain id which is the ID of related credit record and object billingTotalBalance.

In all other cases, DataSourceDocument will be null.

Name	Type	Description
id	integer	The ID is the billing record ID, associated with the document. Currently, only available for postpaid invoices.
billingTotalBalance	object	BillingTotalBalance object.

4.6 BillingTotalBalance

BillingTotalBalance object properties:

BillingTotalBalance is Invoice Condition to which the document is associated to.

Name	Type	Description
id	integer	The ID is the unique key for the Invoice Condition.
instanceId	integer	The application instance represents the "logical installation" of a particular application.
bizPartnerId	integer	Business Partner ID.
currency	integer	Currency number.
currencyCode	string	Currency code. e.g. "EUR"
billingTypeCodeName	string	Billing type code name.
name	string	Name.
customAttributes	array	A list of CustomAttribute Objects.

4.7 documentSync

documentSync object properties:

documentSync is an arbitrary JSON object, holding the document synchronization data. It is returned if status is done, error, misc, exported or invalid.

documentSync Example:

{
  "documentSync": {
      "propertyA": "value A",
      "propertyB": "value B"
      }
}

4.8 DocumentItem

DocumentItem object properties:

Document Item object contains fields related to the invoice.

Name	Type	Description
id	integer	The ID of the item.
documentId	integer	DocumentId is the ID of the document to which the item belongs, the ID property of the Document object. This property is the same for all items belonging to the same document.
ordNum	integer	Ordinary number.
name	integer	Name of the item.
quantity	number($float)	Quantity.
measureUnit	string	Measure unit.
price	number($float)	Price.
totalNoVat	number($float)	Total value without VAT.
totalVat	number($float)	Total value with VAT.
dataSourceId	integer	DataSourceId is the ID of data source from which this item comes from. The most probably this will match with document dataSourceId, but we have it on item level to store explicitly pointer to data source which is originator of the item (that way we can support in future (if needed) items for different data sources).
dataSourceCodeName	string	Code name from which this document originates.
dataSourceForeignKey	integer	Foreign key.
dataSourceSelector	string	Data source selector.
dataSource	object	DataSource is the source from which this document item originates. It contains billing account object (billing account is pricing condition) related to that document item. DataSourceDocumentItem object.

4.9 DataSourceDocumentItem

DataSourceDocumentItem object properties:

If item or document dataSourceCodeName is POSTPAID and dataSourceSelector is empty or dataSourceCodeName is POSTPAID-CONTROL, DataSourceDocumentItem will contain id which is the ID of related charge record and object billingAccount.

If item or document dataSourceCodeName is POSTPAID and dataSourceSelector is PART-PAYMENT, DataSourceDocumentItem will contain id which is the ID of related credit record and documentId which is the ID of related invoice.

In all other cases, DataSourceDocumentItem will be null.

Name	Type	Description
id	integer	The ID of the Data Source.
documentId	integer	The ID of the document.
billingAccount	object	BillingAccount object.

4.10 BillingAccount

BillingAccount object properties:

Billing Account is Pricing Condition and it contains all the fields related to the specified pricing condition.

If document domainCodeName is BULK, BillingAccount will contain smsConnections array with all SMS connections related to given billing account.

If document domainCodeName is BULK-MNP, BillingAccount will contain mnpConnections array with all MNP connections related to given billing account.

Name	Type	Description
id	integer	The ID of the billingAccount.
instanceId	integer	The application instance represents the "logical installation" of a particular application. The instance has an owner and belongs to one and only one context of the same owner. The context defines a "group" of application instances of the same owner which represent an application platform. InstanceId determines which platform and application the document belongs to.
bizPartnerId	integer	Business Partner ID.
currency	integer	Currency number.
currencyCode	string	Currency code, e.g. "EUR".
billingTypeCodeName	string	Billing type code name.
name	string	Name.
customAttributes	array	A list of CustomAttribute Objects.
smsConnections	array	A list of SMS Connection objects related to the specific billing account, smsConnection object.
mnpConnections	array	A list of MNP Connection objects related to the specific billing account, mnpConnection object.

4.11 SmsConnection

SmsConnection object properties:

SMS Connection object has fields related to the specified smsConnection in the Billing Account.

If document dataSourceCodeName is POSTPAID, SmsConnection will be customer SMS connection and will have the following properties: id, instanceId, name, authName and protocol.

If document dataSourceCodeName is POSTPAID-CONTROL, SmsConnection will be supplier SMS connection and will have the following properties: id, name. There is no input protocol for SMS supplier connection or authName (name used for authentication on input protocol level).

Name	Type	Description
id	integer	SMS connection ID.
instanceId	integer	Billing account ID.
name	string	SMS connection name.
authName	string	Authentication name.
protocol	string	The name of the protocol.

4.12 MnpConnection

MnpConnection object properties:

MnpConnection object has fields related to the specified MNP Connection in the Billing Account.

If document dataSourceCodeName is POSTPAID, MnpConnection will be customer MNP connection and will have the following properties: id, instanceId, name, authName and protocol.

If document dataSourceCodeName is POSTPAID-CONTROL, MnpConnection will be supplier MNP connection and will have the following properties: id, instanceId, name. There is no input protocol for MNP supplier connection or authName (name used for authentication on input protocol level).

Name	Type	Description
id	integer	MNP connection ID.
instanceId	integer	Billing account ID.
name	string	MNP connection name.
authName	string	Authentication name.
protocol	string	The name of the protocol.

4.13 SyncStatusChangeData

SyncStatusChangeData object properties:

Name	Type	Description
status	string	New sync status. Possible values: none, waiting, syncing, done, error, misc, invalid, exported.
reportData	object	An arbitrary JSON object, holding sync report data.
documentSync	object	An arbitrary JSON object, holding the document synchronization data. Example: "documentSync": { "propertyA": "value A", "propertyB": "value B" }.

4.14 DocsDeliveryStatusChangeData

DocsDeliveryStatusChangeData object properties:

Name	Type	Description
status	string	Status of delivering invoice documents for customer (via certain communication channel as e-mail or mail). The status value can be: none - document is not ready for delivery, i.e. it is not approved nor canceled, waiting - document is ready for sending, sending - the sending is in progress, sent - document is sent, error - sending failed, misc - this is temporary status, document should not be considered for sending until this status is changed (probably by manual intervention in db).

4.15 BillingBalance

BillingBalance object properties:

BillingBalance is Invoice Condition to which an invoice is associated to.

Name	Type	Description
id	integer	The 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.16 Invoice

Invoice object properties:

Name	Type	Description
id	integer	Invoice ID.
invUid	string	Invoice UUID.
instanceID	integer	An 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 post code.
custCity	string	Customer city.
custCountry	integer	Customer country.
custPOBox	string	Customer postal 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)	The date of invoicing.
invoicingDatePolicy	string	The policy of invoicing date.
invNumberFix	string	The fixed part of invoice number, based on this field system will define next invoice number.
invNumberNum	integer	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	Invoice overdue date.
ownerVatNumber	string	The owner VAT number.
currency	integer	Currency number.
currencyCode	string	Name of the currency, e.g. "EUR".
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)	Percentage of the value added tax.
vat	number($float)	Value of the value added tax.
rounding	number($float)	Difference between an invoice total and amount including VAT value.
total	number($float)	Invoice gross amount.
totalUnpaid	number($float)	Invoice's unpaid amount.
totalPaid	number($float)	Invoice's paid amount.
vatInPrice	integer	VAT in price.
vatInTotal	integer	VAT in total.
status	string	Invoice status.
insertDt	string($date-time)	Date-time of the insert.
statusDt	string($date-time)	Status date-time.
deliveryDate	string($date)	Delivery date.
invPeriodStart	string($date)	The start of an invoice period.
invPeriodEnd	string($date)	The end of an invoice period.
docsDeliveryStatus	string	Status of delivery.
docsDeliveryStatusDate	string($date-time)	Invoice delivery status date.
docsDeliveryDlrStatus	string	Status of DLR.
docsDeliveryDlrStatusDate	string($date-time)	The date of DLR.
classCodeName	string	Unique code name.
classDomain	string	The group of documents.
classArea	string	The business area/section, i.e. sales or purchase.
lang	string	Language.
paymentStatus	string	The status of payment.
paymentStatusDate	string($date-time)	The payment status date.
disputeStatus	string	DisputeStatus indicates whether the invoice is in dispute process or not.
disputeStatusDate	string($date-time)	Dispute status date.
dataSourceId	integer	The ID of a data source.
dataSourceCodeName	string	The data source code name.
nettingInvoiceId	integer	The ID of an invoice netting.
nettingInvoiceNumber	string	Netting invoice number.
selfBilling	string	Indicator if an invoice is a credit note or not. If value is 'yes', when the document is in netting statement, indicates that the document is in favor of buyer, but issued by seller. Also, if the document is CREDIT_DEBIT_NOTE class, it indicates that the document is a credit note, which is also in favor of buyer, but issued by 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	The ID of dispute.
collectionMode	string	Document collection mode. If member, the document is a 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 the document is a member of a collection, this value contains the ID of a collection lead document.
collectionLeadNumber	string	If the document is a member of a collection, this value contains the number of a collection lead document.
collectionLeadNettingInvoiceId	integer	Netting statement ID of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceNumber	string	Netting statement number of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceStatus	string	Netting statement status of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoicePaymentStatus	string	Netting statement payment status of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotal	string	Netting statement total amount of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalPaid	string	Netting statement total paid amount of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalUnpaid	string	Netting statement total unpaid amount of a collection lead. It is returned when the collection lead, to whom the current invoice belongs to, is a netting statement's member.
processingStatus	string	Indicates processing status of a document, if the 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 an invoice is a credit or debit note. Comment is not available when an invoice list is returned as a result of a request, regardless of an invoice class code name.
nettingInvoiceStatus	string	If an invoice is a netting statement's member, this property contains netting statement status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived.
nettingPaymentStatus	string	If an invoice is a netting statement's member, this property is a netting's payment status. Possible values: none, open, closed.
nettingTotal	number($float)	If an invoice is a netting statement's member, this property is a netting's gross amount. It can be negative when selfBilling is 'yes'.
nettingTotalUnpaid	number($float)	If an invoice is a netting statement's member, this property is a netting's unpaid amount.
nettingTotalPaid	number($float)	If an invoice is a netting statement's member, this property is a 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	The ID of an invoice email import.
billingBalance	object	BillingBalance object
billingTypeName	string	Required and returned for control invoices.
smsCount	integer	An amount of messages. Required and returned for postpaid and control invoices.
syncStatus	string	SyncStatus is an invoice synchronization status. The synchronization is done between our system and some independent financial software. Possible values: none, waiting, syncing, done, error, misc, exported, invalid.
syncStatusDt	string($date‑time)	Sync 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, e.g. "CHD".
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	Co-owner ID.
ownerBpName	string	Co-owner name.
ownerBpBriefName	string	Co-owner brief name.
externalRefId	string	External reference ID.
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.17 InvoiceFile

InvoiceFile object properties:

Name	Type	Description
id	integer	Invoice file ID.
invoiceId	integer	Invoice ID.
dataSourceFileTypeId	integer	Data source file type ID.
filename	string	File name.
fileSystemFileFilename	string	File system file name.
size	integer	Size.
status	string	Status of a file. Possible values: available, archived, deleted, misc.
fileSystemFileStatus	string	File system file status. Possible values: stored, cached, volatile.
statusInfo	string	Status info.
statusDt	string($date-time)	Date and time of a status.
fileSystemFileStatusDt	string($date-time)	Date and time of system file status.
insertDt	string($date-time)	Date and time of insertion.
dataSourceFileTypeCodeName	string	Data source file type code name.

Part-Payment Example:

{
  "data": [
    {
      "documentUuid": "f44d0a30-b28f-4641-854c-4bc50c7d7e56",
      "id": 22960,
      "instanceId": 41,
      "bizPartnerId": 87612478,
      "bizPartnerCountry": 384,
      "bizPartnerExternalRefId": "XZ876765-S33",
      "bizPartner": {
        "name": "Business Partner Example 1",
        "briefName": "BP 1",
        "partnerType": "wholesale",
        "attn": "",
        "address": "",
        "post": "",
        "city": "",
        "vatNumber": "",
        "customAttributes": [
            {
              "codeName": "OBJECT_EXAMPLE",
              "value": {
                    "propertyA": "value A",
                    "propertyB": "value B"
              }
            }
         ]
      },
      "documentDate": "2019-09-30",
      "deliveryDate": "2019-09-30",
      "documentNumber": "300919-1",
      "documentNumberMask": "300919-%d",
      "documentNumberNum": 1,
      "dueDate": "2019-10-30",
      "periodStart": "2019-09-01",
      "periodEnd": "2019-09-30",
      "currency": 978,
      "currencyCode": "EUR",
      "amountNoVat": 0.55,
      "amountVat": 0.55,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0.55,
      "totalUnpaid": 0.55,
      "totalPaid": 0,
      "domesticCurrency": 752,
      "domesticCurrencyCode": "SEK",
      "domesticCurrencyRate": 10.7287,
      "domesticAmountNoVat": 5.9,
      "domesticAmountVat": 5.9,
      "domesticRounding": 0,
      "domesticTotal": 5.9,
      "status": "approved",
      "insertDt": "2019-10-01T11:08:59Z",
      "statusDt": "2019-10-01T16:33:05Z",
      "paymentStatus": "open",
      "paymentStatusDate": "2019-10-01T16:33:05Z",
      "domainId": 1,
      "domainCodeName": "BULK",
      "documentClassCodeName": "CUSTOMER_INVOICE",
      "documentClassDomain": "invoice",
      "documentClassArea": "sales",
      "selfBilling": "no",
      "dataSourceId": 2,
      "dataSourceCodeName": "POSTPAID",
      "dataSourceSelector": "PART-PAYMENT",
      "dataSource": {
        "id": 214,
        "billingTotalBalance": {
          "id": 1994,
          "instanceId": 12,
          "bizPartnerId": 87612478,
          "currency": 978,
          "currencyCode": "EUR",
          "billingTypeCodeName": "POSTPAID",
          "name": "BP1 postpaid CHF",
          "customAttributes": [
              {
              "codeName": "CONTRACT_NAME",
              "value": "DD2000018"
              }
          ]
        }
      },
      "lang": "en",
      "documentType": 26,
      "documentTypeName": "Bulk Invoice - Postpaid Part Payment",
      "syncStatus": "none",
      "syncStatusDt": null,
      "disputeStatus": "none",
      "docsDeliveryStatus": "none",
      "docsDeliveryStatusDate": null,
      "note": "string",
      "documentSync": {},
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "items": [
        {
          "id": 99091,
          "documentId": 22960,
          "ordNum": 1,
          "name": "Postpaid Bulk SMS Part Payment\nPostpaid EUR",
          "quantity": 0,
          "measureUnit": "PIECE",
          "price": 0,
          "totalNoVat": 0.552,
          "totalVat": 0.552,
          "dataSourceId": 2,
          "dataSourceCodeName": "POSTPAID",
          "dataSourceForeignKey": 214,
          "dataSourceSelector": "PART-PAYMENT",
          "dataSource": {
            "id": 214,
            "documentId": 22970
          }
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "totalPages": 1,
      "currentPage": 1,
      "perPage": 10,
      "count": 1
    }
  }
}  

Postpaid-SMS Example:

{
  "data": [
    {
      "documentUuid": "f44d0a30-b28f-4641-854c-4bc50c7d7e56",
      "id": 22960,
      "instanceId": 47,
      "bizPartnerId": 87612478,
      "bizPartnerCountry": 384,
      "bizPartnerExternalRefId": "XZ876765-S33",
      "bizPartner": {
        "name": "Business Partner Example 1",
        "briefName": "BP 1",
        "partnerType": "Wholesale",
        "attn": "",
        "address": "",
        "post": "",
        "city": "",
        "vatNumber": "",
        "customAttributes": [
          {
            "codeName": "OBJECT_EXAMPLE",
            "value": {
              "propertyA": "value A",
              "propertyB": "value B"
            }
          }
        ]
      },
      "documentDate": "2019-09-30",
      "deliveryDate": "2019-09-30",
      "documentNumber": "300919-1",
      "documentNumberMask": "300919-%d",
      "documentNumberNum": 1,
      "dueDate": "2019-10-30",
      "periodStart": "2019-09-01",
      "periodEnd": "2019-09-30",
      "currency": 978,
      "currencyCode": "EUR",
      "amountNoVat": 0.55,
      "amountVat": 0.55,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0.55,
      "totalUnpaid": 0.55,
      "totalPaid": 0,
      "domesticCurrency": 752,
      "domesticCurrencyCode": "SEK",
      "domesticCurrencyRate": 10.7287,
      "domesticAmountNoVat": 5.9,
      "domesticAmountVat": 5.9,
      "domesticRounding": 0,
      "domesticTotal": 5.9,
      "status": "approved",
      "insertDt": "2019-10-01T11:08:59Z",
      "statusDt": "2019-10-01T16:33:05Z",
      "paymentStatus": "open",
      "paymentStatusDate": "2019-10-01T16:33:05Z",
      "domainId": 1,
      "domainCodeName": "BULK",
      "documentClassCodeName": "CUSTOMER_INVOICE",
      "documentClassDomain": "invoice",
      "documentClassArea": "sales",
      "selfBilling": "no",
      "dataSourceId": 2,
      "dataSourceCodeName": "POSTPAID",
      "dataSourceSelector": "",
      "dataSource": {
        "id": 6363,
        "billingTotalBalance": {
          "id": 1994,
          "instanceId": 12,
          "bizPartnerId": 87612478,
          "currency": 978,
          "currencyCode": "EUR",
          "billingTypeCodeName": "POSTPAID",
          "name": "BP1 postpaid CHF",
          "customAttributes": [
            {
              "codeName": "CONTRACT_NAME",
              "value": "DD2000018"
            }
          ]
        }
      },
      "lang": "en",
      "documentType": 5,
      "documentTypeName": "Bulk Invoice",
      "syncStatus": "none",
      "syncStatusDt": null,
      "disputeStatus": "none",
      "docsDeliveryStatus": "none",
      "docsDeliveryStatusDate": null,
      "note": "string",
      "documentSync": {},
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "items": [
        {
          "id": 99090,
          "documentId": 22960,
          "ordNum": 1,
          "name": "Account: DIR",
          "quantity": 12,
          "measureUnit": "PIECE",
          "price": 0,
          "totalNoVat": 0.552,
          "totalVat": 0.552,
          "dataSourceId": 2,
          "dataSourceCodeName": "POSTPAID",
          "dataSourceForeignKey": 45684,
          "dataSourceSelector": "",
          "dataSource": {
            "id": 45684,
            "billingAccount": {
              "id": 3369,
              "instanceId": 12,
              "bizPartnerId": 87612478,
              "currency": 978,
              "currencyCode": "EUR",
              "billingTypeCodeName": "POSTPAID",
              "name": "DIR",
              "customAttributes": [
                {
                  "codeName": "STRING_EXAMPLE",
                  "value": "value C"
                }
              ],
              "smsConnections": [
                {
                  "id": 12023,
                  "instanceId": 12,
                  "name": "DIR",
                  "authName": "7987823_DIR",
                  "protocol": "SMPP"
                }
              ]
            }
          }
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "totalPages": 1,
      "currentPage": 1,
      "perPage": 10,
      "count": 1
    }
  }
}

Prepaid Example:

{
  "data": [
    {
      "documentUuid": "f44d0a30-b28f-4641-854c-4bc50c7d7e56",
      "id": 22960,
      "instanceId": 41,
      "bizPartnerId": 87612478,
      "bizPartnerCountry": 384,
      "bizPartnerExternalRefId": "XZ876765-S33",
      "bizPartner": {
        "name": "Business Partner Example 1",
        "briefName": "BP 1",
        "partnerType": "wholesale",
        "attn": "",
        "address": "",
        "post": "",
        "city": "",
        "vatNumber": "",
        "customAttributes": [
          {
            "codeName": "OBJECT_EXAMPLE",
            "value": {
              "propertyA": "value A",
              "propertyB": "value B"
              }
          }
        ]
      },
      "documentDate": "2019-09-30",
      "deliveryDate": "2019-09-30",
      "documentNumber": "300919-1",
      "documentNumberMask": "300919-%d",
      "documentNumberNum": 1,
      "dueDate": "2019-10-30",
      "periodStart": "2019-09-01",
      "periodEnd": "2019-09-30",
      "currency": 978,
      "currencyCode": "EUR",
      "amountNoVat": 0.55,
      "amountVat": 0.55,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0.55,
      "totalUnpaid": 0.55,
      "totalPaid": 0,
      "domesticCurrency": 752,
      "domesticCurrencyCode": "SEK",
      "domesticCurrencyRate": 10.7287,
      "domesticAmountNoVat": 5.9,
      "domesticAmountVat": 5.9,
      "domesticRounding": 0,
      "domesticTotal": 5.9,
      "status": "approved",
      "insertDt": "2019-10-01T11:08:59Z",
      "statusDt": "2019-10-01T16:33:05Z",
      "paymentStatus": "open",
      "paymentStatusDate": "2019-10-01T16:33:05Z",
      "domainId": 1,
      "domainCodeName": "BULK",
      "documentClassCodeName": "CUSTOMER_INVOICE",
      "documentClassDomain": "invoice",
      "documentClassArea": "sales",
      "selfBilling": "no",
      "dataSourceId": 1,
      "dataSourceCodeName": "PREPAID",
      "dataSourceSelector": "",
      "dataSource": {
        "id": 217,
        "billingTotalBalance": {
          "id": 1995,
          "instanceId": 12,
          "bizPartnerId": 87612478,
          "currency": 978,
          "currencyCode": "EUR",
          "billingTypeCodeName": "PREPAID",
          "name": "BP1 prepaid EUR",
          "customAttributes": [
            {
              "codeName": "CONTRACT_NAME",
              "value": "DD2000018"
            }
          ]
        }
      },
      "lang": "en",
      "documentType": 19,
      "documentTypeName": "Bulk Invoice - Prepaid",
      "syncStatus": "none",
      "syncStatusDt": null,
      "disputeStatus": "none",
      "docsDeliveryStatus": "none",
      "docsDeliveryStatusDate": null,
      "note": "string",
      "documentSync": {},
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "items": [
        {
          "id": 99095,
          "documentId": 22960,
          "ordNum": 1,
          "name": "Clearing Test InvoiceItem",
          "quantity": 1,
          "measureUnit": "PIECE",
          "price": 1000,
          "totalNoVat": 1000,
          "totalVat": 1000,
          "dataSourceId": 0,
          "dataSourceCodeName": "",
          "dataSourceForeignKey": 0,
          "dataSourceSelector": "",
          "dataSource": null
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "totalPages": 1,
      "currentPage": 1,
      "perPage": 10,
      "count": 1
    }
  }
}

4.18 TrafficReport

TrafficReport object properties:

Name	Type	Description
bizPartnerId	integer	Business Partner ID.
bizPartnerBriefName	string	Business Partner brief name.
bizPartnerExtRefId	string	Business Partner external reference ID.
billingAccountId	integer	ID of Pricing Condition.
billingAccountName	string	Name of Pricing Condition.
countryId	integer	Country ID.
countryName	string	Country name.
countryCode2	string	Country code.
operatorId	integer	Operator ID.
operatorName	string	Operator name.
mcc	string	Mobile country code.
mnc	string	Mobile network code.
startDt	string($date-time)	Start date and time.
endDt	string($date-time)	End date and time.
priceSinceDt	string($date-time)	Price since date and time.
smsCnt	integer	Quantity per unit.
currency	integer	ID of currency.
currencyCode	string	Currency code.
price	number($float)	Price per unit.
totalAmount	number($float)	TotalAmount is price per unit multiplied by quantity per unit (totalAmount = price * smsCnt).

4.19 Error

Error object properties:

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

JSON Example

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

Error list

Response code	Response body	Message
401	NOT_AUTHENTICATED	Not authenticated.
401	NOT_AUTHORIZED	Not authorized.
404	BAD_PARAM	Bad parameter.
400	BAD_PARAM_PAGE_NUMBER	Bad parameter 'page_number': value must be greater than 0.
400	BAD_PARAM_PAGE_SIZE	Bad parameter 'page_size': value must be greater than 0.
500	INT_APP_ERROR	FINANCE instance not found.
500	INT_APP_ERROR	BUSINESS_PARTNERS instance not found.
500	INT_APP_ERROR	Internal server error.
404	INVOICE_NOTFOUND	Invoice not found.

4.20 CollectionMeta

CollectionMeta object properties:

Name	Type	Description
collectionMetaPagination	object	collectionMetaPagination object.

4.21 CollectionMetaPagination

CollectionMetaPagination object properties:

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

JSON Example

"meta": {
    "pagination": {
      "total": 0,
      "totalPages": 0,
      "currentPage": 0,
      "perPage": 0,
      "count": 0
    }
}

5. Examples

1. In order to get a collection of all invoices for a certain period of time, between operator can be used. E.g. this will return a collection of invoices from December 2021:

   between(documentDate)=2021-12-01,2021-12-31

2. The following filter can be used for customer invoices:

   documentClassCodeName=CUSTOMER_INVOICE

3. There are three types of customer invoices, prepaid, postpaid and part payments. Here are the filters for each type of the customer invoice:

   • Prepaid

     documentClassCodeName=CUSTOMER_INVOICE&dataSourceCodeName=PREPAID

   • Postpaid

     documentClassCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&isnull(dataSourceSelector)=true

   • Part Payments

     documentClassCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&dataSourceSelector=PART-PAYMENT

4. For control invoices, it is enough to use the following filter:

   documentClassCodeName=CONTROL_INVOICE

5. If you want to return control and customer postpaid invoices together, you can use the following combination of filters:

   in(documentClassCodeName)=CUSTOMER_INVOICE,CONTROL_INVOICE&in(dataSourceCodeName)=POSTPAID,POSTPAID-CONTROL&isnull(dataSourceSelector)=true

6. Only approved invoices can be returned by using the following filter:

   status=approved

7. Paid invoices can be returned by using the following filter:

   in(disputeStatus)=closed,none&paymentStatus=closed&status=approved

6. PDF Documents API

In order to get PDFs of documents, e.g. for invoices, credit notes, traffic reports and other finance documents, you should use the HORISEN Invoice Docs API.

The HORISEN Invoice Docs API endpoint URL is:

https://api{separator}{platform_domain}/invoice-docs/v2

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.

6.1 Methods Overview

6.2 Methods Details

The method returns an invoice (PDF) or traffic report (XLSX) file.

Authorization privilege needed for this endpoint:
- invoice-docs.view - Logged user can see data for all biz partners.
- invoice-docs-own.view - Logged user can see only data for his own biz partner.

Parameters

Name	Type	Description
id (required)	integer (path)	Invoice ID.
file_type (required)	string (path)	Invoice file type. It can be INVOICE or TRAFFIC-REPORT.
address_cover_page	string (query)	Available value: yes. Value 'yes' should be passed in order to get an extra cover page with an address.

Responses

Code	Description	Links
200	Invoice file.	No links
default	Unexpected error.	No links

Success Response 200: Invoice file

Error Response Unexpected Error: Default

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

The method downloads Supplier and Supplier Debit Note invoices.

Authorization privilege needed for this endpoint:
- invoice-docs.view - Logged user can see data for all biz partners.
- invoice-docs-own.view - Logged user can see only data for his own biz partner.

Parameters

Name	Type	Description
invoiceId (required)	integer (path)	Invoice ID.
fileID (required)	integer (path)	Invoice file ID.

Responses

Code	Description	Links
200	Invoice file.	No links
default	Unexpected error.	No links

Success Response 200: Invoice file

Error Response Unexpected Error: Default

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