InvoiceBorg

InvoiceBorg User Manual

Coderit s.r.l. <info@coderit.it>

InvoiceBorg is a REST service that converts invoices from one format to another.

Please note this is an early-access version of the service. The API interface, the service content or any other technical details can change without notice.

1. Quick Start

In these short examplee we will use the InvoiceBorg REST API to convert an invoice in Italian format FattPA to the Peppol format.

Take note of the following data used to access the REST API, you’ll need to use them:

  • client_id=sample-trial-customer

  • client_secret=`5e37beb1-ed13-45b3-9e3c-378c8d81e481

You can click here to get the sample FattPA invoice.

1.1. Using cURL

This example uses cURL to demonstrate how to interact with InvoiceBorg REST API programmatically. It should not be impossible to convert the cURL commands listed here in any language you may use in your solution.

The first step is to authenticate with the API, getting back a token that you can use for later interactions, using the client_id and client_secret parameters and get a token that can be later used for subsequent calls. Execute the following POST with BASIC authentication, using client_id and client_secret as username and password.

curl \
-X POST \
--user sample-trial-customer:5e37beb1-ed13-45b3-9e3c-378c8d81e481 \
'https://invoiceborg.coderit.it/auth/realms/coderit/protocol/openid-connect/token' \
-H 'content-type: application/x-www-form-urlencoded' \
-H 'authority: fatt.apps.coderit.it' \
--data 'grant_type=client_credentials' \
--compressed

This will return a json result with several information. The value of some fields have been shortened for readability’s sake. The token you should use in later invocations is the one in the access_token field. In your case the access_token would be obviously different than the one shown here.

{
    "access_token": "eyJ...JtQ",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "opr...C3k",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "b7fea4c8-9f85-4d83-887c-dcdd41e64fec",
    "scope": "email profile"
}

You can now use the access_token just obtained to invoke the conversion of an invoice written in "fatturapa" format to the equivalent invoice in "peppolbis" format.

curl \
-X POST \
--verbose \
"https://invoiceborg.coderit.it/api/v1/convert/fatturapa/peppolbis" \
-H "accept: *" \
-H "Authorization: Bearer eyJ...JtQ" \
-H "Content-Type: multipart/form-data" \
-F "file=@samples/fattpa-sample-plain.xml;type=text/xml" \

If all it’s well you should get the invoice converted in the "peppolbis" output format.

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ccts="urn:un:unece:uncefact:documentation:2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>20150483</cbc:ID>
  <cbc:IssueDate>2015-04-14</cbc:IssueDate>
  <cbc:DueDate>2015-04-14</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:Note>Esempio fattura trasformata da CEN a XML-PA</cbc:Note>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  ...
</Invoice>

1.2. Using Swagger UI

Point your web browser to <https://invoiceborg.coderit.it/api-docs/swagger-ui.html> to access an OpenAPI powered client that allows you to play around with the API.

Click the lock icon in the top right angle, an authorization pop-up will show.

Input both the client_id and the client_secret values in the proper fields.

Click the Authorize button to perform a login. If is it successful, close the pop-up.

To convert an invoice click on the line /api/v1/convert/{source}/{target} line, representing the conversion REST entrypoint.

Click the Try it out button.

In the source field type exactly: fatturapa

In the destination field type exactly: peppolbis

Click on the Choose file button under the Request Body section to select the file containing the invoice you want to convert. Select the fattpa-sample-plain.xml file.

Click the Execute button.

The REST service will convert the invoice and return it in a file you can download.

2. Open API

The Open API definition file for InvoiceBorg REST API can be found here: <https://invoiceborg.coderit.it/api-docs/api-docs>.

3. License

InvoiceBorg makes use of an open source software licensed under the European Union Public License (EUPL 1.2). The project fork can be found here: <https://github.com/coderit-srl/EeISI-mapper>.