Supplier Invoice API

1. Introduction

The HORISEN Supplier Invoice API is used by HORISEN applications for Simple Invoice Tool.

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

https://api.horisen.pro/finance/sit/v1

It supports OAuth 2.0 authentication. An example of how to implement OAuth 2.0 and obtain access token as well as an example of using HORISEN API service, is available on OAuth2 Authentication Guidelines page.

2. Methods Overview

The endpoints to work with Suppliers' Invoices.

3. Method Details

The endpoints to work with Suppliers' Invoices.

Method Overview

The method creates a new Supplier 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.

Manual Generation of a Supplier Invoice

For manual generation of an invoice, personal data should be in the request body. These values have priority over the values from a database found for that 'custID'. If the values are omitted from the body, the data from a database will be used.

To discover invtype, templateId and lang properties, you have to use method GET /default-invoice-config and put response values typeId, templateId and templateLang in properties invType, templateId and lang respectively.
See description of GET /default-invoice-config for instruction on how to get values for different kind of invoices.

Notice that GET /default-invoice-config has query parameter templateLang. By default the value of that parameter is 'en'. In some cases such as manual generation of an invoice, templateLang parameter value should be initially set to a Business Partner's default language, in order to instruct API to try to find template in the Business Partner default language, if available.

Input parameters	Description
invDate	It must be in 2006-01-02 format. If it is omitted, Time.Now() is used. It is mandatory for Supplier invoices.
DeliveryDate	It must be in 2006-01-02 format. If it is omitted, Time.Now() is used.
invNumberFix	Fixed part of an invoice number. If it is omitted, there will be an error. For Supplier invoices it will be populated with supplierInvNumber.
invDueDate	It must be in 2006-01-02 format. It has priority over invDueDateDays. Mandatory for Supplier invoices.
invDueDateDays	It is a number of days to add on invDate. If no invDueDate is used, this parameter is used. If both inDueDate and invDueDateDays are missing, there will be an error.
inDueDate	An Invoice due date. It must be after DeliveryDate. If both inDueDate and invDueDateDays are missing, there will be an error.
invPeriod	It is a string like "01.01.2016 - 31.12.2016".
vatInPrice	It must be 0 or 1. 0 - shows (uses) NET item price. 1 - shows (uses) GROSS. It can be omitted.
vatInTotal	It must be 0 or 1. 0 - shows (uses) NET item total. 1 - shows (uses) GROSS. It can be omitted.
status	It is set to draft by default. Any change to this field is done by delete or change status endpoints, status for Supplier invoices are set to approved by default.
amountNoVat	Net amount. Mandatory for Supplier invoices.
amountVat	Gross amount. Mandatory for Supplier invoices.
total	Total gross amount. Mandatory for Supplier invoices.
currency	Mandatory for Supplier invoices.
supplierInvNumber	Mandatory for Supplier invoices.

Example of minimal JSON body parameters for the Supplier invoices:

{
  "custID": 1061,
  "currency": 978,
  "invType": 21,
  "invDueDate": "2017-03-02",
  "invDate": "2017-02-02",
  "supplierInvNumber": "invoice-123",
  "amountNoVat": 100,
  "amountVat": 120,
  "total": 120
}

Example of minimal JSON body parameters for the Netting invoices:

{
  "custID": 1061,
  "invNumberFix": "string",
  "currency": 978,
  "invDueDateDays": 5,
  "invType" : 1,
  "templateId" : 2
}

URL Parameters

Name	Type	Description
post data (required)	object (body)	If invDate is used, it must be in 2006-01-02 format. If invDueDate is used, it must be in 2006-01-02 format.

Data Parameters

Post data object example

