Receive electronic invoices

Receive electronic invoices#

This endpoint is used to get the document content from the system regardless of the status.

Endpoint steps#

Get a token from your credentials by calling the endpoint Account/getToken;
Is necessary, perform the document search to get the document id;
To get the xml content send the request to the endpoint InboundFinancialDocument/pullDocument/{documentId}, where the id is the document id retrieve from the document search endpoint.
- Example: GET /api/InboundFinancialDocument/pullDocument/b50d6a51-26c4-4060-b45b-ed4b1f104cc7

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 endpoint called */
}

Endpoint Server Base URL#

# Test Environment
server_base_adress = "dcn-solution-qa.saphety.com/Dcn.Business.WebApi"

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

1. Get a token (Account/getToken)#

Get a token from your account credentials using endpoint api/Account/getToken
Check here how to obtain an authentication token.

2. Search document to get the document id (InboundFinancialDocument/search)#

Search document to get the document id using endpoint api/InboundFinancialDocument/search
Check here how to obtain the intended document id.

3. Get the document through pulldocument endpoint (InboundFinancialDocument/pullDocument/{documentId})#

This endpoint will get the CIUS PT content in XML format from the system and set the document to the status “SENT”

3.1 Request structure#

In the url you need to supply this parameter:

documentId#

Description: id associated with the legal document.
Required: Yes
Type: string
Example: “f1baf2fa-98d2-4284-9233-bc6c18a51087”

3.2 Request example#

# SIN endpoint url to get the document content
documentId = "fc5e547d-8537-4e05-97d5-1159c62efd6f"
service_url = "https://" + server_base_adress + "/api/InboundFinancialDocument/pullDocument/" + documentId
print (service_url)

headers = {
    'Authorization': 'bearer ' + token
}
response = requests.request("GET", service_url, headers=headers)
print(response.text)

https://dcn-solution-qa.saphety.com/Dcn.Business.WebApi/api/InboundFinancialDocument/pullDocument/fc5e547d-8537-4e05-97d5-1159c62efd6f

3.3 Response Example#

<?xml version="1.0" encoding="utf-8"?>
<ubl:Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:feap.gov.pt:CIUS-PT:2.1.1</cbc:CustomizationID>
  <cbc:ID>FT SN2402/ap</cbc:ID>
  <cbc:IssueDate>2024-09-20</cbc:IssueDate>
  <cbc:DueDate>2024-10-19</cbc:DueDate>
  <cbc:InvoiceTypeCode>FT</cbc:InvoiceTypeCode>
  <cbc:Note>#NUMBER@ATCERTIFIEDPROGRAM#2330/AT#</cbc:Note>
  <cbc:Note>#HASHCODE@ATCERTIFIEDPROGRAM#YLex#</cbc:Note>
  <cbc:Note>#DESCRIPTION@ATCERTIFIEDPROGRAM#YLex-Processado por programa certificado nº2330/AT#</cbc:Note>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cbc:AccountingCost>N. Compromisso 10</cbc:AccountingCost>
  ....
</ubl:Invoice>