Contents

Series management

Use this service to create and manage issuing series for certified software SaphetyDoc(DOC+).
A valid serie configutation must exist for issuing invoices.

Serie properties

A serie represents a numbering sequence rule for invoices.
A serie is defined by the following properties:

  • Id
    System Id (integer). This Id is used to identity the serie, ex: to to get the serie using service /api/EntityCertifiedInformation/serie/{id}

  • EntityCode
    The entity code that the series belongs to. (Typically <country code + VAT number> ex: PT507957547)

  • Name
    The serie name. This name is to be used when calling the service processLegalInvoice in the series identification: /invoice/@serie (Invoice.Serie)
    The name also acts as a key for the serie. A serie can be retrived by its name using the service /api/EntityCertifiedInformation/documentRangeDefinition/byName

  • IsActive
    Boolean indicator. Must be true for the serie to be used.

  • LastValue
    Last value that can be issued when a range is defined (ex: 99999)

  • LastHash
    Last invoice hash generated in this series (Base64)

  • DocumentType
    One of the following: INVOICE, DEBIT_NOTE, CREDIT_NOTE, DESPATCH_ADVICE, SIMPLIFIED_INVOICE, INVOICE_RECEIPT, WAYBILL

  • InternalCode
    Fixed value: Prefix decorator for invoice number generation (ex: FT-SRV)

  • Serie
    Fixed value: Decorator for the invoice number (ex: 2021)

  • StartValue
    When in a range, the range first value (interger)

  • NumberingLength
    Length mask for the invoice number (ex: for length of 6 the generated number will be: 000097)

  • EndDate
    After this date the series will not longer be valid and no invoices will be issued

  • EndValue
    When in a Range serie, the range end value (interger)

  • DocumentRangeType
    One of the following: Range, TimeLimited, Ilimited

  • DocumentIssuingMode
    One of the following: Paper, Electronic

  • TechKey
    Returned by the Tax Authority (Autoridade tributária e aduaneira)

  • CreationDate
    System creation date

  • ActivationDate
    Before this date the series is not valid and no invoices can be issued.

  • LastDocumentDate
    Invoice Date (document date) of last issued invoices of this series.

  • Finality
    One of the Following: ~~Edition~~, Integration (Use always Integration, Edition is deprecated)

  • SelfBillingSupplierCode
    Used for issuing self-invoices on behalf of supplier (Typically <country code + VAT number> ex: PT507957547).

Get a token

Check more detail how to get a token in Services overview

# Set Environment
#Integration
server_base_adress = "doc-server-int.saphety.com/Doc.WebApi.Services"
#Quality
#server_base_adress = "doc-server-qa.saphety.com/Doc.WebApi.Services"
#Production
#server_base_adress = "doc-server.saphety.com/Doc.WebApi.Services"

#Set authorization data
#username = 'username'
#password = 'request_password'

username = 'user_api_doc'
password = 'request_password'

## Get a JWT token from your username and password
import requests
import json

service_url = "https://" + server_base_adress + "/api/Account/token"

# 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)
# Serializethe response
json_response = json.loads(response.text)
# Your token is at:
token = json_response["Data"];
print ('Your authorization token:' + token)

Your authorization token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI1NDM5NSIsInVuaXF1ZV9uYW1lIjoidXNlcl9hcGlfZG9jIiwic2Vzc2lvbl9pZCI6IjE1Mjg2M2I4LWI2NDQtNGJjYy04NzJhLTlmOTBiMDM3MmFkZSIsInN5c3RlbV9hZG1pbiI6IkZhbHNlIiwiZ2xvYl9lZGl0IjoiRmFsc2UiLCJleHRlcm5hbF91c2VybmFtZSI6InVzZXJfYXBpX2RvYyIsImV4dGVybmFsX3N5c3RlbV9hdWRpZW5jZSI6Imh0dHBzOi8vd3d3LnNhcGhldHktaW50LmNvbS9Eb2NTZXJ2ZXIiLCJuYmYiOjE2MjA4MzA4MTMsImV4cCI6MTYyMDg4MTgxMywiaWF0IjoxNjIwODMwNzUzLCJpc3MiOiJodHRwczovL3d3dy5zYXBoZXR5LmNvbS8iLCJhdWQiOiJodHRwczovL3d3dy5zYXBoZXR5LWludC5jb20vRG9jU2VydmVyIn0.aPEFRuW4XITjc25Ijm5GEcyd5BThg395AayRxrYCsU8

List available series

Get a list of available series for a given company.
This service has a paginable data return. Check more on paginable services on Services overview
It is required to specify the company to list the series for.

About the restriction criteria

Specify the company code in the service RestrictionCriteria.Code
You can specify the following restriction creteria:

  • Code

  • Name

  • IsActive

RestrictionCriteria.Name RestrictionCriteria.IsActive (boolean indicating if the series is active or inactive)

service_url = "https://" + server_base_adress + "/api/EntityCertifiedInformation/documentRangeDefinition/search"

# Search criteria data goes in payload as json
payload = {
  'RestrictionCriteria': {
    'Code': "PT560333331", # The company code that youwant to list the series for
    'Name': '',
    'IsActive': True
  },
  'PageNumber': 0,
  'RowsPerPage': 20
}
# Payload goes in json, serialize the payloal object to json
request_data=json.dumps(payload)
# Indicate in header the authorization token
headers = {
    'content-type': 'application/json',
     'Authorization': 'bearer ' + token
    }