{
  "custID": 0,
  "instanceID": 0,
  "custName": "string",
  "custAttn": "string",
  "custAddress": "string",
  "custAddress2": "string",
  "custPost": "string",
  "custCity": "string",
  "custCountry": 0,
  "custPOBox": "string",
  "custVatNumber": "string",
  "invType": 0,
  "templateID": 0,
  "invDate": "2023-05-19",
  "invoicingDate": "2023-05-19",
  "invNumberFix": "string",
  "supplierInvNumber": "string",
  "invPeriod": "string",
  "invPeriodStart": "2023-05-19",
  "invPeriodEnd": "2023-05-19",
  "invDueDate": "2023-05-19",
  "invDueDateDays": 0,
  "deliveryDate": "2023-05-19",
  "ownerVatNumber": "string",
  "currency": 0,
  "vatInPrice": 0,
  "vatInTotal": 0,
  "lang": "string",
  "docsDeliveryStatus": "none",
  "comment": "string",
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "domainId": 0,
  "domainCodeName": "string",
  "dtsSelectorId": 0,
  "dtsSelectorCodeName": "string",
  "finDocClassId": 0,
  "finDocClassCodeName": "string",
  "sitInvoiceEmailImportId": 0,
  "reminderStatus": "enabled",
  "items": [
    {
      "name": "string",
      "itemType": "string",
      "quantity": 0,
      "quantityMore": 0,
      "quantityMode": 0,
      "measureUnit": 0,
      "price": 0,
      "status": "string",
      "dataSourceId": 0,
      "dataSourceForeignKey": 0,
      "dtsSelectorId": 0
    }
  ],
  "payment": {
    "fullyPaid": true,
    "paymentType": 0,
    "paymentDate": "2023-05-19",
    "comment": "string",
    "bankAccountId": 0,
    "paymentReference": "string"
  },
  "invoiceSourceRecord": {
    "billingRecordId": 0,
    "creditRecordId": 0
  }
}  

Responses

Code	Description	Links
200	Invoice is added.	No links
default	Unexpected Error.	No links

Success Response 200: Invoice is added

{
  "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": "2023-05-19",
  "invoicingDate": "2023-05-19",
  "invoicingDatePolicy": "delivery",
  "invNumberFix": "string",
  "invNumberNum": 0,
  "invNumber": "string",
  "invPeriod": "string",
  "invDueDate": "2023-05-19",
  "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": "2023-05-19T12:18:41.974Z",
  "statusDt": "2023-05-19T12:18:41.974Z",
  "deliveryDate": "2023-05-19",
  "invPeriodStart": "2023-05-19",
  "invPeriodEnd": "2023-05-19",
  "docsDeliveryStatus": "string",
  "docsDeliveryStatusDate": "2023-05-19T12:18:41.974Z",
  "docsDeliveryDlrStatus": "string",
  "docsDeliveryDlrStatusDate": "2023-05-19T12:18:41.974Z",
  "classCodeName": "string",
  "classDomain": "string",
  "classArea": "string",
  "lang": "string",
  "paymentStatus": "none",
  "paymentStatusDate": "2023-05-19T12:18:41.974Z",
  "disputeStatus": "string",
  "disputeStatusDate": "2023-05-19T12:18:41.974Z",
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "nettingInvoiceId": 0,
  "nettingInvoiceNumber": "string",
  "selfBilling": "yes",
  "domainId": 0,
  "domainCodeName": "string",
  "domainName": "string",
  "domainProduct": 0,
  "accountManagerId": 0,
  "accountManagerName": "string",
  "disputeNextId": 0,
  "collectionMode": "none",
  "collectionLeadId": 0,
  "collectionLeadNumber": "string",
  "collectionLeadNettingInvoiceId": 0,
  "collectionLeadNettingInvoiceNumber": "string",
  "collectionLeadNettingInvoiceStatus": "string",
  "collectionLeadNettingInvoicePaymentStatus": "string",
  "collectionLeadNettingInvoiceTotal": "string",
  "collectionLeadNettingInvoiceTotalPaid": "string",
  "collectionLeadNettingInvoiceTotalUnpaid": "string",
  "processingStatus": "none",
  "comment": "string",
  "nettingInvoiceStatus": "draft",
  "nettingPaymentStatus": "none",
  "nettingTotal": 0,
  "nettingTotalUnpaid": 0,
  "nettingTotalPaid": 0,
  "dtsSelectorId": 0,
  "dtsSelectorCodeName": "string",
  "sitInvoiceEmailImportId": 0,
  "billingBalance": {
    "id": 0,
    "name": "string",
    "resourceUrl": "string"
  },
  "billingTypeName": "string",
  "smsCount": 0,
  "syncStatus": "none",
  "syncStatusDt": "2023-05-19T12:18:41.974Z",
  "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"
}

