SAPHETY

1. Integrations details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 Web Services integration - REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Web Services Integration - Create Document Full Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
 Integrations details
Following are the flows and integration points between as invoice issuer and a Virtual Operator (Electronic Invoicing System - EIC).

Document issuing with EIC

1 Integration options (synchronous, asynchronous)

There are 2 options to integrate with the Electronic Invoicing System.

Synchronous
The synchronous API is available via the EIC Rest Webservices.

This document in section(Web Services integration) describes all the API calls required to fulfill the process ilustrated in (fig. Document issuing
with EIC)

Asynchronous
The Asynchrounous intgration is provided via a set of communication protocols and formats supported by "Trade"

This document in section (Asynchronous Integration) describes the message formats and communication protocols accepted in order to fulfill the

Saphety Level, Trusted Services

 process ilustrated in (fig. Document issuing with EIC)

Web Services integration - REST API

The full REST API is available under Swagger documentation at your EIC system endpoint

Below we describe the minimum API interacto required to

ex:https://api-einvoicing-co.saphety.com/swagger

Authentication
These web-services use a bearer token authentication.
The authentication token can be obtained providing a username and password.

Request token (gettoken):

Saphety Level, Trusted Services

 Url: https://<APIBASEURL>/auth/gettoken
Http Method: POST
ContentType: application/json
Body:
{
"grant_type":"password",
"username":"my_username",
"password":"my_password",
"virtual_operator":"my_VirtualOperatorAlias"
}

Authentication response sample

{
"access_token": "eyJ0eX(...removed for security...)RnxY",
"expires": "2017-05-09T18:48:11.1671844Z",
"token_type": "bearer"
}

These credentials are also suitable to login at web application.

Saphety Level, Trusted Services

 The issuer application must be aware of these credentials.

Before calling any service the token must be acquired.

Api create sales invoice request sample

Url:
https://<APIBASEURL>/<VirtualOperatorAlias>/outbounddocuments/salesinvoice
Http Method: POST
ContentType: application/xml
Authorization: Bearer eyJ0eX(...removed for security...)RnxY
Body:
<SalesInvoice>
<IssueDate>2017-03-01T00:00:00</IssueDate>
(...removed legibility..)
</SalesInvoice>

Api response sample

Error response sample

{
"IsValid": false,
"Errors": [ {
"Field": "SalesInvoiceDTO.CorrelationDocumentId",
"Code": "Duplicated",
"Description": null
}

],
"Documents": [],
"ResultData": [],
"ResultCode": 400
}

Saphety Level, Trusted Services

 Document creation Ok response
{
"IsValid": true,
"Errors": [],
"Documents": [
{
"Id": "2b57bd79-08b7-4363-8312-91eca3ab2f54",
"Content": "PD94bWwgdmVy(...removed base 64 for legibility..)2ljZT4=",
"ContentType": "text/xml"
}
],
"ResultData": [],
"ResultCode": 200
}

What happens after successful document creation?

If the document creation is successful, as shown above, the document Id is returned ("Id": "2b57bd79-08b7-4363-8312-91eca3ab2f54").

Note that with the successful response on invoice creation you will also obtain the certified invoice according the DIAN UBL
specification:

Content": "PD94bWwgdmVy(...removed base 64 for legibility..)2ljZT4="

We strongly recommend that this Id is stored in the HIS associated with the correspondent internal document. The purpose of this internal
association is to use the API calls to interact with the document on the eInvoice platform.

Now, we will describe the calls that allows to consult the document business status/communication status within the eInvoice platform assuming
that the HIS has the document Id and how to obtain the document details (e.g. certified Dian UBL file, PDF, metadata).

Get the document details (metadata):

Request
Url:
https://<APIBASEURL>/<VirtualOperatorAlias>/documents/2b57bd79-08b7-4363-8
312-91eca3ab2f54
Http Method: GET
ContentType: application/json
Authorization: Bearer eyJ0eX(...removed for security...)RnxY

