Check invoice status in archive (electronic or PDF)

Check invoice status in archive (electronic or PDF)#

Use this service to check an invoice (electronic or PDF) status in archive for your processed document.

Service steps#

Get a token from your credentials by calling the service Account/getToken;
Get an invoice status in archive calling the service OutboundFinancialDocument/{documentId};

Response structure from server#

When a request is well formed and the authentication data is correct the system responds with a message envelope as follows:

{
	"CorrelationId": "<GUID>", /* for correlation purposes */
	"IsValid": true,           /* false in case of erros */
	"Errors": [],              /* if empty is a good signal */
	"Data": "<Service Response Data>"   /* the data retuned ex: token, invoice status, dependent on the service called */
}

1. Get a token (Account/getToken)#

Credentials have be given to you, according to your registration at SANDBOX or Saphety Invoice Network:

For Test purposes, the user and password defined at SANDBOX registration
or
For Production, the user and password defined at Saphety Invoice Network registration

Use those credentials to get a token at:

https://<ServerBaseAddress>/api/Account/getToken

# SANDBOX - Test Environment
server_base_adress = "dcn-solution.saphety.com/Dcn.Sandbox.WebApi"

# Saphety Invoice Network - Production Environment
#server_base_adress = "dcn-solution.saphety.com/Dcn.Business.WebApi"

import requests
import json

# SIN account service url
service_url = "https://" + server_base_adress + "/api/Account/getToken"

# the username and password you registerd in SIN
username = 'sin_api_documentation_user@saphety.com'
password = 'request_password'

# auhtentication data goes in payload as json
payload = {
      'Username': username,
      'Password': password
}
# payload goes in json, serialize the payloal object to json
request_data=json.dumps(payload)
# indicate in header that payload is json
headers = {
    'content-type': 'application/json'
    }
# POST request to get a token
response = requests.request("POST", service_url, data=request_data, headers=headers)

* Note: the credentials (user and password) in this documentation were created by Saphety and can only be used in the SANDBOX environment. For tests we recommend that you use the credentials you obtained when registering with the SANDBOX.

# formating the response to json for visualization purposes only
json_response = json.loads(response.text)
print(json.dumps(json_response, indent=4))

{
    "CorrelationId": "640d50fc-8b54-429c-90d0-883c9229c581",
    "IsValid": true,
    "Errors": [],
    "Data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJzaW1hby5nb2RpbmhvQHNhcGhldHkuY29tIiwidW5pcXVlX25hbWUiOiJTaW3Do28gR29kaW5obyIsInN5c3RlbV9hZG1pbiI6IkZhbHNlIiwic2Vzc2lvbl9pZCI6ImYxODhkMjNlLTdiZTUtNDVmMy1iYzBkLWIxMWU0NWRhNWY1ZSIsImNwIjoic2ltYW8uZ29kaW5ob0BzYXBoZXR5LmNvbSIsInJsIjoiRGV2ZWxvcGVyIiwibmJmIjoxNjM2NjQ5MDYyLCJleHAiOjE2NDI2NDkwMDIsImlhdCI6MTYzNjY0OTAwMiwiaXNzIjoiaHR0cHM6Ly93d3cuc2FwaGV0eS5jb20vIiwiYXVkIjoiaHR0cHM6Ly93d3cuc2FwaGV0eS5jb20vRGNuU2FuZGJveCJ9.F1dusIPLNP7PoOaaAM1b1KwB8xy8EI9-pzXOPOAaT2k"
}

# your token is at:
token = json_response["Data"];
print (token)

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJzaW1hby5nb2RpbmhvQHNhcGhldHkuY29tIiwidW5pcXVlX25hbWUiOiJTaW3Do28gR29kaW5obyIsInN5c3RlbV9hZG1pbiI6IkZhbHNlIiwic2Vzc2lvbl9pZCI6ImYxODhkMjNlLTdiZTUtNDVmMy1iYzBkLWIxMWU0NWRhNWY1ZSIsImNwIjoic2ltYW8uZ29kaW5ob0BzYXBoZXR5LmNvbSIsInJsIjoiRGV2ZWxvcGVyIiwibmJmIjoxNjM2NjQ5MDYyLCJleHAiOjE2NDI2NDkwMDIsImlhdCI6MTYzNjY0OTAwMiwiaXNzIjoiaHR0cHM6Ly93d3cuc2FwaGV0eS5jb20vIiwiYXVkIjoiaHR0cHM6Ly93d3cuc2FwaGV0eS5jb20vRGNuU2FuZGJveCJ9.F1dusIPLNP7PoOaaAM1b1KwB8xy8EI9-pzXOPOAaT2k

2. Get a Document status by DocumentId (OutboundFinancialDocument/{documentId})#

Build the service endpoint url#

In the service url you need to supply the outboundfinancialdocumentId received

https://<ServerBaseUrl>/OutboundFinancialDocument/<OutboundFinancialDocumentId>