Method Overview

The method returns data for an Invoice identified by invoiceid.

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

URL Parameters

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

Responses

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

Success Response 200: Invoice data.

{
  "id": 0,
  "invUid": "string",
  "instanceID": 0,
  "custID": 0,
  "custName": "string",
  "custShortName": "string",
  "custAttn": "string",
  "custAddress": "string",
  "custAddress2": "string",
  "custPost": "string",
  "custCity": "string",
  "custCountry": 0,
  "custPOBox": "string",
  "customerType": "string",
  "custVatNumber": "string",
  "invType": 0,
  "invTypeName": "string",
  "templateID": 0,
  "invDate": "2023-05-22",
  "invoicingDate": "2023-05-22",
  "invoicingDatePolicy": "delivery",
  "invNumberFix": "string",
  "invNumberNum": 0,
  "invNumber": "string",
  "invPeriod": "string",
  "invDueDate": "2023-05-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": "2023-05-22T10:00:25.567Z",
  "statusDt": "2023-05-22T10:00:25.567Z",
  "deliveryDate": "2023-05-22",
  "invPeriodStart": "2023-05-22",
  "invPeriodEnd": "2023-05-22",
  "docsDeliveryStatus": "string",
  "docsDeliveryStatusDate": "2023-05-22T10:00:25.567Z",
  "docsDeliveryDlrStatus": "string",
  "docsDeliveryDlrStatusDate": "2023-05-22T10:00:25.567Z",
  "classCodeName": "string",
  "classDomain": "string",
  "classArea": "string",
  "lang": "string",
  "paymentStatus": "none",
  "paymentStatusDate": "2023-05-22T10:00:25.567Z",
  "disputeStatus": "string",
  "disputeStatusDate": "2023-05-22T10:00:25.567Z",
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "nettingInvoiceId": 0,
  "nettingInvoiceNumber": "string",
  "selfBilling": "yes",
  "domainId": 0,
  "domainCodeName": "string",
  "domainName": "string",
  "domainProduct": 0,
  "accountManagerId": 0,
  "accountManagerName": "string",
  "disputeNextId": 0,
  "collectionMode": "none",
  "collectionLeadId": 0,
  "collectionLeadNumber": "string",
  "collectionLeadNettingInvoiceId": 0,
  "collectionLeadNettingInvoiceNumber": "string",
  "collectionLeadNettingInvoiceStatus": "string",
  "collectionLeadNettingInvoicePaymentStatus": "string",
  "collectionLeadNettingInvoiceTotal": "string",
  "collectionLeadNettingInvoiceTotalPaid": "string",
  "collectionLeadNettingInvoiceTotalUnpaid": "string",
  "processingStatus": "none",
  "comment": "string",
  "nettingInvoiceStatus": "draft",
  "nettingPaymentStatus": "none",
  "nettingTotal": 0,
  "nettingTotalUnpaid": 0,
  "nettingTotalPaid": 0,
  "dtsSelectorId": 0,
  "dtsSelectorCodeName": "string",
  "sitInvoiceEmailImportId": 0,
  "billingBalance": {
    "id": 0,
    "name": "string",
    "resourceUrl": "string"
  },
  "billingTypeName": "string",
  "smsCount": 0,
  "syncStatus": "none",
  "syncStatusDt": "2023-05-22T10:00:25.567Z",
  "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"
}

