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.horisen.pro/finance/sit/v1

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

2. Method Overview

2.1 Document

The endpoint for financial documents.

2.2 Invoice

The endpoints for updating the status of financial documents.

3. Method 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 documents described at URL Filtering Guidelines page.

Parameters

Name	Type	Description
page_number	integer (query)	A page number. The default value = 1.
page_size	integer (query)	A page size. The default value = 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	A 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.

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)	An 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 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)	An invoice ID.
post 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	An 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"

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	A co-owner ID.
ownerBpName	string	A co-owner name.
ownerBpBriefName	string	A 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	A currency number.
currencyCode	string	A 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	The Invoice Condition name.
resourceUrl	string	A billing API URL that should be used to load billing balance resource.

Invoice object:

Name	Type	Description
id	integer	An invoice ID.
invUid	string	An invoice UUID.
instanceID	integer	An instance ID.
custID	integer	A customer ID.
custName	string	A customer name.
custShortName	string	A customer short name.
custAttn	string	A customer attn data.
custAddress	string	A customer address.
custAddress2	string	A customer address2.
custPost	string	A customer post code.
custCity	string	A customer city.
custCountry	integer	A customer country.
custPOBox	string	A customer postal box.
customerType	string	A customer type.
custVatNumber	string	A customer VAT number.
invType	integer	An invoice type.
invTypeName	string	An invoice type name.
templateID	integer	A template ID.
invDate	string($date)	An 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	The invoice number (variable part) - it counts invoices for the same invNumberFix.
invNumber	string	An invoice number.
invPeriod	string	An invoice period.
invDueDate	string($date)	An invoice due date.
overDueDate	integer	An 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)	An invoice amount without VAT (net amount). It can be negative when selfBilling is 'yes'.
amountVat	number($float)	An 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)	An invoice gross amount.
totalUnpaid	number($float)	An invoice's unpaid amount.
totalPaid	number($float)	An invoice's paid amount.
vatInPrice	integer	VAT in price.
vatInTotal	integer	VAT in total.
status	string	An 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)	An 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.
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)	An invoice amount in domestic currency without VAT.
domesticCurrencyAmountVAT	number($float)	An invoice amount in domestic currency with VAT.
domesticCurrencyTotal	number($float)	An invoice total amount in domestic currency.
domesticCurrencyRounding	number($float)	An 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	An industry name.
ownerName	string	An owner name.
ownerId	integer	A co-owner ID.
ownerBpName	string	A co-owner name.
ownerBpBriefName	string	A 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" }.

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 Examplez

"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.horisen.pro/invoice-docs/v1

6.1 Method Overview

6.2 Method 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)	The invoice ID.
file_type (required)	string (path)	The 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	The 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"
    }
  ]
}