Search for electronic invoices#

This endpoint is used to search for all received document in different statuses. There are multiple search criteria available that retrieves several document informations, including the document id, necessary to get the physical document.

Endpoint steps#

  1. Get a token from your credentials by calling the endpoint Account/getToken;

  2. Search for invoices through the endpoint (POST) InboundFinancialDocument/search, by specifying the necessary criteria;

  3. Once the request has finished successfully you should store the document id in case you need to obtain the document content in the legal format.

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 for electronic invoices (POST InboundFinancialDocument/search)#

Use this endpoint to get the list of documents persisted in the system.

2.1 Request body structure#

Body can’t be empty and “RestrictionCriteria” is required on payload

{
  "RestrictionCriteria": {
    "CompanyIntlVatCodes": [
      "string"
    ],
    "DocumentIds": [
      "string"
    ],
    "DocumentsType": [
      "string"
    ],
    "DocumentDateStart": "string",
    "DocumentDateEnd": "string",
    "DocumentNumber": "string",
    "DocumentTotalMin": "string",
    "DocumentTotalMax": "string",
    "SenderIntlVatCode": "string",
    "SenderName": "string",
    "IntegrationsStatus": [
      "string"
    ],
    "IntegrationDateStart": "string",
    "IntegrationDateEnd": "string",
    "CreationDateStart": "string",
    "CreationDateEnd": "string",
    "IsDocumentBlocked": true
  },
  "OrderBy": "string",
  "OrderDescending": true,
  "PageNumber": 0,
  "RowsPerPage": 0
}

CompanyIntlVatCodes#

  • Description: Tax identification of the client/receiver entity (aka as vat Number)

  • Required: No

  • Type: string

  • Example: “PT501564432”

  • Notes: Only accepts valid vat Numbers and filled with the country Code prefix

DocumentIds#

  • Description: Id associated with the legal document

  • Required: No

  • Type: string

  • Example: “f1baf2fa-98d2-4284-9233-bc6c18a51087”

DocumentsType#

  • Description: Document type for legal documents

  • Required: No

  • Type: string

  • Allowed values: “Invoice”, “Credit_Note”, “Debit_Note”, “Invoice_Receipt”, “Simplified_Invoice”

  • Example: “Invoice”

DocumentDateStart#

  • Description: Document start date

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

DocumentDateEnd#

  • Description: Document end date

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

DocumentTotalMin#

  • Description: Document total amount payable interval start amount

  • Required: No

  • Type: string

  • Format: “0000.00”

  • Example: “13547.23”

DocumentTotalMax#

  • Description: Document total amount payable interval end amount

  • Required: No

  • Type: string

  • Format: “0000.00”

  • Example: “13547.23”

SenderIntlVatCode#

  • Description: Tax identification of the issuer/sender entity (aka as vat Number)

  • Required: No

  • Type: string

  • Example: “PT501564432”

  • Notes: Only accepts valid vat Numbers and filled with the country Code prefix

SenderName#

  • Description: Name of the issuer/sender entity

  • Required: No

  • Type: string

  • Example: “Company Name Test”

  • Notes: The name is not case sensitive

IntegrationsStatus#

  • Description: Document integration status

  • Required: No

  • Type: string

  • Allowed values: “Not_Sent”, “Sent”, “Accepted”, “Rejected”, “Paid”

  • Example: “Not_Sent”

IntegrationDateStart#

  • Description: Start date of the last integration state

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

IntegrationDateEnd#

  • Description: End date of the last integration state

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

CreationDateStart#

  • Description: Start date in which the document is created in the system

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

CreationDateEnd#

  • Description: End date in which the document is created in the system

  • Required: No

  • Type: string

  • Format: “yyyy-MM-dd”

  • Example: “2024-12-12”

IsDocumentBlocked#

  • Description: Flag to get or not the blocked documents

  • Required: No

  • Type: boolean

  • Allowed values: “true”, “false”

  • Example: true

OrderBy#

  • Description: Fields in which is possible to ordered

  • Required: No

  • Type: string

  • Allowed values: “DocumentNumber”, “DocumentDate”, “CreationDate”

  • Example: “DocumentNumber”

OrderDescending#

  • Description: Flag to define if the order by field is to be ascending or descending

  • Required: No

  • Type: boolean

  • Allowed values: “true”, “false”

  • Example: true

PageNumber#

  • Description: The number of the page to show because the list is paginated

  • Required: yes

  • Type: numeric

  • Example: 0

  • Notes: the first page is 0

RowsPerPage#

  • Description: Number of rows being retrieve per page.

  • Required: yes

  • Type: numeric

  • Example: 20

2.2 Request example#

service_url = "https://" + server_base_adress + "/api/InboundFinancialDocument/search"
print ('Endpoint url: POST ' + service_url)

#headers
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'bearer ' + token
    }
# payload as json
payload = {
    "PageNumber": 0,
    "RowsPerPage": 10,
    "RestrictionCriteria": {
        "CompanyIntlVatCodes": [
            "PT510000000"
        ]
    },
    "OrderBy": "CreationDate"
}
request_data=json.dumps(payload)

Endpoint url: POST https://dcn-solution-qa.saphety.com/Dcn.Business.WebApi/api/InboundFinancialDocument/search

2.3 Response example#

{
  "CorrelationId": "e7aeb422-dde0-4c2a-9b8c-6f9a3ae8ee95",
  "IsValid": true,
  "Errors": [],
  "Data": [
    {
      "Id": "b50d6a51-26c4-4060-b45b-ed4b1f104cc7",
      "VirtualOperatorCode": "Saphety",
      "CompanyIntlVatCode": "PT510000000",
      "DocumentType": "Invoice",
      "DocumentDate": "2024-09-20 00:00:00",
      "DocumentNumber": "FT SN2402/1002",
      "SenderIntlVatCode": "PT510000000",
      "SenderName": "Teste AP Buyer",
      "DocumentStatus": "Final",
      "DocumentSource": "Integration",
      "DocumentLink": "https://dcn-solution-int.saphety.com/IN2.ContentStorage.WebApi/api/Content?token=7gIWGuoQJTJ8QnDlA2v8KUDIaRR7ImN0SWQiOiJiNWM2YzY2Ny1lNzcwLTRjYjgtYTc3OC1iZTg1ODM5ZmI0NWYiLCJpRHQiOiIyMDI0LTEyLTIwIiwiZUR0IjoiMjAyNC0xMi0yMyIsImlCeSbm8ubWVsb0Bzb3Zvcy5jb20iLCJpVG8iOiJudW5vLm1lbG9Ac292b3MuY29tIiwicyI6IndlYiIsImFhaCI6ZmFsc2V9",
      "DocumentTotal": 167.21,
      "CurrencyCode": "EUR",
      "IntegrationStatus": "Not_Sent",
      "IntegrationDate": "2024-12-20 12:38:58",
      "LastUpdateDate": "2024-12-20 12:38:58",
      "AuthorId": "3fc4d83b-4970-4dcd-8fd6-6fe28786f759",
      "Errors": null,
      "CreationDate": "2024-12-20 12:36:13",
      "IsDocumentBlocked": false
    },
    ...
  ]
}