Method Overview

The method returns a list of the Suppliers Invoices.

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

This endpoint is used to list invoices. Invoices can be filtered by many parameters, but most common are: custID, currency, domainCodeName, dataSourceCodName, classCodeName, dtsSelectorCodeName, status and paymentStatus.
This parameters are used in most queries to filter invoices.
Parameters custID and currency can be used to filter invoices for customer in currencies. status and paymentStatus parameters filter invoices per status.
domainCodeName parameter represents invoice's domain. Supported values are 'BULK' and 'BULK-MNP' for Bulk SMS and Bulk MNP invoices respectively.
dataSourceCodeName parameter represents invoice data source. Supported values are 'PREPAID', 'POSTPAID', 'FINANCE', 'SUPPLIER-INVOICE', 'POSTPAID-SUPPLIER-INVOICE', 'POSTPAID-CONTROL'.
classCodeName parameter represents document class and it is perhaps the most important one, because it allows to list different kind of invoices. Common values are 'CUSTOMER_INVOICE', 'SUPPLIER_INVOICE', 'NETTING_INVOICE', 'CONTROL_INVOICE', 'CREDIT_DEBIT_NOTE', 'SUPPLIER_CR_DB_NOTE'.
dtsSelectorCodeName represents subprocess of existing data source. The only supported dtsSelectorCodeName is 'PART-PAYMENT' for POSTPAID data source.
Each of these classes represent one kind of financial document. Because each document class has its own distinct properties and behavior, which differentiate that kind of document from other kinds, this filter property plays the key role in filtering invoices.

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

Supported filter properties are:

custName, custShortName, invNumber, invDate, invDueDate, overDueDate, status, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoiceTypeName, invoicingDate, invoicingDatePolicy, paymentStatus, nettingInvoiceId, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName, documentSync.

IMPORTANT: showAccountManager filter has been added, with 2 values (yes, no). If you want to see accountManagerId and accountManagerName, you need to call with this parameter showAccountManager=yes.

Examples:

1. Loading all member invoices (both supplier and customer) belonging to the netting invoice with id=100:

   GET /invoices?nettingInvoiceId=100

2. Loading the draft netting statements:

   GET /invoices?classCodeName=NETTING_INVOICE&status=draft

3. Loading the netting statements in favor of a supplier:

   GET /invoices?classCodeName=NETTING_INVOICE&paymentStatus=open&selfBilling=yes

4. Loading the netting statements in favor of a platform owner:

   GET /invoices?classCodeName=NETTING_INVOICE&paymentStatus=open&selfBilling=no

5. Loading the supplier invoices with a payment status open:

   GET /invoices?domainCodeName=BULK&classCodeName=SUPPLIER_INVOICE&paymentStatus=open

6. Loading the customer invoices with a payment status open:

   GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&paymentStatus=open

7. Loading the customer part-payment invoices:

   GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&dtsSelectorCodeName=PART-PAYMENT

8. Loading the customer postpaid without part-payment invoices:

   GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&dtsSelectorCodeName=0

9. Loading the control invoices:

   GET /invoices?domainCodeName=BULK&classCodeName=CONTROL_INVOICE

10. Loading the collection members for invoice:

    GET /invoices?collectionLeadId=X&...

11. Loading the documents which are member of the invoices collections:

    GET /invoices?collectionMode=member&...

12. Loading all documents which has processingStatus scheduled or running:

    GET /invoices?in(processingStatus)=scheduled,running&...

13. Loading all documents which has processingStatus scheduled or running:

    GET /invoices?showAccountManager=yes&...

URL Parameters

