API Process

Process

Customers Creation

New customers are created using customers API with provided specific information about this customer. More generic information such as posting groups is assigned from Customer Template. Customer Template is assigned according to templates defined in E-Invoice Setup.

The template is automatically selected according to country defined in API request.
Default dimensions can be assigned to customer at the same request as they are created together with $expand=defaultDimensions method (if customer/vendor template does not contain that default dimension).

Vendors Creation

New vendors are created using vendors API with provided specific information about vendor. The same way as with customers, you can enable setup in E-Invoice setup to assign Vendor Templates for each of the vendor. With vendors you can make analogical requests as with customers. In addition to that, together with vendors creation Vendor Bank Accounts can be created with vendorBankAccount API.

Sales Documents Creation

Sales Invoices are created using salesInvoices API. It is useful to use expand method in order to minimize the number of requests. Most of the information (fields that start with billTo, shipTo, sellTo) are filled automatically from customer table, so only these fields could be filled on request only when their values differ from those defined in customer table.

Sales Credit Memos are created using salesCreditMemos API.

Total sums checks between BC and integrating system
apiTotalAmountExclVAT and apiTotalAmountInclVAT fields are required to be added to request to check amounts between integrating system and Business Central. Rounding and total amount calculation can differ between different systems, so it is crucial to check if amounts align, and correct if needed.

Expand methods

Sales Invoices
salesInvoiceLines API, to provide document lines for a document.
documentAttachments API, if additional documents need to be provided, i.e. Sales Contract. Document Attachment content can be provided through separated PATCH request.

For more specific example of this API usage, please refer to provided Json Collection in Overview section.

Sales Credit Memos
salesCreditMemoLines API.
documentAttachments API.

Purchase Documents Creation

Purchase Invoices are created using purchaseInvoices API. Most of the information (fields that start with payTo, shipTo, buyFrom) are filled automatically from vendor table, so only these fields could be filled on request only when their values differ from those defined in vendor table.

Purchase Credit Memos are created using purchaseCreditMemos API.

Expand methods

Purchase Invoices
purchaseInvoiceLines API.
documentAttachment API.

Purchase Credit Memos
purchaseCreditMemoLines API.
documentAttachment API.

FAQ

Customers/Vendors API.

1. How can we use templates if we have more than 3 customer/vendor templates defined?
Customer Template Code should be filled in directly customers API request (field customerTemplateCode).
For vendors process, vendorTemplateCode in vendors API request should be filled.
For both cases “Assign Default Template“ checkbox in “E-Invoice Setup“ table should be unmarked.
2. How can I assign payment terms for each customer/vendor?
All possible Payment Terms for the company could be taken using GET request on paymentTerms API.
Payment terms can be defined using paymentTermsCode or paymentTermsId fields in customer/vendor API.
If you have multiple companies using the same paymentTerms codes, then paymentTermsCode could be more effective to use.
Once payments terms code is assigned for customer, this payment term is assigned automatically to sales documents and due date is calculated accordingly.
3. How default dimensions should be assigned?
In order to assign default dimensions for customer/vendor defaultDimensions API should be used. You can assign it at the same request with a master table using $expand method or with a separated request as defined in documentation. The required fields are:
dimensionCode - a dimension code that you want to use.
dimensionValueId - dimensionValueCode cannot be added directly, because it is Read-Only field. In order to get a dimensionValueId for a value code, you need to make a request to dimensionValues API and filter by dimensionCode and code (which would be value code) - then you could take id field value for dimensionValueId field.

4. Where I could store additional information from integrating system to BC?
If you need to store customer/vendor number defined in other system or direct link to this system in BC, you can add this information using customerLink and vendorLink fields.

Sales Documents:

1. How can I take Sales Invoice printout from Business Central?

You can use a separated GET request using pdfDocument request. Printout report and layout is selected using Report Selections setup for each document type. If there are more than 1 report defined, the first report in sequence is selected.
If you need a specific example, please refer to Json Collection.

2. Could I post Sales Invoice Lines on a separated requests?
It is possible, although we recommend using expand requests in order to reduce the number of requests and post whole document to BC once you have a final version of the document in other platform.
Furthermore, If you have a lot of lines in an invoice, consider using $batch requests.

3. Can I assign dimensions to the document lines directly on the same request?

Regarding dimensions, it is important to decide where your master data would be - in Business Central or in other platform. If you assign default dimensions for customer, vendor, G/L Accounts and Items then changing them in document lines could be problematic - you’ll need to make additional PATCH requests to change default values. For example, if your company is selling services and in sales invoice lines those services are issued to the same G/L Account(type = “G/L Account“) and it has different dimensions, then no default dimensions should be assigned.

If no default values are assigned, then it is possible to add dimensions to salesInvoiceLines directly using $expand method with dimensionSetLines API at the same request.