Create your own sandbox

You may start by creating your own company (the one that will receive invoices from EasyUBL) directly in the EasyUBL API. If you fill in the small json document under the "Company/Update" function and press "Execute", the company is created and you are ready to send/receive. Please note that only "real" companies can be created. You cannot therefore create fictitious companies with company numbers that are not registered. The new company will immediately appear in the list of your Tenant's companies in the "Bookkeepers page". As soon as you have done this, we will send you a test invoice. This will appear in the document list. A company can send invoices to itself. You can therefore also immediately try sending your company an invoice directly from the EasyUBL API. Now you can see that the functions work. You then have to make the same thing happen from your application. This is of course much more difficult than our small example. It would be a good idea to start with an online meeting with EasyUBL, where we will show you examples of how it can be done.

Your company will immediately receive UBL invoices, not only from EasyUBL. It would therefore be appropriate to have these loaded into the ERP system first. You can see the document (voucher) EasyUBL delivers under the Creditor/NextTransaction function. The task is to retrieve this document and deliver it to the ERP system's journal. You can do this much more elegantly by using EasyUBL webhooks. The document delivered by our webhook is the same as the one retrieved with the API call. The document also contains information relating to goods transactions. You can skip these for now. Handling stock receipts in the ERP system is considerably more complicated than bookkeeping. The document you receive for accounting contains the invoice as XML, pdf and html. The accountant's site archives these documents for 3 months. If it is not possible to archive the documents in the ERP system, we can store them in EasyUBL (price?)

Before you can send/receive, you must create a company

If the company is not registered in advance by another intermediary, the registration will be done immediately and you are ready to send/receive.
If the company is registered by another intermediary, the function will announce this. You must then ask this company to cancel the registration.

As soon as you have completed the creation, the company will receive documents. You can immediately access the documents you receive in "The bookkeeper's page".
Please note that you must use the established company's contact information (email, SMS) to access the documents.

As the company address is used as a sender address (Supplier) in the document, you must continuously maintain the address Information.
Creation and maintenance is handled by a single function in EasyUBL “API/Company/Update”. The company is identified in EasyUBL with a guid (key). The first time you call "Company/Update" you deliver an empty guid. This tells EasyUBL that you want to create a new company. Company/Update will return a guid, that you store in the local database. This guid will be used for future maintenance.

You call Company/Update every time a company address is changed. If it is difficult to incorporate this call into your application, the maintenance can be carried out by a small console application that replicates with a time interval.

API/Company/AddUpdateCompany