Name	Type	Description
page_number	integer (query)	Page number. The default value is 1.
page_size	integer (query)	Page size. The default value is 10.
paging	string (query)	Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
q	string (query)	General search criteria. Available fields: customerShortName, custName, status, invUid, ownerId, ownerBpName, ownerBpBriefName.
sort	string (query)	Sorting options. The format is: sort=-attribute1,attribute2,-attribute3. Available fields: customerShortName, invNumber, invDate, invDueDate, overDueDate, status, total, totalUnpaid, invoiceType, invPeriod, invPeriodStart, invPeriodEnd, invoiceTypeName, deliveryDate, nettingInvoiceId, paymentStatus, currency, id, disputeStatus, processingStatus, collectionMode, collectionLeadId, custID, vat, amountNoVat, amountVat, rounding, nettingInvoiceStatus, nettingInvoicePaymentStatus, invUid, ownerId, ownerBpName, ownerBpBriefName, invoicingDate, invoicingDatePolicy, documentSync.

Responses

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

Success Response 200: List of Invoices

{
  "data": [
    {
      "id": 0,
      "invUid": "string",
      "instanceID": 0,
      "custID": 0,
      "custName": "string",
      "custShortName": "string",
      "custAttn": "string",
      "custAddress": "string",
      "custAddress2": "string",
      "custPost": "string",
      "custCity": "string",
      "custCountry": 0,
      "custPOBox": "string",
      "customerType": "string",
      "custVatNumber": "string",
      "invType": 0,
      "invTypeName": "string",
      "templateID": 0,
      "invDate": "2023-05-23",
      "invoicingDate": "2023-05-23",
      "invoicingDatePolicy": "delivery",
      "invNumberFix": "string",
      "invNumberNum": 0,
      "invNumber": "string",
      "invPeriod": "string",
      "invDueDate": "2023-05-23",
      "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": "2023-05-23T11:26:00.124Z",
      "statusDt": "2023-05-23T11:26:00.124Z",
      "deliveryDate": "2023-05-23",
      "invPeriodStart": "2023-05-23",
      "invPeriodEnd": "2023-05-23",
      "docsDeliveryStatus": "string",
      "docsDeliveryStatusDate": "2023-05-23T11:26:00.124Z",
      "docsDeliveryDlrStatus": "string",
      "docsDeliveryDlrStatusDate": "2023-05-23T11:26:00.124Z",
      "classCodeName": "string",
      "classDomain": "string",
      "classArea": "string",
      "lang": "string",
      "paymentStatus": "none",
      "paymentStatusDate": "2023-05-23T11:26:00.124Z",
      "disputeStatus": "string",
      "disputeStatusDate": "2023-05-23T11:26:00.124Z",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "nettingInvoiceId": 0,
      "nettingInvoiceNumber": "string",
      "selfBilling": "yes",
      "domainId": 0,
      "domainCodeName": "string",
      "domainName": "string",
      "domainProduct": 0,
      "accountManagerId": 0,
      "accountManagerName": "string",
      "disputeNextId": 0,
      "collectionMode": "none",
      "collectionLeadId": 0,
      "collectionLeadNumber": "string",
      "collectionLeadNettingInvoiceId": 0,
      "collectionLeadNettingInvoiceNumber": "string",
      "collectionLeadNettingInvoiceStatus": "string",
      "collectionLeadNettingInvoicePaymentStatus": "string",
      "collectionLeadNettingInvoiceTotal": "string",
      "collectionLeadNettingInvoiceTotalPaid": "string",
      "collectionLeadNettingInvoiceTotalUnpaid": "string",
      "processingStatus": "none",
      "comment": "string",
      "nettingInvoiceStatus": "draft",
      "nettingPaymentStatus": "none",
      "nettingTotal": 0,
      "nettingTotalUnpaid": 0,
      "nettingTotalPaid": 0,
      "dtsSelectorId": 0,
      "dtsSelectorCodeName": "string",
      "sitInvoiceEmailImportId": 0,
      "billingBalance": {
        "id": 0,
        "name": "string",
        "resourceUrl": "string"
      },
      "billingTypeName": "string",
      "smsCount": 0,
      "syncStatus": "none",
      "syncStatusDt": "2023-05-23T11:26:00.124Z",
      "syncMode": "disabled",
      "reminderStatus": "enabled",
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyAmountNoVAT": 0,
      "domesticCurrencyAmountVAT": 0,
      "domesticCurrencyTotal": 0,
      "domesticCurrencyRounding": 0,
      "domesticCurrencyRate": 0,
      "industryName": "string",
      "ownerName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {}
    }
  ],
  "meta": {
    "pagination": {}
  }
}