# POST request to get a token
response = requests.request("POST", service_url, data=request_data, headers=headers)
print (response)
# Serializethe response
json_response = json.loads(response.text)
print(json_response)

<Response [200]>
{'CorrelationId': '057838d1-d744-4aae-82f7-d84652035e2e', 'IsValid': True, 'Errors': [], 'Data': [{'Id': 177542, 'EntityCode': 'PT560333331', 'Name': 'SerieName', 'IsActive': True, 'LastValue': None, 'LastHash': None, 'DocumentType': 'INVOICE', 'InternalCode': 'INTCode', 'Serie': '2021', 'StartValue': 1, 'NumberingLength': 6, 'EndDate': None, 'EndValue': 999999, 'DocumentRangeType': 'Range', 'DocumentIssuingMode': 'Electronic', 'TechKey': None, 'CreationDate': '2021-05-12T14:48:18.588976', 'ActivationDate': None, 'LastDocumentDate': None, 'Finality': 'Integration', 'SelfBillingSupplierCode': None}]}

Activate and Deactivate a serie

To activate and deactive a serie use the service: /api/EntityCertifiedInformation/documentRangeDefinition/activate/{id}
To deactivate and deactive a serie use the service: /api//EntityCertifiedInformation/documentRangeDefinition/deactivate/{id}
This service uses a PUT method

  • Id
    Id is the system identification for the series

# Get the serie Id from the previous serach service
serieIdToActivate = 177542 
# Build the url
service_url = "https://" + server_base_adress + "/api/EntityCertifiedInformation/documentRangeDefinition/activate" + "/" + str(serieIdToActivate)
# Indicate in header the authorization token
headers = {
    'content-type': 'application/json',
     'Authorization': 'bearer ' + token
    }
# Use PUT to send the request
response = requests.request("PUT", service_url, data=None, headers=headers)
print (response)
# Serializethe response
json_response = json.loads(response.text)
print(json_response)

<Response [200]>
{'CorrelationId': 'a5e7082c-06a5-4389-b3b1-00f0d8ba419d', 'IsValid': True, 'Errors': [], 'Data': {}}

Create a Serie

Use the service POST /api/EntityCertifiedInformation/documentRangeDefinition to create a serie
The serie information passed is the same as defined in section Serie properties
The serie Id is generated by the system.

# Build the url
service_url = "https://" + server_base_adress + "/api//EntityCertifiedInformation/documentRangeDefinition"
# Indicate in header the authorization token
headers = {
    'content-type': 'application/json',
     'Authorization': 'bearer ' + token
    }
serie_to_create = {    
    'IsActive': True,
    'EntityCode': 'PT560333331',     
    'Name': 'SerieName',    
    'DocumentType': 'INVOICE',    
    'DocumentIssuingMode': 'Electronic',    
    'Finality': 'Integration',    
    'InternalCode': 'INTCode',    
    'Serie': '2021',    
    'StartValue': 1,    
    'NumberingLength': 6,   
    'DocumentRangeType': 'Range',    
    'EndValue': '999999'
}
request_data=json.dumps(serie_to_create)
# Use POST to send the request
response = requests.request("POST", service_url, data=request_data, headers=headers)
print (response)
# Serializethe response
json_response = json.loads(response.text)
print(json_response)

<Response [200]>
{'CorrelationId': '416967a1-acfb-4ba8-b48a-9c817a8e5da5', 'IsValid': True, 'Errors': [], 'Data': {}}

Get a series by name

Check a serie existance using the service GET /api/EntityCertifiedInformation/documentRangeDefinition/byName?name=serie_name
The serie name is passed in the query string

# The serie name to get
serie_name = 'SerieName'
# Build the url
service_url = "https://" + server_base_adress + "/api/EntityCertifiedInformation/documentRangeDefinition/byName?name=" + serie_name;
# Indicate in header the authorization token
headers = {
    'content-type': 'application/json',
     'Authorization': 'bearer ' + token
    }
# GET to send the request
response = requests.request("GET", service_url, headers=headers)
print (response)
# Serializethe response
json_response = json.loads(response.text)
print(json_response)

<Response [200]>
{'CorrelationId': 'df6b06c7-e5f0-4565-9f6f-d72740d04ada', 'IsValid': True, 'Errors': [], 'Data': {'Id': 177542, 'EntityCode': 'PT560333331', 'Name': 'SerieName', 'IsActive': True, 'LastValue': None, 'LastHash': None, 'DocumentType': 'INVOICE', 'InternalCode': 'INTCode', 'Serie': '2021', 'StartValue': 1, 'NumberingLength': 6, 'EndDate': None, 'EndValue': 999999, 'DocumentRangeType': 'Range', 'DocumentIssuingMode': 'Electronic', 'TechKey': None, 'CreationDate': '2021-05-12T14:48:18.588976', 'ActivationDate': None, 'LastDocumentDate': None, 'Finality': 'Integration', 'SelfBillingSupplierCode': None}}
API Services SAF-T reports