Saphety Level, Trusted Services

 Response
{
"Id": "2b57bd79-08b7-4363-8312-91eca3ab2f54",
"Number": "FE983004349",
"DocumentType": "SalesInvoice",
"DocumentSubType": null,
"CreationDate": "2017-05-26T15:55:29.7215844",
"IssueDate": "2017-05-26T00:00:00",
"Issuer": "Issuer Company Colombia",
"IssuerVAT": "", /* Deprecated */
"Customer": "Customer Company Colombia",
"CustomerVAT": "", /* Deprecated */
"CustomerPartyEmail": "customer.company@EIC.com",
"Currency": "COP",
"TotalAmount": 23200,
"BusinessStatus": "Certified",
"BusinessStatusReason": null,
"CommunicationStatus": "DeliverOk",
"DocumentFiles": [
{
"Id": "a5aa2453-a00e-49af-a31b-143e5a7d5fb3",
"FileName": "FE983004349_26/05/2017.xml",
"DocumentFormat": "XML"
},
{
"Id": "6ce56a91-32f5-48ea-b1a7-0f9893c915a3",
"FileName": "FE983004349.pdf",
"DocumentFormat": "PDF"
}
]
}

1. In this example, we retain the status information:

"BusinessStatus": "Certified",
"BusinessStatusReason": null,
"CommunicationStatus": "DeliverOk",

The status lifecycle is shown below:

Business Status:

Saphety Level, Trusted Services

 Communication Status:

Saphety Level, Trusted Services

 2. Here, we describe how to obtain certified Dian UBL file, PDF and attachments:

Get the document certified Dian UBL:

In the "Document Files" information present on the example, we have:

{
"Id": "a5aa2453-a00e-49af-a31b-143e5a7d5fb3",
"FileName": "FE983004349_26/05/2017.xml",
"DocumentFormat": "XML"
},

This identifies the certified Dian UBL document retrieved on document details.

Saphety Level, Trusted Services

 Request
Url:
https://<APIBASEURL>/<VirtualOperatorAlias>/documents/2b57bd79-08b7-4363-8
312-91eca3ab2f54
Http Method: GET
ContentType: application/json
Authorization: Bearer eyJ0eX(...removed for security...)RnxY

Response
+ACbhbC4KZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8L1N1YnR5cGUvVHlwZTAvVHlwZS9Gb
250L0Jhc2VG

(...removed to simplify visualization...)

b250L0tGUkpSSCtBcmlhbC9FbmNvZGluZy9JZGVudGl0eS1IL0Rlc2NlbmRhbnRGb250c1sxNC
AwIFJdL1RvVW

Web Services Integration - Create Document Full Example

In this section, you'll find a detailed example on how to create a document in the eInvoice platform.

This example assumes that:

a. The operator administrator has already created your issuer company in the eInvoice platform;
b. The operator administrator has already created a user associated with your company;
c. For this steps you are always authenticated in the eInvoice platform:
For this example, the company user credentials are:
Email: issuer@company.com
Password: password.2017

First Step:

Create a valid series to be used on document creation. Note that the invoice number can be either generated by the eInvoice platform (Is
Autoincrement = true) or serialized through the HIS (Is Autoincrement = false).

In the following image, we have the result of a successful example Series creation.

Note that, when you create a new Series, by default is created inactivated, you'll have to activate it in the Serie details page.

Saphety Level, Trusted Services

 Second Step:

Now you'll just have to submit the document from your HIS invoking the API endpoint as follows:

Note that this request is made using a xml document, but you can send a document in the json format, for that you just have to change
the contentType field to application/json

Request
Url: https://<APIBASEURL>/EIC/outbounddocuments/salesinvoice
Http Method: POST
ContentType: application/xml
Authorization: Bearer eyJ0eX(...removed for security...)RnxY
Body: <?xml version="1.0" encoding="utf-8"?>
<SalesInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<CorrelationDocumentId>FRONTEND-14961589146771</CorrelationDocumentId>
<IssueDate>2017-05-30T00:00:00</IssueDate>
<BillingPeriod>
<From>2016-09-15T02:17:51.2487067</From>
<To>2016-09-15T19:00:15.1498338</To>
</BillingPeriod>

