Skip to content

Latest commit

 

History

History
218 lines (181 loc) · 11.6 KB

README.md

File metadata and controls

218 lines (181 loc) · 11.6 KB
Raw

swagger-client

Warning / Avvertenza

Questa è una API sperimentale che (probabilmente) subirà dei cambiamenti mano a mano che il servizio di messaggistica IO si evolverà.
This is an experimental API that is (most probably) going to change as we evolve the IO Messaging service.

Introduction

This is the documentation of the Digital Citizenship API. This API enables Public Administration services to integrate with the Digital Citizenship platform of the Italian Government. The platform enables services to communicate with Italian Citizens via the IO app.

How to get an API key

To get access to this API, you'll need to register on the Digital Citizenship Developer Portal. After the registration step, you have to click on the button that says subscribe to the digital citizenship api to receive the API key that you will use to authenticate the API calls. You will also receive an email with further instructions, including a fake Fiscal Code that you will be able to use to send test messages. Messages sent to the fake Fiscal Code will be notified to the email address used during the registration process on the developer portal.

Messages

What is a message

Messages are the primary form of communication enabled by the Digital Citizenship APIs. Messages are personal communications directed to a specific citizen. You will not be able to use this API to broadcast a message to a group of citizens, you will have to compose e specific, personalized message to each citizen you want to communicate to. The recipient of the message (i.e. a citizen) is identified trough his Fiscal Code. ## Message format A message is conceptually very similar to an email and, in its simplest form, is composed of the following attributes:

  • A required subject: a short description of the topic.
  • A required markdown body: a Markdown representation of the body (see below on what Markdown tags are allowed).
  • An optional payment_data: in case the message is a payment request, the payment data will enable the recipient to pay the requested amount via PagoPA.
  • An optional due_date: a due date that let the recipient add a reminder when receiving the message. The format for all dates is ISO8601 with time information and UTC timezone (ie. "2018-10-13T00:00:00.000Z").

Allowed Markdown formatting

Not all Markdown formatting is currently available. Currently you can use the following formatting:

  • Headings
  • Text stylings (bold, italic, etc...)
  • Lists (bullet and numbered)

Process for sending a message to a citizen

Not every citizen will be interested in what you have to say and not every citizen you want to communicate to will be registered on the Digital Citizenship platform. For this reason, before sending a message you will have to check whether the recipient is registered on the platform and that he has not yet opted out from receiving messages from you. The process for sending a message is made of 3 steps:

  1. Call getProfile: if the profile does not exist or the recipient has opted-out from your service, you cannot send the message and you must stop here.
  2. Call submitMessageforUser to submit a new message.
  3. (optional) Call getMessage to check whether the message has been notified to the recipient.

This Python package is automatically generated by the Swagger Codegen project:

  • API version: 1.0.0
  • Package version: 1.0.0
  • Build package: io.swagger.codegen.v3.generators.python.PythonClientCodegen For more information, please visit https://forum.italia.it/c/progetto-io

Requirements.

Python 2.7 and 3.4+

Installation & Usage

pip install

If the python package is hosted on Github, you can install directly from Github

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import swagger_client

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import swagger_client

Getting Started

Please follow the installation procedure and then run the following:

from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# Configure API key authorization: SubscriptionKey
configuration = swagger_client.Configuration()
configuration.api_key['Ocp-Apim-Subscription-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['Ocp-Apim-Subscription-Key'] = 'Bearer'

# create an instance of the API class
api_instance = swagger_client.PublicApi(swagger_client.ApiClient(configuration))
fiscal_code = 'fiscal_code_example' # str | The fiscal code of the user, all upper case.
id = 'id_example' # str | The ID of the message.

try:
    # Get Message
    api_response = api_instance.get_message(fiscal_code, id)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PublicApi->get_message: %s\n" % e)

# Configure API key authorization: SubscriptionKey
configuration = swagger_client.Configuration()
configuration.api_key['Ocp-Apim-Subscription-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['Ocp-Apim-Subscription-Key'] = 'Bearer'

# create an instance of the API class
api_instance = swagger_client.PublicApi(swagger_client.ApiClient(configuration))
fiscal_code = 'fiscal_code_example' # str | The fiscal code of the user, all upper case.

try:
    # Get a User Profile
    api_response = api_instance.get_profile(fiscal_code)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PublicApi->get_profile: %s\n" % e)

# Configure API key authorization: SubscriptionKey
configuration = swagger_client.Configuration()
configuration.api_key['Ocp-Apim-Subscription-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['Ocp-Apim-Subscription-Key'] = 'Bearer'

# create an instance of the API class
api_instance = swagger_client.PublicApi(swagger_client.ApiClient(configuration))
fiscal_code = 'fiscal_code_example' # str | The fiscal code of the user, all upper case.
body = swagger_client.NewMessage() # NewMessage |  (optional)

try:
    # Submit a message
    api_response = api_instance.submit_messagefor_user(fiscal_code, body=body)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling PublicApi->submit_messagefor_user: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://api.cd.italia.it/api/v1

Class Method HTTP request Description
PublicApi get_message GET /messages/{fiscal_code}/{id} Get Message
PublicApi get_profile GET /profiles/{fiscal_code} Get a User Profile
PublicApi submit_messagefor_user POST /messages/{fiscal_code} Submit a message
RestrictedApi get_info GET /info API test endpoint
RestrictedApi get_message GET /messages/{fiscal_code}/{id} Get Message
RestrictedApi get_messages_by_user GET /messages/{fiscal_code} Get messages by user
RestrictedApi get_service GET /services/{service_id} Get Service
RestrictedApi get_services_by_recipient GET /profiles/{recipient}/sender-services Get Services by recipient
RestrictedApi get_visible_services GET /services Get all visibile services.
RestrictedApi upsert_profile POST /profiles/{fiscal_code} Updates a User Profile

Documentation For Models

Documentation For Authorization

SubscriptionKey

  • Type: API key
  • API key parameter name: Ocp-Apim-Subscription-Key
  • Location: HTTP header

Author