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.
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.
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 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").
Not all Markdown formatting is currently available. Currently you can use the following formatting:
- Headings
- Text stylings (bold, italic, etc...)
- Lists (bullet and numbered)
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:
- 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.
- Call submitMessageforUser to submit a new message.
- (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
Python 2.7 and 3.4+
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
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
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)
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 |
- BlockedInboxOrChannel
- BlockedInboxOrChannels
- CIDR
- CreatedMessageWithContent
- CreatedMessageWithoutContent
- DepartmentName
- EmailAddress
- ExtendedProfile
- FiscalCode
- HttpStatusCode
- HttpsUrl
- InlineResponse200
- InlineResponse2001
- InlineResponse2002
- InlineResponse201
- IsInboxEnabled
- IsWebhookEnabled
- LimitedProfile
- MaxAllowedPaymentAmount
- MessageBodyMarkdown
- MessageContent
- MessageContentPaymentData
- MessageResponseNotificationStatus
- MessageResponseWithContent
- MessageResponseWithContentMessage
- MessageResponseWithoutContent
- MessageResponseWithoutContentMessage
- MessageResponseWithoutContentNotification
- MessageStatus
- MessageStatusValue
- MessageSubject
- NewMessage
- NewMessageContent
- NewMessageDefaultAddresses
- NotificationChannel
- NotificationChannelStatus
- NotificationChannelStatusValue
- OrganizationFiscalCode
- OrganizationName
- PaginationResponse
- PaymentAmount
- PaymentData
- PaymentNoticeNumber
- PreferredLanguage
- PreferredLanguages
- ProblemJson
- SenderMetadata
- Service
- ServiceId
- ServiceName
- ServicePublic
- ServiceTuple
- TimeToLiveSeconds
- Timestamp
- Type: API key
- API key parameter name: Ocp-Apim-Subscription-Key
- Location: HTTP header