Saphety Level, Trusted Services

 <IssuerParty>
<Identification>
<DocumentNumber>900111111</DocumentNumber>
<DocumentType>NIT</DocumentType>
<CountryCode>CO</CountryCode>
</Identification>
</IssuerParty>
<CustomerParty>
<Person>
</Person>
<LegalType>Legal</LegalType>
<Identification>
<DocumentNumber>800047326</DocumentNumber>
<DocumentType>NIT</DocumentType>
<CountryCode>CO</CountryCode>
</Identification>
<WebsiteUrl></WebsiteUrl>
<Email>customer@EIC.com</Email>
<Name>Customer EIC</Name>
<Address>
<City>BOGOTA</City>
<AddressLine>AVENIDA 92-92</AddressLine>
<Country>CO</Country>
</Address>
<TaxScheme>Simplex</TaxScheme>
<FiscalCategory>Simplified</FiscalCategory>
</CustomerParty>
<Currency>COP</Currency>
<Lines>
<Line>
<Number>1</Number>
<Item>
<Description>Lavavasillas BAZARSUN 1L</Description>
</Item>
<Quantity>200</Quantity>
<GrossAmount>20000.00</GrossAmount>
<UnitPrice>100.00</UnitPrice>
<TaxableAmount>20000.00</TaxableAmount>
<TaxPercentage>16.00</TaxPercentage>
<TaxAmount>3200.00</TaxAmount>
<NetAmount>23200.00</NetAmount>
<QuantityUnitOfMeasure>A12</QuantityUnitOfMeasure>
<TaxCategory>IVA</TaxCategory>
</Line>
</Lines>
<TaxSummaries>
<TaxSummary>
<TaxCategory>IVA</TaxCategory>
<TaxPercentage>16.00</TaxPercentage>
<TaxableAmount>20000.00</TaxableAmount>
<TaxAmount>3200.00</TaxAmount>
</TaxSummary>
</TaxSummaries>

Saphety Level, Trusted Services

 <Total>
<GrossAmount>20000.00</GrossAmount>
<PayableAmount>23200.00</PayableAmount>
<TaxableAmount>3200.00</TaxableAmount>
</Total>
<IssueMode>Electronic</IssueMode>
<DueDate>2017-05-30T00:00:00</DueDate>
<DeliveryDate>2017-05-30T00:00:00</DeliveryDate>

Saphety Level, Trusted Services

 <AuthorizationNumber>0000000000000000</AuthorizationNumber>
<SerieExternalKey>S/O4AMZv2v</SerieExternalKey>
</SalesInvoice>

In this example, we have a successful document creation with the following response:

Response
{
"IsValid": true,
"Errors": [],
"Documents": [
{
"Id": "8459e3b7-c794-4b60-8217-9257bf66a18f",
"Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmN...(removed for
simplification)...CiAgPC9mZTpJbnZvaWNlTGluZT4KPC9mZTpJbnZvaWNlPg==",
"ContentType": "text/xml"
}
],
"ResultData": [],
"ResultCode": 200
}

As we can see in the successful response example, we have three main fields:

Id - that represents the eInvoice unique identifier for the newly created document;
Content - certified DIAN UBL byte array encoded in UTF-8;
Content Type - certified DIAN UBL content type.

Most common errors:

CorrelationDocumentId
{
"IsValid": false,
"Errors": [
{
"Field": "SalesInvoiceDTO.CorrelationDocumentId",
"Code": "Duplicated",
"Description": null
}
],
"Documents": [],
"ResultData": [],
"ResultCode": 400
}

In this example, we have a "CorrelationDocumentId" error. The correlation document Id is a unique field used to avoid the generation of the same
invoice twice.

If you get this error, you'll just have to update the CorrelationDocumentId field in your request body to an unused value.

Saphety Level, Trusted Services