# SIN service url for retrieving inforfation on invoice previously sent
service_url = """{ServerBaseUrl}/api/OutboundFinancialDocument/{OutboundFinancialDocumentId}""".format(
    ServerBaseUrl=server_base_adress,
    OutboundFinancialDocumentId="fc5e547d-8537-4e05-97d5-1159c62efd6f"
)
service_url = "https://" + service_url
print (service_url)

https://dcn-solution-int.saphety.com/Dcn.Sandbox.WebApi/api/OutboundFinancialDocument/fc5e547d-8537-4e05-97d5-1159c62efd6f

Call the service to get the document#

You will call the service endpoint url

# build the request
headers = {
    'Authorization': 'bearer ' + token
    }
# POST request to send the invoice
response = requests.request("GET", service_url, headers=headers)

# formating the response to json for visualization purposes only
json_response = json.loads(response.text)
print(json.dumps(json_response["Data"], indent=4))

{
    "Id": "fc5e547d-8537-4e05-97d5-1159c62efd6f",
    "VirtualOperatorCode": null,
    "CompanyIntlVatCode": "PT507641230",
    "DocumentType": "INVOICE",
    "DocumentDate": "2020-12-31 00:00:00",
    "DocumentNumber": "FTSCN 2020/00000346",
    "ReceiverIntlVatCode": "PT507957547",
    "ReceiverName": "SAPHETY LEVEL - TRUSTED SERVICES, S.A",
    "DocumentStatus": "Final",
    "DocumentSource": "Integration",
    "DocumentLink": "",
    "DocumentTotal": 11.07,
    "CurrencyCode": "EUR",
    "NotificationStatus": "Delivered",
    "IntegrationStatus": "Received",
    "IntegrationDate": "2021-01-03 00:00:00",
    "LastUpdateDate": "2021-01-03 00:00:00",
    "AuthorId": "442ad0fe-74e8-41c7-9d3f-fd009534b26c",
    "Errors": null,
    "CreationDate": "2021-01-01 00:00:00"
}

There are 2 types of documents in the archive:

Electronic invoice
PDF invoice

To query the status of a document in archive, it is necessary to consider 2 concepts of status:

Integration status - indicates the current integration status that a document has in archive
Notification status - indicates the current email notification status that a document has in archive

The integration status of a document in archive is returned at “IntegrationStatus” parameter, see the possible values returned:

NotIntegrated - document not sent to receiver entity for integration
Not_Sent - document not sent for receiver entity
Error - document with errors, not sent to receiver entity for integration
Sent - document sent to receiver entity for integration
Received - document sent to receiver entity for integration, receiver entity has confirmed its reception
Rejected - document sent to receiver entity for integration, receiver entity is rejecting it
Paid - document sent to receiver entity for integration, receiver entity is confirming it as paid

The notification status of a document in archive is returned at “NotificationStatus” parameter, see the possible values returned:

NoEmails - document without any email notification
Sent - document with at least one email notification sent
Delivered - document with at least one email notification delivered
Read - document with at least one email notification read
Error - document with at all email notifications in error

[Important note_1] If an electronic invoice is sent to an entity outside Saphety network, it will not be sent to receiver entity for integration, so the integration status will always be “NotIntegrated”.

In this scenario the electronic invoice may have also a notification status (Sent, Delivered, Read or Error) if the CIUS-PT XML has the tag BT-49 filled in with the receiver entity’s email address (ex: <cbc:EndpointID schemeID=”EM”>eee@hh.pt</cbc:EndpointID>), otherwise the document will have integration status as “NotIntegrated” and notification status as “NoEmails”.

[Important note_2] If an electronic invoice is sent to a receiver entity of a network with interoperability, but the issuer does not have an approved connection to this network, it will not be sent to receiver entity for integration, so the integration status will always be “NotIntegrated”.

In this scenario the electronic invoice may have also a notification status (Sent, Delivered, Read or Error) if the CIUS-PT XML has the tag BT-49 filled in with the receiver entity’s email address (ex: <cbc:EndpointID schemeID=”EM”>eee@hh.pt</cbc:EndpointID>), otherwise the document will have integration status as “NotIntegrated” and notification status as “NoEmails”.

[Important note_3] A PDF invoice has always the integration status as “NotIntegrated”.

If the PDF invoice was signed, stored and sent by email to the receiver entity, the notification status will return the status “Sent”, “Delivered”, “Read” or “Error”.

If the PDF invoice was signed, stored and not sent by email to the receiver entity, the notification status will return the status “NoEmails”.

integration_status = json_response["Data"]["IntegrationStatus"]

#integration status (Sent, Received,...)

if integration_status == "Sent":
    print ("Sent: Your invoice has been sucessfully processed and sent to your customer.")
if integration_status == "Received":
    print ("Received: Your invoice has been received by your customer.")
else:
    print("Your invoice integration status: " + integration_status);

#print(json.dumps(json_response, indent=4))

Received: Your invoice has been received by your customer.