Error Response Unexpected Error: Default

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

Method Overview

The method returns an invoice default configuration (type and template) for a given domain, data source, document class and co-owner ID.

Examples:

1. To get default config for the supplier invoices execute the following:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=SUPPLIER-INVOICE&docClassCodeName=SUPPLIER_INVOICE&coOwnerId=0

2. To get default config for customer prepaid invoices with english language template execute the following:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=POSTPAID&docClassCodeName=CUSTOMER_INVOICE&templateLang=en&coOwnerId=0

3. To get default config for customer postpaid invoices with serbian language template execute the following:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=POSTPAID&docClassCodeName=CUSTOMER_INVOICE&templateLang=sr&coOwnerId=0

4. To get default config for customer postpaid part payment invoices with en language template execute the following:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=POSTPAID&docClassCodeName=CUSTOMER_INVOICE&dtsSelectorCodeName=PART-PAYMENT&templateLang=sr&coOwnerId=0

5. Netting invoice config can be loaded using:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=FINANCE&docClassCodeName=NETTING_INVOICE&templateLang=sr&coOwnerId=0

6. Credit and debit note collection member type discovery:

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=FINANCE&docClassCodeName=CREDIT_DEBIT_NOTE&collectionCode=credit-note&templateLang=sr&coOwnerId=0

   GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=FINANCE&docClassCodeName=CREDIT_DEBIT_NOTE&collectionCode=debit-note&templateLang=sr&coOwnerId=0

When co-owners are enabled on a platform level, replace coOwnerId parameter with owner ID from a biz partner. If co-owners are disabled, coOwnerId should be 0 or not sent at all.

When querying invoice config values, replace templateLang parameter value with an appropriate value. Typically value of templateLang query parameter depends on an invoice biz partner, identified by custID property, and in most cases can be obtained using the Biz core API.

When templateId and templateLang values are present in a response, their values should be copied to an invoice create or update data properties templateId and lang. For example, these values are available when docClassCodeName is 'CUSTOMER_INVOICE' or 'NETTING_INVOICE'.
When docClassName is 'SUPPLIER_INVOICE', templateXXX property values are not applicable.

If template with requested language was not found, but there is a template for a given type but in different language, an existing template will be returned, and templateLang property will be set to available template language.

URL Parameters

Name	Type	Description
domainCodeName (required)	string (query)	Invoice domain (e.g. BULK).
dataSourceCodeName (required)	string (query)	Value represents business process code name (invoice data source) (e.g. FINANCE, PREPAID, POSTPAID, SUPPLIER-INVOICE, ...). PREPAID and POSTPAID are for customer invoices, SUPPLIER-INVOICE is for supplier invoices, FINANCE for netting statements and credit and debit notes.
docClassCodeName (required)	string (query)	Document class code name (e.g. CUSTOMER_INVOICE, CONTROL_INVOICE, SUPPLIER_INVOICE, NETTING_INVOICE, CREDIT_DEBIT_NOTE).
templateLang	string (query)	Requested template language code (e.g. en, de, sr, ...). Language codes are usually represented as 2 lowercase letters. The default value: en.
collectionCode	string (query)	collectionCode parameter must be used to discover document types for invoices which will be used as collection members. if collectionCode value is none, returned invoice type can not be used for documents which can be added as invoice collection members. Available values: none, credit-note, debit-no, reminder. The default value : none.
dtsSelectorCodeName	string (query)	Subprocess code name for selected data source. Currently only POSTPAID customer invoice PART-PAYMENT subprocess is supported.
coOwnerId	integer (query)	Owner ID of invoice biz partner.