HttpClient myClient = new HttpClient(); myClient.DefaultRequestHeaders.Add("Authorization", ApiKey); string myUrl = String.Concat("https://EasyUBL.net/api/Company/Update/", CompanyId); string myCompanyJson = JsonConvert.SerializeObject(myCompany); var stringContent = new StringContent(myCompanyJson, UnicodeEncoding.UTF8, "application/json"); var response = await myClient.PostAsync(myUrl, stringContent); response.EnsureSuccessStatusCode(); if (response.IsSuccessStatusCode) { var responseContent = await response.Content.ReadAsStringAsync(); string sub = (string)JsonConvert.DeserializeObject(responseContent); CompanyId = Guid.Parse(sub); // save the company guid in your application }

-

public class companyEasyUBL { public string name { get; set; } public string cvr { get; set; } public string currency { get; set; } public string country { get; set; } public string? webhookUrl { get; set; } public addEndpoint defaultEndpoint { get; set; } public addAddress defaultAddress { get; set; } public addContact defaultContact { get; set; } public addPayment payment { get; set; } public bool? DoNotReceiveUBL { get; set; } = false; } public class addEndpoint { public string endpointType { get; set; } public string endpointIdentifier { get; set; } } public class addAddress { public string? name { get; set; } public string? streetName { get; set; } public string? additionalStreetName { get; set; } public string? buildingNumber { get; set; } public string? inhouseMail { get; set; } public string? department { get; set; } public string? attensionName { get; set; } public string? cityName { get; set; } public string? postalCode { get; set; } public string? countrySubentity { get; set; } public string? countryCode { get; set; } } public class addContact { public string roleCode { get; set; } public string name { get; set; } public string email { get; set; } public string sms { get; set; } } public class addPayment { public string bankname { get; set; } public string bankRegNo { get; set; } public string bankAccount { get; set; } public string bic { get; set; } public string iban { get; set; } public string CreditorIdentifier { get; set; } }

The preferred way to send an invoice

Sending invoices and receiving notifications should be the easy way to handle an invoice. The possibilities depend entirely on the extent to which it is possible to make changes to the ERP system. The integration with EasyUBL is the easy part. Don't underestimate the importance of handling notifications.

Invoices are sent with the feature /api/ SendDocuments/ Invoice/ {companyId} The function demands "companyId" as a parameter to identify the sender company address (the supplier). This ensures that no one sends invoices on your behalf through EasyUBL. This information is found in your database after calling AddUpdate (create companies). The function SendDocuments/Invoice" sends the invoice and returns the complete UBL document.

HttpClient myClient = new HttpClient(); myClient.DefaultRequestHeaders.Add("Authorization",myTenantKey); string myUrl = String.Concat("https:// EasyUBL.net/api /SendDocuments/ Invoice/", companyId); string myInvoiceJson = JsonConvert.SerializeObject(myInvoice); var stringContent = new StringContent(myInvoiceJson, UnicodeEncoding.UTF8, "application/json"); var response = await myClient.PostAsync(myUrl, stringContent); response.EnsureSuccessStatusCode(); myXmlDocument = await response.Content.ReadAsStringAsync();

You should archive the complete UBL document in the database. This is the legal document the recipient receives. In the event of disputes, the complete UBL document is what must be referred to. Human readable versions formed on the fly like PDF, HTML etc. must be considered "copies with special features" like being human readable, but they are not the legal document. That is solely the actual complete UBL document. Some recipients have special requirements for the content, that must be agreed with the invoice issuing company. For example, this could be a requisition number, specific contact persons, accounting codes, cost centers etc. If the recipient has an elaborate system, a message will be returned, if any of these informations are missing. If the recipient behaves correctly, this message will indicate, where in the UBL document this information must be placed. This means that you will be notified very quickly after sending a document, and you can then add any missing information, if that's the case, and resend it right away, not having to hunt down someone at the sender, who knows where the information should be found in the document. Furthermore, the UBL document is the legal document. In the event of disputes, this is what must be referred to. Human readable versions can be considered copies with special abilities that are formed on the fly.

The document may be built in this way. This is only an example to illustrate the scope. Data is read from an SQL server and placed in the json document.

SqlDataReader myr = Comm.ExecuteReader(); if (myr.Read()) { int AddressID = (int)myr["So_addressID"]; if (AddressID == 0) errCode = 1; int CreInvFactor = (int)myr["CreInvFactor"]; if (CreInvFactor == -1) myI.invoiceCreditnote = "Cre"; else myI.invoiceCreditnote = "Inv"; myI.id = new(myr["InvoiceNo"].ToString()); myI.documentCurrencyCode = myr["Currency"].ToString().ToUpper(); myI.issueDate = (myr["InvDate"].Equals(DBNull.Value) ? DateTime.Today : (DateTime)myr["InvDate"]); myI.dueDate = (myr["PayDate"].Equals(DBNull.Value) ? DateTime.Today : (DateTime)myr["PayDate"]); myI.accountingCost = myr["AccountingCost"].ToString(); myI.buyerReference = myr["requisition"].ToString(); long OrderNo; long.TryParse(myr["OrderNo"].ToString(), out OrderNo); myI.salesOrderID = OrderNo.ToString(); myI.note = string.Concat(myr["text_1"], " ", myr["text_2"]).Trim(); if (myr["ShipDate"].Equals(DBNull.Value)) myI.deliveryDate = myI.issueDate; else myI.deliveryDate = (DateTime)myr["ShipDate"]; int thisContId = myr["ContID"] == DBNull.Value ? 0 : (int)myr["ContID"]; myI.accountingCustomerParty = GetPartyInfo((int)myr["So_addressID"]); myI.accountingCustomerParty.Contact = GetContactInfo((int)myr["So_addressID"], thisContId); if (string.IsNullOrEmpty(myI.accountingCustomerParty.Contact.name)) { myI.accountingCustomerParty.Contact.name = myI.accountingCustomerParty.name; } myI.totalAmount = (decimal)myr["amount"]; myI.accountingCustomerParty.postalAddress = GetPostalAddress((int)myr["Sh_addressID"]); if ((int)myr["Sh_addressID"] != 0) myI.deliverAddress = GetPostalAddress((int)myr["Sh_addressID"]); myI.invoiceLines = GetLines(saleID); } return myI;

It is a traditional mapping of the fields found in the local database for the JSON document describing the invoice. Enjoy the fact that it is significantly easier to map for this document than to the underlying XML document. Feel free to use the source text for this application. If you turn to Easyubl support, we will be happy to help with advice and guidance.

A real-time and seamless integration

To receive a webhook, you must have an api that can service all of your tenant's companies. EasyUBL webhook calls a url, that you provide when creating your tenant It could be: https://myBasicURL/api/ tools/ UBLNotifications The webhook call to your service will contain a small json document: { "companyId": "c9b89d84-cdb6-4207-8a99-23c7ffb04577", "endpointId": "df4967d4-7e4d-4f23-9653-b8bd1b8719b2", "ublDocumentId": "22323456", "documentStatusCode" : "5110", "documentType": "110", "actionCode": "2", "errorCode": "-1", "base64EncodedMessage": "Not sent", "externalIdentifier": "5053387" "documentXmlBase64Content" } CompanyId will make it possible to find the company in your application. This is the key that was returned, when you created the company. You probably don't use EndpointId for anything. ublDocumentID is an internal ID in the system, that makes it possible to backtrace the document. You don't use it. externalIdentifier will contain your invoice number/order number etc. depending on the document type. We currently support document types 100 (order), 110 (Invoice), 120 (credit note) and Essy100 (Financial documents and goods transactions). "base64MEssage" and "documentBase64" will contain information related to the document type. When you receive documents, the document is associated with the notification. You can therefore save the document in the ERP system as soon as it is received. The person(s) who must approve the document simultaneously receives the document for approval. The received document can be processed into usable data with the tools "Human readable", "Creditor Booking" and "Goods Handling" When you receive invoices from cost creditors, the received document is the accounting vaucher. You must therefore archive it as it is. This is the document the sender is responsible for. If the recipient system is not able to present a UBL document itself, you can archive the readable format in the recipient database. You can also simply save the UBL document and use EasyUBL to convert the document when it is displayed. Upon receipt, EasyUBL will send a copy of the document to an approver. This is not the "invoice" but a copy for the approver. It should not be saved. If the receiving system does not receive UBL documents at all, the recipient's copy can be perceived as the original. This is just as acceptable as only sending the invoice as a pdf document by email. Not all ERP systems are able to receive a webhook. We have the option of delivering notifications in other ways. The solution will depend on the receiving system. Contact easyUBL and we will find a solution. The ERP system must use vouchers for the accounts, goods transactions, orders and human-readable documents. Functions in Tools make these translations. The functions receive the archived document and return the data that is useful for the ERP system. Feel free to use the source text for this application. If you turn to EasyUBL support, we will be happy to help with advice and guidance.

We talk to everyone

For systems that do not work online, we have various alternative solutions. We can give you access to a SQL server database where the notifications are in a table. We can provide a robot that is installed locally. This can retrieve information on a schedule that is delivered to a folder in the file system. We provide source code for this robot so you can expand and modify it according to local needs. The alternative methods are not described here, but you are welcome to contact EasyUBL if you need alternatives. We can usually find a solution.