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.

GET/documents-export
Returns a list of documents for export.Read More

2.2 Invoice

The endpoints for updating the status of financial documents.

POST/invoices/{invoiceid}/change-sync-status
Changes an invoice sync status.Read More
POST/invoices/{invoices-list}/bulk-change-sync-status
Changes sync status of group of invoices.Read More
POST/invoices/{invoiceid}/change-docs-delivery-status
Changes an invoice docs delivery status.Read More

2.3 Invoice Files

The endpoint to work with invoices' files.

GET/invoices/{invoiceid}/files
Returns a list of all registered files related to the invoice for a given Invoice ID.Read More

3. Methods Details

3.1 Document

The endpoint for financial documents.

GET/documents-export
Returns a list of documents for export.Up
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.

Parameters
Name Type Description
page_number integer (query) Page number. Default value is 1.
page_size integer (query) Page size. 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, API will return 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 beginng 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 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_EXAMPLE",
            "value": "value C"
          },
          {
            "codeName": "OBJECT_EXAMPLE",
            "value": {
              "propertyA": "value A",
              "propertyB": "value B"
            }
          }
        ]
      },
      "documentDate": "2022-02-22",
      "deliveryDate": "2022-02-22",
      "documentNumber": "string",
      "documentNumberMask": "string",
      "documentNumberNum": 0,
      "dueDate": "2022-02-22",
      "periodStart": "2022-02-22",
      "periodEnd": "2022-02-22",
      "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": "2022-02-22T14:11:24.043Z",
      "statusDt": "2022-02-22T14:11:24.043Z",
      "paymentStatus": "none",
      "paymentStatusDate": "2022-02-22T14:11:24.043Z",
      "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_EXAMPLE",
              "value": "value C"
            },
            {
              "codeName": "OBJECT_EXAMPLE",
              "value": {
                "propertyA": "value A",
                "propertyB": "value B"
              }
            }
          ]
        }
      },
      "lang": "string",
      "documentType": 0,
      "documentTypeName": "string",
      "syncStatus": "none",
      "syncStatusDt": "2022-02-22T14:11:24.043Z",
      "disputeStatus": "none",
      "docsDeliveryStatus": "none",
      "docsDeliveryStatusDate": "2022-02-22T14:11:24.043Z",
      "note": "string",
      "documentSync": {},
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "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_EXAMPLE",
                  "value": "value C"
                },
                {
                  "codeName": "OBJECT_EXAMPLE",
                  "value": {
                    "propertyA": "value A",
                    "propertyB": "value B"
                  }
                }
              ],
              "smsConnections": [
                {
                  "id": 0,
                  "instanceId": 0,
                  "name": "string",
                  "authName": "string",
                  "protocol": "string"
                }
              ],
              "mnpConnections": [
                {
                  "id": 0,
                  "instanceId": 0,
                  "name": "string",
                  "authName": "string",
                  "protocol": "string"
                }
              ]
            }
          }
        }
      ]
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}

3.2 Invoice

The endpoints for updating the status of financial documents.

POST/invoices/{invoiceid}/change-sync-status
Changes an invoice sync status.Up
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:
- 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"
POST/invoices/{invoices-list}/bulk-change-sync-status
Changes sync status of group of invoices.Up
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"
}
POST/invoices/{invoiceid}/change-docs-delivery-status
Changes an invoice docs delivery status.Up
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:
- 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.

GET/invoices/{invoiceid}/files
Returns a list of all registered files related to the invoice for a given Invoice ID.Up

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.

4.1 Data

Data describe all the data related to the Finance Documents.

Name Type Description
DocumentCollection object DocumentCollection object.

DocumentCollection object properties:

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

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 due 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 including 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.
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.

Business partner object:

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.

CustomAttribute object:

Custom attributes are attributes that the user defines 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: 

{
    "codeName": "CONTRACT_NO",
    "value": "123456"
}
Name Type Description
name STRING_EXAMPLE Business Partner name.
value string Value as a string.
codeName OBJECT_EXAMPLE Business Partner Code Name as an object.
value object Value as an object.

DataSourceDocument object:

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.

BillingTotalBalance object:

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.

CustomAttribute object:

Name Type Description
codeName STRING_EXAMPLE Code name.
value string Value as a string.
codeName OBJECT_EXAMPLE Code Name as an object.
value object Value as an object.

Document synchronization data object:

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"
      }
}

DocumentItem object:

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.

DataSourceDocumentItem object:

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.

BillingAccount object:

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.

CustomAttributes object:

Custom attributes are attributes that the user defines at the Billing Account level. They are used to enrich basic data in many sections (areas) of the billing account model.

Name Type Description
codeName STRING_EXAMPLE Code name.
value string Value as a string.
codeName OBJECT_EXAMPLE Code Name as an object.
value object Value as an object.

Example:

We can define a custom attribute codeName and then save some values for that field for some Billing Accounts.

{
  "customAttributes": [
                      {
                        "codeName": "OBJECT_EXAMPLE",
                        "value": {
                            "propertyA": "value A",
                            "propertyB": "value B"
                        }
                      }
                    ]
}

SMS connection object:

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.

MNP connection object:

MNP Connection object has fields related to the specified mnpConnection 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.

SyncStatusChangeData object:

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" }.

DocsDeliveryStatusChangeData object:

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).

BillingBalance object:

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.

Invoice object:

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.
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.
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" }.

InvoiceFile object:

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.

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.

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.2 Meta

Meta contains data for the number of rows and pages that have been received for a given API call.

Name Type Description
collectionMeta object collectionMeta object.

collectionMeta object properties:

Name Type Description
collectionMetaPagination object collectionMetaPagination object.

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

GET/invoice/{id}/file-type/{file_type}
Returns an invoice (PDF) or traffic report (XLSX) file.Read More
GET/supplier-invoices/{invoiceId}/invoice-files-dl/{fileId}
Downloads Supplier and Supplier Debit Note invoices.Read More

6.2 Methods Details

GET/invoice/{id}/file-type/{file_type}
Returns an invoice (PDF) or traffic report (XLSX) file.Up

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"
    }
  ]
}
GET/supplier-invoices/{invoiceId}/invoice-files-dl/{fileId}
Downloads Supplier and Supplier Debit Note invoices.Up

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"
    }
  ]
}