Responses

Code	Description	Links
200	Invoice configuration data.	No links.
default	Unexpected error.	No links.

Success Response 200: Invoice data.

{
  "typeId": 0,
  "instanceId": 0,
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "dataSourceDefault": "string",
  "domainId": 0,
  "domainCodeName": "string",
  "name": "string",
  "status": "string",
  "docClassId": 0,
  "docClassCodeName": "string",
  "selfBilling": "string",
  "selfBillingOfType": 0,
  "docFactoryParams": "string",
  "comment": "string",
  "statusDt": "string",
  "templateId": 0,
  "templateLang": "string",
  "templateName": "string",
  "templateFileName": "string",
  "dtsSelectorId": 0,
  "dtsSelectorCodeName": "string"
}

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 Customer/Supplier Balance.

InvoiceCollection object properties:

Name	Type	Description
data (required)	array	An array of Invoice objects.
meta (required)	object	collectionMeta object.

Invoice object properties:

Name	Type	Description
id	integer	Invoice ID.
invUid	string	Invoice UID.
instanceID	integer	Instance ID.
custID	integer	Cstomer's ID.
custName	string	Customer's name.
custShortName	string	Customer's short name.
custAttn	string	Customer's attn data.
custAddress	string	Customer's address.
custAddress2	string	Customer's address2.
custPost	string	Customer's post code.
custCity	string	Customer's city.
custCountry	integer	Customer's country.
custPOBox	string	Customer's postbox.
customerType	string	Customer's type.
custVatNumber	string	Customer's VAT number.
invType	integer	Invoice type.
invTypeName	string	Invoice type name.
templateID	integer	Template ID.
invDate	string($date)	Invoice date.
invoicingDate	string($date)	Date of invoicing.
invoicingDatePolicy	string	Invoicing date policy. Possible values: delivery, creation, approval.
invNumberFix	string	The fixed part of an invoice number, based on this field system will define next invoice number.
invNumberNum	integer	The invoice number (variable part) - it counts invoices for the same invNumberFix.
invNumber	string	Invoice number.
invPeriod	string	Invoice period.
invDueDate	string($date)	Invoice's due date.
overDueDate	integer	Invoice's over due date.
ownerVatNumber	string	Owner's VAT number.
currency	integer	Currency.
currencyCode	string	Currency code.
amountNoVat	number($float)	Invoice amount without VAT (net amount). It can be negative when selfBilling is 'yes'.
amountVat	number($float)	Invoice amount including VAT. It can be negative when selfBilling is 'yes'.
vatPercent	number($float)	Percentage of the value added tax.
vat	number($float)	Value added tax.
rounding	number($float)	Difference between an invoice total and amount including VAT value.
total	number($float)	Invoice gross amount. It can be negative when selfBilling is 'yes'.
totalUnpaid	number($float)	Invoice's unpaid amount.
totalPaid	number($float)	Invoice's paid amount.
vatInPrice	integer	VAT in price.
vatInTotal	integer	VAT in total.
status	string	Invoice status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived, imported.
insertDt	string($date-time)	Date and time of insertion.
statusDt	string($date-time)	Date and time of the invoice's status.
deliveryDate	string($date)	Date of a delivery.
invPeriodStart	string($date)	Staring date of the invoice.
invPeriodEnd	string($date)	Ending date of the invoice.
docsDeliveryStatus	string	Delivery status.
docsDeliveryStatusDate	string($date-time)	Date and time of delivery status.
docsDeliveryDlrStatus	string	Delivery report status.
docsDeliveryDlrStatusDate	string($date-time)	Date and time of delivery report status.
classCodeName	string	Unique code name.
classDomain	string	Group of documents.
classArea	string	Business area/section, i.e. sales or purchase.
lang	string	Language.
paymentStatus	string	Payment status. Possible values: none, open, on-hold, closed.
paymentStatusDate	string($date-time)	Payment status date and time.
disputeStatus	string	Dispute status, indicates whether the invoice is in dispute process or not.
disputeStatusDate	string($date-time)	Dispute status date and time.
dataSourceId	integer	ID of a data source.
dataSourceCodeName	string	Data source code name. It represents invoice data source.
nettingInvoiceId	integer	Netting invoice ID.
nettingInvoiceNumber	string	ID of an invoice netting.
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 a buyer, but issued by a 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 a buyer, but issued by a seller. Possible values: yes, no.
domainId	integer	Domain ID.
domainCodeName	string	Invoice domain (e.g. BULK).
domainName	string	Domain name.
domainProduct	integer	Domain product.
accountManagerId	integer	Account manager ID.
accountManagerName	string	Account manager name.
disputeNextId	integer	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	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" }.

