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:
-
Loading all member invoices (both supplier and customer) belonging to the netting invoice with id=100:
GET /invoices?nettingInvoiceId=100
-
Loading the draft netting statements:
GET /invoices?classCodeName=NETTING_INVOICE&status=draft
-
Loading the netting statements in favor of a supplier:
GET /invoices?classCodeName=NETTING_INVOICE&paymentStatus=open&selfBilling=yes
-
Loading the netting statements in favor of a platform owner:
GET /invoices?classCodeName=NETTING_INVOICE&paymentStatus=open&selfBilling=no
-
Loading the supplier invoices with a payment status open:
GET /invoices?domainCodeName=BULK&classCodeName=SUPPLIER_INVOICE&paymentStatus=open
-
Loading the customer invoices with a payment status open:
GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&paymentStatus=open
-
Loading the customer part-payment invoices:
GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&dtsSelectorCodeName=PART-PAYMENT
-
Loading the customer postpaid without part-payment invoices:
GET /invoices?domainCodeName=BULK&classCodeName=CUSTOMER_INVOICE&dataSourceCodeName=POSTPAID&dtsSelectorCodeName=0
-
Loading the control invoices:
GET /invoices?domainCodeName=BULK&classCodeName=CONTROL_INVOICE
-
Loading the collection members for invoice:
GET /invoices?collectionLeadId=X&...
-
Loading the documents which are member of the invoices collections:
GET /invoices?collectionMode=member&...
-
Loading all documents which has processingStatus scheduled or running:
GET /invoices?in(processingStatus)=scheduled,running&...
-
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:
-
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
-
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
-
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
-
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
-
Netting invoice config can be loaded using:
GET /default-invoice-config?domainCodeName=BULK&dataSourceCodeName=FINANCE&docClassCodeName=NETTING_INVOICE&templateLang=sr&coOwnerId=0
-
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. |
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"
}
}
}