BillingBalance object properties:

BillingBalance is Invoice Condition which an invoice is associated to.

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

InvoiceConfig object properties:

Name	Type	Description
typeId	integer	ID of invoice type.
instanceId	integer	Instance ID.
dataSourceId	integer	ID of a data source.
dataSourceCodeName	string	Data source code name. It represents invoice data source.
dataSourceDefault	string	Is this type default for DTS. Only one invoice type can be default for certain dts_id within the same instance_id + co_owner_id
domainId	integer	Domain ID.
domainCodeName	string	Invoice domain (e.g. BULK).
name	string	Invoice name.
status	string	Invoice status.
docClassId	integer	Relation to finance document class definition which categorizes what kind of invoices this type holds (customer invoice, supplier invoices, control invoices, etc).
docClassCodeName	string	Document class code name (e.g. CUSTOMER_INVOICE, CONTROL_INVOICE, SUPPLIER_INVOICE, NETTING_INVOICE, CREDIT_DEBIT_NOTE).
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 a buyer, but issued by a 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 a buyer, but issued by a seller. Possible values: yes, no.
selfBillingOfType	integer	self_billing_of_type - if self_billing = 'yes', then this is relation to 'regular' invoice type (if self billing type represents 'Credit Note' then self_billing_of_type will point to Invoice type).
docFactoryParams	string	doc_factory_params - JSON object used to pass to document creator factory. The attribute 'factory' is mandatory (it is class selector), other attributes will be documented if they are introduced.
comment	string	Comment.
statusDt	string	Date and time of the invoice's status.
templateId	integer	A template ID.
templateLang	string	Requested template language code (e.g. en, de, sr, ...). Language codes are usually represented as 2 lowercase letters. The default value: en.
templateName	string	Template name.
templateFileName	string	Template file name.
dtsSelectorId	integer	ID reference to DTS selector, e.g. for part-payment invoice.
dtsSelectorCodeName	string	DTS selector code name.

JSON example

{
  "typeId": 0,
  "instanceId": 0,
  "dataSourceId": 0,
  "dataSourceCodeName": "string",
  "dataSourceDefault": "string",
  "domainId": 0,
  "domainCodeName": "string",
  "name": "string",
  "status": "string",
  "docClassId": 0,
  "docClassCodeName": "string",
  "selfBilling": "string",
  "selfBillingOfType": 0,
  "docFactoryParams": "string",
  "comment": "string",
  "statusDt": "string",
  "templateId": 0,
  "templateLang": "string",
  "templateName": "string",
  "templateFileName": "string",
  "dtsSelectorId": 0,
  "dtsSelectorCodeName": "string"
}

4.2 Meta

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

CollectionMeta object properties:

Name	Type	Description
collectionMetaPagination	object	collectionMetaPagination object.

CollectionMetaPagination object properties:

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

CollectionMetaPaginationLinks object properties:

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

JSON example

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