Ufficio Postale (1.0.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

This web service allows the delivery of postal products like Raccomandate, Telegrammi, Posta Prioritaria through Poste Italiane

Create a new mail with a POST request
Check the prices and confirm it with a PATCH, or use autoconfirm: true
Receive the status updates of your mail by providing a callback url

Note: There are some limitations regarding the size of a PDF document. Please read the 'document' field in the description of the endpoint that you want to use.

Error handling

When a sending error occurs, the response will include a message and a data.wrong_fields: []: each element of wrong_fields is a string which indicates where the error was generated from. This makes it very easy to integrate in your front-end form, where you can highlight the wrong entries

Testing

When using the Sandbox environment, you will receive update callbacks a short time after creating the request with placeholder content. It is also possible, for some products, to force the execution of the callback in the sandbox environment.

First time here? Generate a new access token

Ufficio Postale

Get pricings

Returns a list of prices for various kinds of services

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/pricing/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

OK

{"data": [{"tipologia": "raccomandata",
"prodotto": "raccomandata",
"descrizione": "Raccomandata",
"riferimento_prezzo": "pagina",
"accetta_allegati": 1,
"attivo": 1,
"tariffe": [{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 0,
"a": 1,
"tariffa_postale": 3.4,
"zona": 0,
"stampa": 0.1,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 2,
"a": 2,
"tariffa_postale": 3.4,
"zona": 0,
"stampa": 0.2,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 3,
"a": 3,
"tariffa_postale": 3.4,
"zona": 0,
"stampa": 0.3,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 4,
"a": 5,
"tariffa_postale": 4.55,
"zona": 0,
"stampa": 0.3,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 6,
"a": 9,
"tariffa_postale": 4.55,
"zona": 0,
"stampa": 0.35,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 10,
"a": 13,
"tariffa_postale": 4.55,
"zona": 0,
"stampa": 0.4,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 14,
"a": 18,
"tariffa_postale": 4.55,
"zona": 0,
"stampa": 0.45,
"imbustamento": 0
},
{"iva_tariffa_postale": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "pagine",
"da": 19,
"a": 10000000,
"tariffa_postale": 4.55,
"zona": 0,
"stampa": 0.45,
"imbustamento": 0
}
],
"options": {"StampaColori": {"nome_option": "Stampa Colori",
"nome_option_invio": "StampaColori",
"prezzo_option": 0.8,
"iva": 0,
"attivo": 1
},
"RicevutaRitorno": {"nome_option": "Ricevuta di Ritorno",
"nome_option_invio": "RicevutaRitorno",
"prezzo_option": 0.8,
"iva": 0,
"attivo": 1
},
"FronteRetro": {"nome_option": "Stampa Fronte/Retro",
"nome_option_invio": "FronteRetro",
"prezzo_option": 0.3,
"iva": 0,
"attivo": 1
}
},
"username": null
}
],
"success": true,
"message": "",
"error": null
}

Get pricing for a specific service

Returns pricing information for the specified postal service.

Authorizations:

bearerAuth

path Parameters

service

required

string

Default: "<string>"

Enum: "atti_giudiziari" "raccomandate" "telegrammi" "ordinarie" "ordinarie" "prioritarie" "telegrammi_estero" "raccomandate_estero" "ordinarie_estero" "prioritarie_estero"

The specific postal service to get pricing for.

Responses

Response Schema: application/json

	object (PricingData)
success	boolean Indicates whether the request was successful
message	string Additional information or status message
error	object or null Error details, if any. Null if the request was successful

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/pricing/%7Bservice%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

Example

{"data": {"tipologia": "telegramma",
"prodotto": "telegramma_estero",
"descrizione": "Telegramma_estero",
"riferimento_prezzo": "parole",
"accetta_allegati": 1,
"attivo": 1,
"tariffe": [{"iva_tariffa_postale": 0,
"iva_imbustamento": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "parole",
"zona": "A",
"tariffa_postale": 0.32,
"stampa": 0.32,
"imbustamento": 0.12,
"prezzo_fisso": 7.23,
"iva_prezzo_fisso": 0
},
{"iva_tariffa_postale": 0,
"iva_imbustamento": 0,
"iva_stampa_imbustamento": 0,
"tipologia": "parole",
"zona": "G",
"tariffa_postale": 0.77,
"stampa": 0.32,
"imbustamento": 0.12
}
]
},
"success": true,
"message": "",
"error": null
}

Get countries list

Returns a list of countries with available postal services. You can optionally filter by service type by adding a path parameter. Available service types are: telegramma_estero, raccomandata_estero, ordinaria_estero, prioritaria_estero.

Example: /nazioni/telegramma_estero

This will return only countries where the specified service is available, including the pricing zone.

Zone information:

For raccomandata_estero, ordinaria_estero, and prioritaria_estero: Zones range from 1 to 3.
For telegramma_estero: Zones range from A to H.

The zone determines the pricing tier for each country and service. For detailed pricing information, please refer to the /pricing/ endpoint.

Authorizations:

bearerAuth

path Parameters

service

required

string

Default: "<string>"

Enum: "telegramma_estero" "raccomandata_estero" "ordinaria_estero" "prioritaria_estero"

Optional. Filter countries by specific postal service.

Responses

Response Schema: application/json

	object
success	boolean Indicates if the request was successful
message	string Additional information about the response
error	object or null Error details, if any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/nazioni/%7Bservice%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

Example

{"data": {"AL": {"nome": "Albania",
"name": "Albania",
"zona": 1
},
"DZ": {"nome": "Algeria",
"name": "Algeria",
"zona": 1
},
"AD": {"nome": "Andorra",
"name": "Andorra",
"zona": 1
},
"AO": {"nome": "Angola",
"name": "Angola",
"zona": 2
}
},
"success": true,
"message": "",
"error": null
}

Get full countries list

Returns a list of all countries with their available postal services.

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	object or null

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/nazioni/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": {"AL": {"nome": "Albania",
"name": "Albania",
"products": {"telegramma_estero": true,
"raccomandata_estero": true,
"ordinaria_estero": true,
"prioritaria_estero": true
}
},
"DZ": {"nome": "Algeria",
"name": "Algeria",
"products": {"telegramma_estero": true,
"raccomandata_estero": true,
"ordinaria_estero": true,
"prioritaria_estero": true
}
},
"IC": {"nome": "Isole Canarie",
"name": "Canary Islands",
"products": {"telegramma_estero": true
}
},
"CC": {"nome": "Isole Cocos",
"name": "Cocos (Keeling) Islands",
"products": {"telegramma_estero": true
}
}
},
"success": true,
"message": "",
"error": null
}

Get all cover configurations

Retrieves a list of all cover configurations created

Authorizations:

bearerAuth

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/covers/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"header": "text header",
"mittente": "yourbase64",
"dettaglioMittente": "yourbase64",
"body": "yourbase64",
"footer": "text footer",
"dettaglioLettera": "text",
"creation_timestamp": 1725895605,
"update_timestamp": 1725896412,
"status": "READY",
"error": "",
"id": "66df13b5e19ee05eb800234a"
},
{"header": "yourbase64",
"mittente": "yourbase64",
"dettaglioMittente": "yourbase64",
"body": "yourbase64",
"footer": "base64",
"dettaglioLettera": "base64",
"creation_timestamp": 1728658590,
"update_timestamp": 1728658590,
"status": "ERROR CREATE",
"error": "\"Errore in creaCover: Code: a:InternalServiceFault, String: Error in deserializing body of request message for operation 'CreaCover'., Detail: The maximum string content length quota (8192) has been exceeded while reading XML data. This quota may be increased by changing the MaxStringContentLength property on the XmlDictionaryReaderQuotas object used when creating the XML reader. Line 1, position 2321.\",\n",
"last_callback_status"": {"status_code": 200,
"responde_data": ""
},
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"id": "67093c9e46d1398aa40c64a2"
},
{"header": "yourbase64",
"mittente": "yourbase64",
"dettaglioMittente": "yourbase64",
"body": "yourbase64",
"footer": "base64",
"dettaglioLettera": "base64",
"creation_timestamp": 1728658590,
"update_timestamp": 1728658590,
"status": "NEW",
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"id": "67093c9e46d1398aa40c64a2"
}
],
"success": true,
"message": "",
"error": null
}

Create a new cover

Create a new cover for postal services including Registered Mail, Priority Mail, and Ordinary Mail.

You can insert either custom text or an image, the image must be in a supported format (e.g., JPEG, PNG)

You can find details and examples of the individual field in the schema

Example Cover PDF

Authorizations:

bearerAuth

Request Body schema: application/json

	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.
	string or string
mittente	string <base64> Default: "<base64>" Text or Base64 encoded image of the sender's logo. Recommended size is 340 x 79 pixels.Image of the sender's logo. It must be an image that includes all essential details of the sender, such as: - First and last name (or company name) - Complete address - Postal code - City and state/province - Any contacts (phone, email) - VAT number or Tax ID (if applicable) The image must be in a supported format (e.g., JPEG, PNG) and of appropriate dimensions for display in the document. Example
	string or string
	string or string
	string or string
	string or string

Responses

Response Schema: application/json

	object
success	boolean Indicates if the request was successful.
message	string Additional message regarding the request.
error	string or null Error message if an error occurred, null otherwise.

Request samples

Content type

application/json

{"callback": {"method": "POST",
"field": "data",
"url": "https://www.mysite.com/myEndpoint",
"retry": 3,
"headers": {"session_id": "9834r5fh589494"
},
"custom": {"my_custom_id": "123456789"
}
},
"header": "<string>",
"mittente": "<base64>",
"dettaglioMittente": "<string>",
"body": "<string>",
"footer": "<string>",
"dettaglioLettera": "<string>"
}

Response samples

200
400

Content type

application/json

{"data": {"header": "yourbase64",
"mittente": "yourbase64",
"dettaglioMittente": "yourbase64",
"body": "yourbase64",
"footer": "base64",
"dettaglioLettera": "base64",
"creation_timestamp": 1728658590,
"update_timestamp": 1728658590,
"status": "NEW",
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"id": "67093c9e46d1398aa40c64a2"
},
"success": true,
"message": "",
"error": null
}

Get specific cover configuration

Retrieves the configuration of a specific cover by its ID. Optionally can download the preview if the status is READY.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Unique identifier of the cover

Responses

Response Schema: application/json

	object
success	boolean Indicates if the request was successful
message	string Additional message regarding the request
error	string or null Error message if an error occurred, null otherwise

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/covers/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": {"header": "yourbase64",
"mittente": "yourbase64",
"dettaglioMittente": "yourbase64",
"body": "yourbase64",
"footer": "base64",
"dettaglioLettera": "base64",
"creation_timestamp": 1728658590,
"update_timestamp": 1728658590,
"status": "NEW",
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"id": "67093c9e46d1398aa40c64a2"
},
"success": true,
"message": "",
"error": null
}

Get specific cover preview

Retrieves the configuration of a specific cover by its ID. Optionally can download the preview if the status is READY.If the cover status is READY, returns the preview for download instead of the configuration

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Unique identifier of the cover

Responses

Response Schema: application/pdf

string <binary>

Preview PDF file (only when preview=true and status is READY)

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/covers/%7Bid%7D/preview");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

404

Content type

application/json

{"success": false,
"message": "No configuration found",
"error": 1045,
"data": null
}

List of addresses

Authorizations:

bearerAuth

query Parameters

cap	string Default: "<string>" Example: cap=05100
comune	string Default: "<string>" Example: comune=terni
dug	string Default: "<string>" Example: dug=via

Responses

Response Schema: application/json

data	Array of strings <= 2 items
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/indirizzi/?cap=05100&comune=terni&dug=via");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": ["string"
],
"success": true,
"message": "string",
"error": null
}

List of all available dugs

(denomiazioni urbanistiche generiche)

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/dug/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"codice_dug": "BGO",
"dug": "Borgo"
}
],
"message": "1 Risultato",
"success": true,
"error": null
}

Track your product

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/tracking/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"timestamp": 1604567446,
"descrizione": "accettata online",
"type": "00",
"definitivo": false
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Get information about a postal code Deprecated

Authorizations:

bearerAuth

path Parameters

code

required

string

Default: "<string>"

Example: 05100

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/comuni/05100");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

OK

{"data": [{"nome_provincia": "Terni",
"sigla_provincia": "TR",
"regione": "Umbria",
"comuni": ["Terni"
],
"dettaglio_comuni": [{"nome": "Terni",
"popolazione": 109193,
"codice_catastale": "L117",
"codice_istat": "055032"
}
]
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Telegrammi

Get information about a telegram

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state

string

Default: "<string>"

Example: state=NEW

If the option has been set, it returns a specifc schema with state equal to the one requested

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/telegrammi/%7Bid%7D?state=NEW");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": {"mittente": {"nome": "Mario",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Dante Alighieri",
"civico": "4",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"nome": "PRIMO",
"cognome": "ROSSI",
"dug": "VIA",
"indirizzo": "PRIMO MAGGIO",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "609d43e457d71a5b600ee17c",
"state": "NEW",
"IdRicevuta": "WG55505B956001"
}
],
"documento": ["Test document"
],
"opzioni": {"ar_c": {"nome": "Mario",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Dante Alighieri",
"civico": "4",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"fronteretro": false,
"colori": false,
"autoconfirm": true,
"mittente": false,
"ar_e": false,
"timestamp_invio": 1620919269
},
"prodotto": "telegramma",
"creation_timestamp": 1620919268,
"update_timestamp": 1620919779,
"username": "[email protected]",
"confirmed": true,
"state": "SENT",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/0000000eeaaaa11111111xxxxx.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/0000000eeaaaa11111111xxxxx.jpg",
"parole": 2,
"size": 11
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaRitornoCartacea",
"descrizione_servizio": "Ricevuta cartacea",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 7.93,
"importo_unitario_netto": 6.5,
"importo_unitario_iva": 1.4300000000000002
},
{"codice_servizio": "parole",
"descrizione_servizio": "Tariffa Postale parole",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 4.27,
"importo_unitario_netto": 3.5,
"importo_unitario_iva": 0.77
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 10,
"importo_totale_iva": 2.2,
"importo_totale": 12.2
}
},
"confirmed_timestamp": 1620919269,
"GuidUtente": "xxxxxx-ae90-48b5-bec1-abcdefg",
"IDRichiesta": "xxxxxx-ae90-48b5-bec1-abcdefg",
"sending_timestamp": 1620919746,
"substate": "SENT",
"error": null,
"error_timestamp": 1620919356,
"sent_timestamp": 1620919779,
"id": "xxxxxxxe557d71a5b600ee17d"
},
"message": "",
"success": true,
"error": null
}

Confirm send of a telegram

Confirm sending a telegram that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
421

Content type

application/json

{"data": [{"mittente": {"ragione_sociale": "Mario Rossi Srl",
"dug": "Viale",
"indirizzo": "dei Giardini",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"ragione_sociale": "prova spa",
"dug": "viale",
"indirizzo": "rossi mario",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"id": "649998d25b295d43ac0f1e78",
"state": "NEW"
}
],
"documento": ["tmpfiles.org/dl/980693/br223_compressed.pdf"
],
"opzioni": {"fronteretro": true,
"ar_c": false,
"ar_e": false,
"ricevuta": false,
"autoconfirm": false,
"timestamp_invio": 1687787732
},
"prodotto": "telegramma",
"creation_timestamp": 1687787729,
"update_timestamp": 1687787742,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/telegrammaUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/telegrammaUBLwd2TfrzVnSTMymTi5SnmAo.jpg",
"filename": "telegrammaUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"parole": 25,
"size": 176
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"dettaglio": [{"codice_servizio": "parole",
"descrizione_servizio": "Tariffa postale parole",
"percentuale_iva": 0,
"quantita": 25,
"importo_unitario_netto": 6.92,
"importo_unitario_iva": 0,
"importo_unitario_totale": 6.92
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.32,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.32
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.12,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.12
}
],
"totale": {"importo_totale_netto": 5.21,
"importo_totale_iva": 0,
"importo_totale": 5.21
}
},
"confirmed_timestamp": 1687787742,
"id": "649998d45b295d43ac0f1e79"
}
],
"success": true,
"message": "",
"error": null
}

Download accettazione Telegrammi

Download the "accettazione" receipt if requested at the time of submission .

Acceptance is the process that certifies the acknowledgment of a request by the system. During this phase, the data provided by the user is validated, and if correct, an acceptance receipt is generated. This receipt is a digital document that formally confirms the acceptance of the request and marks the starting point for subsequent processing.

The acceptance receipt includes:

The date and time of acceptance.
Details about the requested service, the sender, and the recipient.
A digital signature and timestamp, ensuring its legal validity.

Acceptance is a fundamental step to guarantee traceability, transparency, and legal compliance for the services provided.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

ID of request

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/telegrammi/%7Bid%7D/accettazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

List your telegrams

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/telegrammi/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"cognome": "Rossi",
"email": "[email protected]"
},
"creation_timestamp": 1620919268,
"update_timestamp": 1620919779,
"confirmed": true,
"state": "SENT",
"error": null,
"id": "xxxxxxxe557d71a5b600ee17d"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

Send a telegram. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save the telegram for a later confirmation with a PATCH request, while you do custom logic with the response.

This endpoint now supports sending foreign telegrams. Here are the key details:

Foreign Telegram Support: You can now send telegrams to international destinations.
Single Recipient: Foreign telegrams are limited to one recipient only.
Address Format: For foreign telegrams, it's crucial to write the complete address within the 'indirizzo' (address) field as shown in the example.
Province Setting: The 'provincia' (province) field will be automatically set to 'EE' (estero/foreign) for foreign addresses.
Pricing Information: To check the rates for foreign telegrams, you can use the /pricing/ endpoint.
Available Options: All options specific to foreign telegrams are listed in the schema. Any additional options not listed will be ignored.
List of Countries: For a list of countries to which you can send foreign telegrams, please refer to the /nazioni/ endpoint.

Please refer to the schema for the complete list of fields and options available for both domestic and foreign telegrams.

Authorizations:

bearerAuth

Request Body schema: application/json

	Array of telegramma_options (object) or telegramma_foreign_options (object) <= 2 items [ items ]
	object
	Array of recipient (object) or foreign_recipient (object) <= 2 items [ items ]
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.
documento	any (documentoTelegramma) The "document" field must be an array with a single element of type text. No other types of content such as HTML, PDF, URL, or base64 are allowed. The text within the array must not exceed 8100 Characters and 2000 words.

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	object or null

Callbacks

Request samples

Content type

application/json

Example

{"mittente": {"ragione_sociale": "openapi spa",
"dug": "piazza",
"indirizzo": "cavur '",
"civico": "43",
"comune": "roma",
"cap": "00121",
"provincia": "rm",
"email": "prova.******@gmail.com",
"nazione": "IT"
},
"destinatari": [{"nome": "Giacomo",
"cognome": "Rossi",
"dug": "VIA",
"indirizzo": "PROVA",
"civico": "8",
"comune": "MIlano",
"cap": "20123",
"provincia": "MI",
"nazione": "IT",
"id": "664228bbbf*****01b0815f2",
"state": "NEW"
}
],
"documento": ["XX XXXXXX XXXXXXXXXXXXXXX XXXXX XXXXXXXX XXXXXXXXX XXXXXXXXX XXXXX XXXXXXXX XXX, XX XXXXXXXX XXXXX X XXX XXXXX XX XXXXXXX XXX 18 XXXXX 2023,XXXXXXX XX XXXXX XX XXXXXXX XXXXXXXX XX XXXXXXXX XXXXXXX XX 250.000 XXXX, XXXXXX XX XXXXXXX XX X. 3 XXXXXXX XXX XX XXXXXX XX 30000 XXXX. XX XXXXXXXX XXXXXXXX XXXXXXX XXXXXX XXXXX XX 30 XXXXXXXXX 2023, XXXXXXXXXX XX XXXXX XXXXXXXXXXXXXX XX XXXXX XX XXXXXXXXXXXXXX XXXXXX X XXXXXX XX XXXXXXXXX XXXXXX XX XXXX XXXXXXXXXXX. XX XXXXXXXXX XX XX XXXXXXXX XXXX XXXXXXXX XXXXXXXX; XX XXXX XXXXXXXXX, XX XXXXXXXXX XXXXX XXXXXXXXXXXX X XXXXXXXXXXXX XX XXXXXX XXXXXXXXXXXXX XXXXX XXXX XXXXXXXXX, XXXXXXXXXXXX XX XXXXXXXXXX XX XXXXXXXXXXXX XX XXXX XXXXX XXXXXX."
],
"opzioni": {"autoconfirm": false,
"mittente": true,
"ar_c": false,
"ar_e": false
},
"callback": {"url": "https://your-server.site/123232",
"custom": 123
}
}

Response samples

201
421
422
500

Content type

application/json

{"data": {"mittente": {"ragione_sociale": "openapi spa",
"dug": "piazza",
"indirizzo": "cavur '",
"civico": "43",
"comune": "roma",
"cap": "00121",
"provincia": "rm",
"email": "prova.******@gmail.com",
"nazione": "IT",
"destinatari": [{"nome": "Giacomo",
"cognome": "Rossi",
"dug": "VIA",
"indirizzo": "PROVA",
"civico": "8",
"comune": "MIlano",
"cap": "20123",
"provincia": "MI",
"nazione": "IT",
"id": "664228bbbf1239901b0815f2",
"state": "NEW"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "PIAZZA",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "61041dc0ac2b1f63327e92d1",
"state": "NEW"
}
],
"documento": "lorem ipsum",
"opzioni": {"autoconfirm": true,
"mittente": false,
"ar_c": false,
"ar_e": false,
"timestamp_invio": 1627659712
},
"prodotto": "telegramma",
"creation_timestamp": 1627659712,
"update_timestamp": 1627659712,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/test-document.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/test-document.jpg",
"parole": 1,
"txt": "L",
"size": 1
},
"pricing": {"dettaglio": [{"codice_servizio": "parole",
"descrizione_servizio": "Tariffa Postale parole",
"percentuale_iva": 22,
"quantita": 2,
"importo_unitario_totale": 4.27,
"importo_unitario_netto": 3.5,
"importo_unitario_iva": 0.77
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 7,
"importo_totale_iva": 1.54,
"importo_totale": 8.54
}
},
"lock": false,
"confirmed_timestamp": 1627659712,
"id": "61041dc0ac2b1f63327e92d2"
}
},
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

Atti Giudiziari

This product offers a tracking code

Download archiviazione Atti Giudiziari

Download the archival document when it is ready. You can check the status here. The documents will be digitally signed by the responsible representative of Poste Italiane, timestamped, and stored in a dedicated document management system.

NB: The client declares compliance with the provisions of Law No. 53 of January 21, 1994, particularly regarding the management and preservation of digitally archived documents. Specifically:

The client is responsible for downloading the digital archive of the document within 2 months from its availability.
The client assumes full responsibility for retaining this copy, as it will not be stored in our archives beyond the specified timeframe.
Failure to download or properly retain the document will result in the loss of the archived version, and no recovery will be possible from our systems.

Authorizations:

bearerAuth

path Parameters

id required	string Default: "<string>" ID of request
IdDestinatario required	string Default: "<string>" You can check the destinatari.id [here](https://console.openapi.com/it/apis/ufficiopostale/documentation#/Atti Giudiziari/get_raccomandate__id_).

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/atti_giudiziari/%7Bid%7D/destinatari/%7BIdDestinatario%7D/archiviazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Download Digital Return Receipt (AR Digitale)

Downloads the Return Receipt (Avviso di Ricevimento - AR) in digital format for a specific recipient of a Judicial Act (Atto Giudiziario).

The Digital Return Receipt (Avviso di Ricevimento Digitale - AR Digitale) is a legally valid electronic document that certifies the notification of the act. It is produced only if the digital return receipt option was enabled during submission. The returned document is digitally signed and timestamped.

Authorizations:

bearerAuth

path Parameters

id required	string Default: "<string>" ID of the Judicial Act request (Atto Giudiziario).
IdDestinatario required	string Default: "<string>" ID of the recipient for whom the Digital Return Receipt (AR Digitale) is requested. It can be found in the `destinatari` object of the `GET /atti_giudiziari/{id}` response.

Responses

Response Schema: application/pdf

string <binary>

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/atti_giudiziari/%7Bid%7D/destinatari/%7BIdDestinatario%7D/ardigitale");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

404

Content type

application/json

{"success": false,
"message": "Digital Return Receipt not found or not yet available.",
"error": 2017,
"data": null
}

Download accettazione Atti Giudiziari

Download the "accettazione" receipt if requested at the time of submission .

Acceptance is the process that certifies the acknowledgment of a request by the system. During this phase, the data provided by the user is validated, and if correct, an acceptance receipt is generated. This receipt is a digital document that formally confirms the acceptance of the request and marks the starting point for subsequent processing.

The acceptance receipt includes:

The date and time of acceptance.
Details about the requested service, the sender, and the recipient.
A digital signature and timestamp, ensuring its legal validity.

Acceptance is a fundamental step to guarantee traceability, transparency, and legal compliance for the services provided.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

ID of request

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/atti_giudiziari/%7Bid%7D/accettazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Get information about a Atto Giudiziaro

Check the NumeroRaccomandata field in the recipient object if you need the tracking number

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state	string Default: "<string>" Example: state=NEW If the option has been set, it returns a specifc schema with state equal to the one requested
callback	string Default: "<string>" Example: callback=<empty string> Simulates the progress of the shipment status: every time that this endpoint is called, your request progresses the the next shipping status. If specified in the request, you will receive callback updates. Please note that this option is avaialble ONLY for the sandbox environment

Responses

Response Schema: application/json

	object
message	string
success	boolean
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/atti_giudiziari/%7Bid%7D?state=NEW&callback=%3Cempty%20string%3E");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": {"mittente": {"nome": "Mario",
"cognome": "Bianchi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"state": "SENT"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "000000000000000000000000",
"state": "SENT",
"NumeroRaccomandata": "123412341234",
"archiviazione": "WAITING"
}
],
"documento": ["Test di invio"
],
"opzioni": {"fronteretro": false,
"colori": true,
"ar": {"nome": "Mario",
"cognome": "Bianchi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"state": "SENT"
},
"ricevuta": false,
"autoconfirm": false,
"timestamp_invio": 1662372837
},
"prodotto": "atto_giudiziaro",
"creation_timestamp": 1662372836,
"update_timestamp": 1662372836,
"username": "[email protected]",
"confirmed": false,
"state": "NEW",
"documento_validato": {"pdf": "https://xxxxxxxxx.pdf",
"jpg": "https://xxxxxxxxx.jpg",
"filename": "example.pdf",
"pagine": 1,
"size": 4513
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta Ritorno",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "StampaColori",
"descrizione_servizio": "Stampa Colori",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.976,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0.176
},
{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta di Ritorno",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 3.4,
"importo_unitario_netto": 3.4,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 20,
"quantita": 1,
"importo_unitario_totale": 0.12000000000000001,
"importo_unitario_netto": 0.1,
"importo_unitario_iva": 0.02
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 1.2,
"importo_unitario_netto": 1,
"importo_unitario_iva": 0.2
}
],
"totale": {"importo_totale_netto": 6.1,
"importo_totale_iva": 0.396,
"importo_totale": 6.4959999999999996
}
},
"id": "4242424242424242424242"
},
"message": "",
"success": true,
"error": null
}

Confirm send Atti Giudiziari

Confirm sending a atto_giudiziaro that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406
421

Content type

application/json

{"data": {"mittente": {"ragione_sociale": "Mario Rossi Srl",
"dug": "Viale",
"indirizzo": "dei Giardini",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"ragione_sociale": "prova spa",
"dug": "viale",
"indirizzo": "rossi mario",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"id": "649998d25b295d43ac0f1e78",
"state": "NEW"
}
],
"documento": ["tmpfiles.org/dl/980693/br223_compressed.pdf"
],
"opzioni": {"fronteretro": true,
"colori": true,
"ar": true,
"ricevuta": false,
"autoconfirm": false,
"timestamp_invio": 1687787732
},
"prodotto": "atto_giudiziaro",
"creation_timestamp": 1687787729,
"update_timestamp": 1687787742,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/atto_giudiziaroUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/atto_giudiziaroUBLwd2TfrzVnSTMymTi5SnmAo.jpg",
"filename": "atto_giudiziaroUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"pagine": 1,
"size": 6308
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta Ritorno",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "FronteRetro",
"descrizione_servizio": "Fronte Retro",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.05,
"importo_unitario_netto": 0.05,
"importo_unitario_iva": 0
},
{"codice_servizio": "StampaColori",
"descrizione_servizio": "Stampa Colori",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 3.92,
"importo_unitario_iva": 0,
"importo_unitario_totale": 3.92
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.32,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.32
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.12,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.12
}
],
"totale": {"importo_totale_netto": 5.21,
"importo_totale_iva": 0,
"importo_totale": 5.21
}
},
"confirmed_timestamp": 1687787742,
"id": "649998d45b295d43ac0f1e79"
},
"success": true,
"message": "",
"error": null
}

List your Atti Giudiziari

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/atti_giudiziari/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Alberto",
"cognome": "Rossi",
"email": "[email protected]"
},
"creation_timestamp": 1608040424,
"update_timestamp": 1608040424,
"confirmed": false,
"state": "NEW",
"id": "5fd8bfeaa10b340e2e558db7"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

A "Atto Giudiziario" is a legal document used to formally notify a judicial action, such as summons, payment orders, or court rulings. Italian law requires these documents to be sent via a special registered mail service that ensures:

Delivery traceability.
Issuance of a return receipt (Avviso di Ricevimento, AR).
Legal validity of the delivery, as required by law.
Sending a Judicial Act through an API allows companies to automate and centrally manage the process of sending, confirming, and tracking, while maintaining compliance with regulations regarding judicial notifications.

Send an "Atto Giudiziario" with the following requirements:

Delivery is limited to the national territory, with a maximum weight of 2 kg.
Shipments to foreign destinations, including Vatican City and San Marino, are not allowed.
Shipments cannot be directed to P.O. Boxes.
Delivery occurs within 5 business days, plus an additional 2 days for printing.
A single national rate applies to all shipments within the territory, regardless of logistical destination.
The recipient of the return receipt (23L) must have the same name as the sender.
The "AR" option is mandatory and can be set to true, or an object with the AR recipient's details can be provided.
- IMPORTANT: The recipient’s name must match the sender of the "Atto Giudiziario."
The "autoconfirm" parameter can be set to false to save the Raccomandata for later confirmation via a PATCH request, allowing for custom handling of the response.

Check the NumeroRaccomandata field in the recipient object if you need the tracking number

NB: The client declares compliance with the provisions of Law No. 53 of January 21, 1994, particularly regarding the management and preservation of digitally archived documents. Specifically:

The client is responsible for downloading the digital archive of the document within 2 months from its availability.
The client assumes full responsibility for retaining this copy, as it will not be stored in our archives beyond the specified timeframe.
Failure to download or properly retain the document will result in the loss of the archived version, and no recovery will be possible from our systems.

Authorizations:

bearerAuth

Request Body schema: application/json

	object (atti_giudiziari_options)
	object (atti_giudiziari_sender_object)
	object (atti_giudiziari_recipient_object)
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	object or null

Callbacks

Request samples

Content type

application/json

{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "Italia"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": true,
"autoconfirm": true,
"atti_giudiziari": {"centro_costo_cliente": "ABC123",
"note": "Consegnare entro 72h",
"notificante": {"tipologia": "UfficialeGiudiziario",
"valore": "prova"
},
"numero_cronologico": "2023001",
"oggetto": "Diffida art. 123",
"partner_tecnologico": "TechPartner Srl",
"tipo_lingua": "IT"
}
}
}

Response samples

201
421
422
500

Content type

application/json

{"data": [{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "IT",
"id": "6103f711dd2507415c5db6ce",
"state": "NEW"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "6103f711dd2507415c5db6cf",
"state": "NEW"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"autoconfirm": true,
"timestamp_invio": 1627649810
},
"prodotto": "atto_giudiziario",
"creation_timestamp": 1627649809,
"update_timestamp": 1627649810,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/f7294e76871965ea206d560d77ff079e.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/f7294e76871965ea206d560d77ff079e.jpg",
"pagine": 1,
"size": 9350
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta di Ritorno",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 3.4,
"importo_unitario_netto": 3.4,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0.1,
"importo_unitario_netto": 0.1,
"importo_unitario_iva": 0
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 8.6,
"importo_totale_iva": 0,
"importo_totale": 8.6
}
},
"lock": false,
"confirmed_timestamp": 1627649810,
"id": "6103f712dd2507415c5db6d0"
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

Raccomandate

This product offers a tracking code

List your Raccomandate

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Alberto",
"cognome": "Rossi",
"email": "[email protected]"
},
"creation_timestamp": 1608040424,
"update_timestamp": 1608040424,
"confirmed": false,
"state": "NEW",
"id": "5fd8bfeaa10b340e2e558db7"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

Send a Raccomandata. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save the Raccomandata for a later confirmation with a PATCH request, while you do custom logic with the response. Check the NumeroRaccomandata field in the recipient object if you need the tracking number

This endpoint now supports sending international registered mail. Here are the key details:

International Raccomandata Support: You can now send registered mail to international destinations.
Multiple Recipients: Foreign Raccomandata are limited to one recipient only. recipients.
Address Format: For international registered mail, ensure you provide the complete address within the appropriate fields as shown in the example.
Province Setting: For international addresses, the 'provincia' (province) field should be left empty or set according to the destination country's format.
Pricing Information: To check the rates for international registered mail, you can use the /pricing/ endpoint.
Available Options: All options specific to international registered mail are listed in the schema. Any additional options not listed will be ignored.
List of Countries: For a list of countries to which you can send international registered mail, please refer to the /nazioni/ endpoint. This endpoint provides both pricing information and the list of available countries for international services.

Please refer to the schema for the complete list of fields and options available for both domestic and international registered mail.

Authorizations:

bearerAuth

Request Body schema: application/json

	Array of raccomandata_options (object) or ForeignRaccomandataOption (object) <= 2 items [ items ]
	object (common_sender_object)
	Array of (Recipient or Casella postale (Recipient (object) or Casella postale (object))) or ForeignRecipient (object) <= 2 items [ items ]
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	object or null

Callbacks

Request samples

Content type

application/json

Example

{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "Italia"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": true,
"autoconfirm": true
}
}

Response samples

201
421
422
500

Content type

application/json

{"data": [{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "IT",
"id": "6103f711dd2507415c5db6ce",
"state": "NEW"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "6103f711dd2507415c5db6cf",
"state": "NEW"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"autoconfirm": true,
"timestamp_invio": 1627649810
},
"prodotto": "raccomandata",
"creation_timestamp": 1627649809,
"update_timestamp": 1627649810,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/f7294e76871965ea206d560d77ff079e.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/f7294e76871965ea206d560d77ff079e.jpg",
"pagine": 1,
"size": 9350
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta di Ritorno",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 3.4,
"importo_unitario_netto": 3.4,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0.1,
"importo_unitario_netto": 0.1,
"importo_unitario_iva": 0
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 8.6,
"importo_totale_iva": 0,
"importo_totale": 8.6
}
},
"lock": false,
"confirmed_timestamp": 1627649810,
"id": "6103f712dd2507415c5db6d0"
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

Download archiviazione Raccomandata

Download the archival document when it is ready. You can check the status here. The documents will be digitally signed by the responsible representative of Poste Italiane, timestamped, and stored in a dedicated document management system.

Authorizations:

bearerAuth

path Parameters

id required	string Default: "<string>" ID of request
IdDestinatario required	string Default: "<string>" You can check the destinatari.id here.

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate/%7Bid%7D/destinatari/%7BIdDestinatario%7D/archiviazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Download accettazione Raccomandate

Download the "accettazione" receipt if requested at the time of submission .

Acceptance is the process that certifies the acknowledgment of a request by the system. During this phase, the data provided by the user is validated, and if correct, an acceptance receipt is generated. This receipt is a digital document that formally confirms the acceptance of the request and marks the starting point for subsequent processing.

The acceptance receipt includes:

The date and time of acceptance.
Details about the requested service, the sender, and the recipient.
A digital signature and timestamp, ensuring its legal validity.

Acceptance is a fundamental step to guarantee traceability, transparency, and legal compliance for the services provided.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

ID of request

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate/%7Bid%7D/accettazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Get information about a Raccomandata

Check the NumeroRaccomandata field in the recipient object if you need the tracking number

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state	string Default: "<string>" Example: state=NEW If the option has been set, it returns a specifc schema with state equal to the one requested
callback	string Default: "<string>" Example: callback=<empty string> Simulates the progress of the shipment status: every time that this endpoint is called, your request progresses the the next shipping status. If specified in the request, you will receive callback updates. Please note that this option is avaialble ONLY for the sandbox environment

Responses

Response Schema: application/json

	object
message	string
success	boolean
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate/%7Bid%7D?state=NEW&callback=%3Cempty%20string%3E");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": {"mittente": {"nome": "Mario",
"cognome": "Bianchi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"state": "SENT"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "000000000000000000000000",
"state": "SENT",
"NumeroRaccomandata": "123412341234",
"archiviazione": "WAITING"
}
],
"documento": ["Test di invio"
],
"opzioni": {"fronteretro": false,
"colori": true,
"ar": {"nome": "Mario",
"cognome": "Bianchi",
"dug": "piazza",
"indirizzo": "italia",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"state": "SENT"
},
"ricevuta": false,
"autoconfirm": false,
"timestamp_invio": 1662372837
},
"prodotto": "raccomandata",
"creation_timestamp": 1662372836,
"update_timestamp": 1662372836,
"username": "[email protected]",
"confirmed": false,
"state": "NEW",
"documento_validato": {"pdf": "https://xxxxxxxxx.pdf",
"jpg": "https://xxxxxxxxx.jpg",
"filename": "example.pdf",
"pagine": 1,
"size": 4513
},
"pricing": {"dettaglio": [{"codice_servizio": "StampaColori",
"descrizione_servizio": "Stampa Colori",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.976,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0.176
},
{"codice_servizio": "RicevutaRitorno",
"descrizione_servizio": "Ricevuta di Ritorno",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 3.4,
"importo_unitario_netto": 3.4,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 20,
"quantita": 1,
"importo_unitario_totale": 0.12000000000000001,
"importo_unitario_netto": 0.1,
"importo_unitario_iva": 0.02
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 1.2,
"importo_unitario_netto": 1,
"importo_unitario_iva": 0.2
}
],
"totale": {"importo_totale_netto": 6.1,
"importo_totale_iva": 0.396,
"importo_totale": 6.4959999999999996
}
},
"id": "4242424242424242424242"
},
"message": "",
"success": true,
"error": null
}

Confirm send Posta Raccomandate

Confirm sending a Raccomandata that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406
421

Content type

application/json

{"data": [{"mittente": {"ragione_sociale": "Mario Rossi Srl",
"dug": "Viale",
"indirizzo": "dei Giardini",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"ragione_sociale": "prova spa",
"dug": "viale",
"indirizzo": "rossi mario",
"civico": "82",
"comune": "san dona' di piave",
"cap": "30027",
"provincia": "VE",
"nazione": "IT",
"id": "649998d25b295d43ac0f1e78",
"state": "NEW"
}
],
"documento": ["tmpfiles.org/dl/980693/br223_compressed.pdf"
],
"opzioni": {"fronteretro": true,
"colori": true,
"ar": false,
"ricevuta": false,
"autoconfirm": false,
"timestamp_invio": 1687787732
},
"prodotto": "raccomandata",
"creation_timestamp": 1687787729,
"update_timestamp": 1687787742,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/raccomandataUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/raccomandataUBLwd2TfrzVnSTMymTi5SnmAo.jpg",
"filename": "raccomandataUBLwd2TfrzVnSTMymTi5SnmAo.pdf",
"pagine": 1,
"size": 6308
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"dettaglio": [{"codice_servizio": "FronteRetro",
"descrizione_servizio": "Fronte Retro",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.05,
"importo_unitario_netto": 0.05,
"importo_unitario_iva": 0
},
{"codice_servizio": "StampaColori",
"descrizione_servizio": "Stampa Colori",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.8,
"importo_unitario_netto": 0.8,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 3.92,
"importo_unitario_iva": 0,
"importo_unitario_totale": 3.92
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.32,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.32
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_netto": 0.12,
"importo_unitario_iva": 0,
"importo_unitario_totale": 0.12
}
],
"totale": {"importo_totale_netto": 5.21,
"importo_totale_iva": 0,
"importo_totale": 5.21
}
},
"confirmed_timestamp": 1687787742,
"id": "649998d45b295d43ac0f1e79"
}
],
"success": true,
"message": "",
"error": null
}

Posta Prioritaria

This product offers a code to track status updates

List your requests

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/prioritarie/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Alberto",
"cognome": "Rossi",
"email": "[email protected]"
},
"creation_timestamp": 1608040424,
"update_timestamp": 1608040424,
"confirmed": false,
"state": "NEW",
"id": "5fd8bfeaa10b340e2e558db7"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

Send a priority mail. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save the mail for a later confirmation with a PATCH request, while you do custom logic with the response. Check the IdRicevuta field in the recipient object if you need the tracking number

This endpoint now supports sending foreign Prioritaria. Here are the key details:

Foreign Prioritaria Support: You can now send Prioritaria to international destinations.
Single Recipient: Foreign Prioritaria are limited to one recipient only.
Address Format: For foreign Prioritaria, it's crucial to write the complete address within the 'indirizzo' (address) field as shown in the example.
Province Setting: The 'provincia' (province) field will be automatically set to 'EE' (estero/foreign) for foreign addresses.
Pricing Information: To check the rates for foreign Prioritaria, you can use the /pricing/ endpoint.
Available Options: All options specific to foreign Prioritaria are listed in the schema. Any additional options not listed will be ignored.
List of Countries: For a list of countries to which you can send foreign Prioritaria, please refer to the /nazioni/ endpoint.

Please refer to the schema for the complete list of fields and options available for both domestic and foreign priority mail.

Authorizations:

bearerAuth

Request Body schema: application/json

	Array of posta_options (object) or ForeignPostaOption (object) <= 2 items [ items ]
	Array of (Recipient or Casella postale (Recipient (object) or Casella postale (object))) or ForeignRecipient (object) <= 2 items [ items ]
	object
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	object or null

Callbacks

Request samples

Content type

application/json

Example

{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "Italia"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": true
}
}

Response samples

201
422

Content type

application/json

{"data": [{"mittente": {"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": true,
"timestamp_invio": 1627649810
},
"prodotto": "prioritaria",
"creation_timestamp": 1627649809,
"update_timestamp": 1627649810,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/f7294e76871965ea206d560d77ff079e.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/f7294e76871965ea206d560d77ff079e.jpg",
"pagine": 1,
"size": 9350
},
"pricing": {"dettaglio": [{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 8.6,
"importo_totale_iva": 0,
"importo_totale": 8.6
}
},
"lock": false,
"confirmed_timestamp": 1627649810,
"id": "6103f712dd2507415c5db6d0"
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

Download accettazione Posta Prioritaria

Download the "accettazione" receipt if requested at the time of submission .

Acceptance is the process that certifies the acknowledgment of a request by the system. During this phase, the data provided by the user is validated, and if correct, an acceptance receipt is generated. This receipt is a digital document that formally confirms the acceptance of the request and marks the starting point for subsequent processing.

The acceptance receipt includes:

The date and time of acceptance.
Details about the requested service, the sender, and the recipient.
A digital signature and timestamp, ensuring its legal validity.

Acceptance is a fundamental step to guarantee traceability, transparency, and legal compliance for the services provided.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

ID of request

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/prioritarie/%7Bid%7D/accettazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Download archiviazione Prioritarie

Download the archival document when it is ready. You can check the status here. The documents will be digitally signed by the responsible representative of Poste Italiane, timestamped, and stored in a dedicated document management system.

Authorizations:

bearerAuth

path Parameters

id required	string Default: "<string>" ID of request
IdDestinatario required	string Default: "<string>" You can check the destinatari.id here.

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/prioritarie/%7Bid%7D/destinatari/%7BIdDestinatario%7D/archiviazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Get information about a single priority mail

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state	string Default: "<string>" Example: state=NEW If the option has been set, it returns a specifc schema with state equal to the one requested
callback	string Default: "<string>" Simulates the progress of the shipment status: every time that this endpoint is called, your request progresses the the next shipping status. If specified in the request, you will receive callback updates. Please note that this option is avaialble ONLY for the sandbox environment

Responses

Response Schema: application/json

	object
message	string
success	boolean
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/prioritarie/%7Bid%7D?state=NEW&callback=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": {"mittente": {"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
}
],
"documento": ["testo di prova"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": true,
"timestamp_invio": 1635168169
},
"prodotto": "prioritaria",
"creation_timestamp": 1635168169,
"update_timestamp": 1635168169,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/test.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/test.jpg",
"pagine": 1,
"size": 5249
},
"pricing": {"dettaglio": [{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.85,
"importo_unitario_netto": 0.85,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.20740000000000003,
"importo_unitario_netto": 0.17,
"importo_unitario_iva": 0.0374
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.31720000000000004,
"importo_unitario_netto": 0.26,
"importo_unitario_iva": 0.0572
}
],
"totale": {"importo_totale_netto": 1.28,
"importo_totale_iva": 0.0946,
"importo_totale": 1.3746
}
},
"confirmed_timestamp": 1635168169,
"id": "az034324hjksd829jwqlo12uo"
},
"message": "",
"success": true,
"error": null
}

Confirm send Posta Prioritaria

Confirm sending a mail that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406

Content type

application/json

{"data": [{"mittente": {"titolo": "mr",
"nome": "Lorenzo",
"cognome": "Paderi",
"dug": "Piazza",
"indirizzo": "ener bettica",
"civico": "43",
"comune": "roma",
"cap": "00121",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"titolo": "mr",
"nome": "Lorenzo",
"cognome": "Paderi",
"dug": "Piazza",
"indirizzo": "ener bettica",
"civico": "43",
"comune": "roma",
"cap": "00121",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]",
"id": "6499a05813df9dd7900e42c4",
"state": "NEW"
}
],
"documento": ["Lorem ipsum dixit nuovo test2"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": false,
"ricevuta": true,
"timestamp_invio": 1687789658
},
"prodotto": "prioritaria",
"creation_timestamp": 1687789656,
"update_timestamp": 1687789674,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/prioritariaCukonJsUHfAJMObAd1WFFPGP7.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/prioritariaCukonJsUHfAJMObAd1WFFPGP7.jpg",
"filename": "prioritariaCukonJsUHfAJMObAd1WFFPGP7.pdf",
"pagine": 1,
"size": 5273
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"dettaglio": [{"codice_servizio": "RicevutaDiInvio",
"descrizione_servizio": "Ricevuta Di Invio",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 1,
"importo_unitario_netto": 1,
"importo_unitario_iva": 0
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa postale pagine",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 2.1,
"importo_unitario_iva": 0.462,
"importo_unitario_totale": 2.5620000000000003
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 0.22,
"importo_unitario_iva": 0.048400000000000006,
"importo_unitario_totale": 0.2684
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 0.23,
"importo_unitario_iva": 0.0506,
"importo_unitario_totale": 0.2806
}
],
"totale": {"importo_totale_netto": 3.5500000000000003,
"importo_totale_iva": 0.561,
"importo_totale": 4.111000000000001
}
},
"confirmed_timestamp": 1687789674,
"id": "6499a05a13df9dd7900e42c5"
}
],
"success": true,
"message": "",
"error": null
}

Posta Ordinaria

List your requests

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/ordinarie/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Alberto",
"cognome": "Rossi",
"email": "[email protected]"
},
"creation_timestamp": 1608040424,
"update_timestamp": 1608040424,
"confirmed": false,
"state": "NEW",
"id": "5fd8bfeaa10b340e2e558db7"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

Send a standard mail. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save the mail for a later confirmation with a PATCH request, while you do custom logic with the response.

This endpoint now supports sending foreign Ordinaria. Here are the key details:

Foreign Ordinaria Support: You can now send Ordinaria to international destinations.
Single Recipient: Foreign Ordinaria are limited to one recipient only.
Address Format: For foreign Ordinaria, it's crucial to write the complete address within the 'indirizzo' (address) field as shown in the example.
Province Setting: The 'provincia' (province) field will be automatically set to 'EE' (estero/foreign) for foreign addresses.
Pricing Information: To check the rates for foreign Ordinaria, you can use the /pricing/ endpoint.
Available Options: All options specific to foreign Ordinaria are listed in the schema. Any additional options not listed will be ignored.
List of Countries: For a list of countries to which you can send foreign Ordinaria, please refer to the /nazioni/ endpoint.

Please refer to the schema for the complete list of fields and options available for both domestic and foreign standard mail.

Authorizations:

bearerAuth

Request Body schema: application/json

	Array of posta_options (object) or ForeignPostaOption (object) <= 2 items [ items ]
	object
	Array of (Recipient or Casella postale (Recipient (object) or Casella postale (object))) or ForeignRecipient (object) <= 2 items [ items ]
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.

Responses

Response Schema: application/json

	Array of objects[ items ]
success	boolean
message	string
error	object or null

Callbacks

Request samples

Content type

application/json

Example

{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "Italia"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": true
}
}

Response samples

201
421
422
500

Content type

application/json

Example

{"data": [{"mittente": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "interno A",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RE",
"nazione": "IT",
"id": "6103f711dd2507415c5db6ce",
"state": "NEW"
},
{"nome": "Mario",
"cognome": "Rossi",
"co": "OPENAPI SRL",
"dug": "piazza",
"indirizzo": "San Giovanni",
"civico": "6",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"id": "6103f711dd2507415c5db6cf",
"state": "NEW"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": {"titolo": "mr",
"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"dettaglio_immobile": "scala B",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"autoconfirm": true,
"timestamp_invio": 1627649810
},
"prodotto": "ordinaria",
"creation_timestamp": 1627649809,
"update_timestamp": 1627649810,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/f7294e76871965ea206d560d77ff079e.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/f7294e76871965ea206d560d77ff079e.jpg",
"pagine": 1,
"size": 9350
},
"pricing": {"dettaglio": [{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 3.4,
"importo_unitario_netto": 3.4,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0.1,
"importo_unitario_netto": 0.1,
"importo_unitario_iva": 0
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 0,
"quantita": 2,
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0
}
],
"totale": {"importo_totale_netto": 8.6,
"importo_totale_iva": 0,
"importo_totale": 8.6
}
},
"lock": false,
"confirmed_timestamp": 1627649810,
"id": "6103f712dd2507415c5db6d0"
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

Download accettazione Posta Ordinaria

Download the "accettazione" receipt if requested at the time of submission .

Acceptance is the process that certifies the acknowledgment of a request by the system. During this phase, the data provided by the user is validated, and if correct, an acceptance receipt is generated. This receipt is a digital document that formally confirms the acceptance of the request and marks the starting point for subsequent processing.

The acceptance receipt includes:

The date and time of acceptance.
Details about the requested service, the sender, and the recipient.
A digital signature and timestamp, ensuring its legal validity.

Acceptance is a fundamental step to guarantee traceability, transparency, and legal compliance for the services provided.

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

ID of request

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/ordinarie/%7Bid%7D/accettazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Download archiviazione Ordinaria

Download the archival document when it is ready. You can check the status here. The documents will be digitally signed by the responsible representative of Poste Italiane, timestamped, and stored in a dedicated document management system.

Authorizations:

bearerAuth

path Parameters

id required	string Default: "<string>" ID of request
IdDestinatario required	string Default: "<string>" You can check the destinatari.id here.

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/ordinarie/%7Bid%7D/destinatari/%7BIdDestinatario%7D/archiviazione");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/pdf

pdf

Get information about a single mail

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state

string

Default: "<string>"

Example: state=NEW

If the option has been set, it returns a specifc schema with state equal to the one requested

Responses

Response Schema: application/json

	object
message	string
success	boolean
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/ordinarie/%7Bid%7D?state=NEW");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": {"mittente": {"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"titolo": "mr",
"nome": "John",
"cognome": "Doe",
"dug": "Piazza",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
}
],
"documento": ["testo di prova"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": true,
"timestamp_invio": 1635168169
},
"prodotto": "ordinaria",
"creation_timestamp": 1635168169,
"update_timestamp": 1635168169,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://ws.ufficiopostale.com/Up/pdf/test.pdf",
"jpg": "https://ws.ufficiopostale.com/Up/jpg/test.jpg",
"pagine": 1,
"size": 5249
},
"pricing": {"dettaglio": [{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa Postale pagine",
"percentuale_iva": 0,
"quantita": 1,
"importo_unitario_totale": 0.85,
"importo_unitario_netto": 0.85,
"importo_unitario_iva": 0
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.20740000000000003,
"importo_unitario_netto": 0.17,
"importo_unitario_iva": 0.0374
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.31720000000000004,
"importo_unitario_netto": 0.26,
"importo_unitario_iva": 0.0572
}
],
"totale": {"importo_totale_netto": 1.28,
"importo_totale_iva": 0.0946,
"importo_totale": 1.3746
}
},
"confirmed_timestamp": 1635168169,
"id": "az034324hjksd829jwqlo12uo"
},
"message": "",
"success": true,
"error": null
}

Confirm send Posta Ordinaria

Confirm sending a mail that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406
421

Content type

application/json

{"data": [{"mittente": {"titolo": "mr",
"nome": "Lorenzo",
"cognome": "Paderi",
"dug": "Piazza",
"indirizzo": "ener bettica",
"civico": "1",
"comune": "roma",
"cap": "00121",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
},
"destinatari": [{"titolo": "mr",
"nome": "Lorenzo",
"cognome": "Paderi",
"dug": "Piazza",
"indirizzo": "ener bettica",
"civico": "11",
"comune": "roma",
"cap": "00121",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]",
"id": "64999de413df9dd7900e42c0",
"state": "NEW"
}
],
"documento": ["https://www.nasa.gov/pdf/65431main_ffs_factsheets_issoverview.pdf",
"https://www.nasa.gov/pdf/65431main_ffs_factsheets_issoverview.pdf"
],
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": false,
"timestamp_invio": 1687789031
},
"prodotto": "ordinaria",
"creation_timestamp": 1687789028,
"update_timestamp": 1687789043,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/ordinariaZTq31xBfGVtjo4YxQJzSrvNRb.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/ordinariaZTq31xBfGVtjo4YxQJzSrvNRb.jpg",
"filename": "ordinariaZTq31xBfGVtjo4YxQJzSrvNRb.pdf",
"pagine": 4,
"size": 149658
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"dettaglio": [{"codice_servizio": "StampaColori",
"descrizione_servizio": "Stampa Colori",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_totale": 0.8539999999999999,
"importo_unitario_netto": 0.7,
"importo_unitario_iva": 0.15399999999999997
},
{"codice_servizio": "pagine",
"descrizione_servizio": "Tariffa postale pagine",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 0.95,
"importo_unitario_iva": 0.209,
"importo_unitario_totale": 1.159
},
{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 0.4,
"importo_unitario_iva": 0.088,
"importo_unitario_totale": 0.488
},
{"codice_servizio": "IMBUST",
"descrizione_servizio": "Imbustamento",
"percentuale_iva": 22,
"quantita": 1,
"importo_unitario_netto": 0.14,
"importo_unitario_iva": 0.030800000000000004,
"importo_unitario_totale": 0.1708
}
],
"totale": {"importo_totale_netto": 2.19,
"importo_totale_iva": 0.48179999999999995,
"importo_totale": 2.6717999999999997
}
},
"confirmed_timestamp": 1687789043,
"id": "64999de713df9dd7900e42c1"
}
],
"success": true,
"message": "",
"error": null
}

Raccomandata Smart

List your raccomandate_smart

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
message	string
success	boolean
error	any

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate_smart/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"ragione_sociale": "openapi srl",
"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi"
},
"creation_timestamp": 1657169682,
"update_timestamp": 1676901090,
"confirmed": false,
"state": "SENT",
"id": "xxxxxxxe557d71a5b600ee11d"
}
],
"message": "1 Risultati",
"success": true,
"error": null
}

Create your request

Send a Raccomandata Smart. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save it for a later confirmation with a PATCH request, while you do custom logic with the response.

Authorizations:

bearerAuth

Request Body schema: application/json

	object
	object
	Recipient (object) or Casella postale (object) (Recipient or Casella postale) It is mandatory to enter the full name(nome, cognome) or business name(ragione sociale).
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	integer

Callbacks

Request samples

Content type

application/json

{"mittente": [{"ragione_sociale": "Openapi SRL",
"civico": "221",
"comune": "roma",
"dug": "via",
"indirizzo": "Filippo tommaso marinetti",
"cap": "00143",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]"
}
],
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Dante Alighieri",
"civico": "6",
"comune": "Roma",
"cap": "00143",
"provincia": "RM",
"nazione": "Italia"
}
],
"documento": ["https://www.soundczech.cz/temp/lorem-ipsum.pdf"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": true,
"autoconfirm": false
},
"callback": {"url": "https://your-server.site/123232",
"custom": 123
}
}

Response samples

201
421
422
500

Content type

application/json

{"data": [{"mittente": {"ragione_sociale": "Openapi SRL",
"civico": "221",
"comune": "roma",
"dug": "via",
"indirizzo": "Filippo tommaso marinetti",
"cap": "00143",
"provincia": "RM",
"nazione": "IT",
"email": "[email protected]",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Dante Alighieri",
"civico": "6",
"comune": "Roma",
"cap": "00143",
"provincia": "RM",
"nazione": "Italia",
"intestazione_completa": "Mario Rossi",
"zona": "AM",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["https://www.soundczech.cz/temp/lorem-ipsum.pdf"
],
"opzioni": {"fronteretro": false,
"colori": false,
"ar": true,
"autoconfirm": false
},
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"prodotto": "raccomandata_smart",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": false,
"state": "NEW",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.jpg",
"filename": "raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.pdf",
"pagine": 2,
"size": 49553,
"pricing": {"totale": {"importo_totale": 0.58
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.28,
"importo_unitario_netto": 0.22,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "Spedizione",
"importo_unitario_totale": 0.3,
"importo_unitario_netto": 0.3,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

List your single raccomandata smart

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state

string

Default: "<string>"

Example: state=NEW

If the option has been set, it returns a specifc schema with state equal to the one requested

Responses

Response Schema: application/json

	object (ExampleState)
	object
success	boolean
message	string
error	integer

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/raccomandate_smart/%7Bid%7D?state=NEW");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "ener bettica",
"civico": "14",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "lazio",
"civico": "12",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["test prova"
],
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 1687169681
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"prodotto": "raccomandata_smart",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": false,
"state": "NEW",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.jpg",
"filename": "raccomandata_smartu6pccgbnFNeRA69t7hvPDOKMa.pdf",
"pagine": 2,
"size": 49553,
"pricing": {"totale": {"importo_totale": 0.58
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.28,
"importo_unitario_netto": 0.22,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "Spedizione",
"importo_unitario_totale": 0.3,
"importo_unitario_netto": 0.3,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}

Confirm send Raccomandata Smart

Confirm sending a mail that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406
421

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "romagna",
"civico": "12",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "alighieri",
"civico": "15",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["test prova"
],
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 1687169681
},
"prodotto": "raccomandata_smart",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/raccomandata_smartyvSPArFg2S7ccrrK99YIuyItJ.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/raccomandata_smartyvSPArFg2S7ccrrK99YIuyItJ.jpg",
"filename": "raccomandata_smartyvSPArFg2S7ccrrK99YIuyItJ.pdf",
"pagine": 1,
"size": 6840,
"pricing": {"totale": {"importo_totale": 2.2
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.29,
"importo_unitario_netto": 0.23,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "spedizione",
"importo_unitario_totale": 1.91,
"importo_unitario_netto": 1.91,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"confirmed_timestamp": "1687169682,",
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}

Posta Massiva

List your posta_massiva

Authorizations:

bearerAuth

Responses

Response Schema: application/json

	Array of objects[ items ]
message	string
success	boolean
error	integer

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/posta_massiva/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi"
},
"creation_timestamp": 1657169682,
"update_timestamp": 1676901090,
"confirmed": false,
"state": "SENT",
"id": "xxxxxxxe557d71a5b600ee11d"
},
{"mittente": {"nome": "Fabio",
"email": "[email protected]",
"cognome": "verdi"
},
"creation_timestamp": 1657169682,
"update_timestamp": 1676901090,
"confirmed": false,
"state": "NEW",
"id": "xxxxxxxe557d71a5b600ee14d"
},
{"mittente": {"nome": "Sara",
"email": "[email protected]",
"cognome": "Rossi"
},
"creation_timestamp": 1657169682,
"update_timestamp": 1676901090,
"confirmed": false,
"state": "NEW",
"id": "xxxxxxxe557d71a5b6005e13d"
}
],
"message": "3 Risultati",
"success": true,
"error": null
}

Create your request

Send a posta_massiva. You should provide information about the sender and the receiver(s) in the post body. Additionally, the "autoconfirm" parameter can be set to false to save it for a later confirmation with a PATCH request, while you do custom logic with the response.

Authorizations:

bearerAuth

Request Body schema: application/json

	object
	object
	Recipient (object) or Casella postale (object) (Recipient or Casella postale) It is mandatory to enter the full name(nome, cognome) or business name(ragione sociale).
	Array of strings or string (documento) The document can either be a string or an array of strings in plain text. The strings can either be: Plain text Formatted in HTML, with style, header tags etc.. An URL pointing to either a webpage, a PDF or an image file (urls must start with http). The content is deduced from the "Content-Type" header A base64-encoded PDF file. Encoded strings are deducted by the base64 content header `data:application/pdf;base64,`: basically, in order to mark a string as a base64-encoded content, you should prepend the aforementioned string to the output. The request will return an error if the decoding process fails on the server The service analyses the "documento" (document) field, merges all the strings/document/images in different pages, compresses it slightly (if possible) and generates a single PDF file. The maximum size for a PDF document, after our compression, is 5 MB for every products execept Posta 4 PRO, Posta Massiva and Raccomandata Smart (these 3 products accept up to 15 MB maximum). The maximum number of pages is currently 50, or 100 is using the `fronteretro` option.
	object (callback) This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	integer

Callbacks

Request samples

Content type

application/json

{"mittente": {"nome": "Mario",
"cognome": "Rossi",
"dug": "Via",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "Italia",
"email": "[email protected]"
},
"destinatari": [{"nome": "Mario",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Morandi",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RM",
"nazione": "Italia"
}
],
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": false,
"autoconfirm": false
}
}

Response samples

201
421
422
500

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Dante Alighieri",
"civico": "1",
"comune": "Roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "Morandi",
"civico": "6",
"comune": "Roma",
"cap": "00101",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["Example document"
],
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": false
},
"prodotto": "posta_massiva",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": false,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.jpg",
"filename": "posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.pdf",
"pagine": 1,
"size": 6849,
"pricing": {"totale": {"importo_totale": 0.74
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.29,
"importo_unitario_netto": 0.23,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "Spedizione",
"importo_unitario_totale": 0.45,
"importo_unitario_netto": 0.45,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}

Callback payload samples

Callback

POST: {$request.body#/opzioni/callback_url}

Content type

application/json

{"mittente": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string"
},
"destinatari": {"nome": "string",
"email": "string",
"cognome": "string",
"dug": "string",
"indirizzo": "string",
"civico": "string",
"comune": "string",
"cap": 0,
"provincia": "string",
"nazione": "string",
"intestazione_completa": "string",
"id": "string",
"state": "string"
},
"documento": ["string"
],
"opzioni": {"fronteretro": true,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 0
},
"prodotto": "string",
"creation_timestamp": 0,
"update_timestamp": 0,
"username": "string",
"confirmed": true,
"state": "string",
"documento_validato": {"pdf": "string",
"jpg": "string",
"filename": "string",
"pagine": 0,
"size": 0
},
"pricing": {"totale": {"importo_totale": 0
},
"dettaglio": [{"codice_servizio": "string",
"descrizione_servizio": "string",
"importo_unitario_totale": 0,
"importo_unitario_netto": 0,
"importo_unitario_iva": 0,
"quantita": 0
}
]
},
"confirmed_timestamp": 0,
"id": "string"
}

List your single posta_massiva

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

query Parameters

state

string

Default: "<string>"

Example: state=NEW

If the option has been set, it returns a specifc schema with state equal to the one requested

Responses

Response Schema: application/json

	object
success	boolean
message	string
error	integer

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://ws.ufficiopostale.com/posta_massiva/%7Bid%7D?state=NEW");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

200
404

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "trastevere",
"civico": "8",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "ener bettica",
"civico": "7",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["test prova"
],
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 1687169681
},
"callback": {"url": "https://your-server.site/123232",
"custom": 123
},
"prodotto": "posta_massiva",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": false,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.jpg",
"filename": "posta_massivaCw4wGmsHe9ddsD2RAB2ZyMdUm.pdf",
"pagine": 1,
"size": 6849,
"pricing": {"totale": {"importo_totale": 0.74
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.29,
"importo_unitario_netto": 0.23,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "Spedizione",
"importo_unitario_totale": 0.45,
"importo_unitario_netto": 0.45,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}

Confirm send Posta Massiva

Confirm sending a mail that was created with "autoconfirm = false"

Authorizations:

bearerAuth

path Parameters

id

required

string

Default: "<string>"

Request Body schema: application/json

confirmed

boolean

Default: "<boolean>"

Responses

Request samples

Content type

application/json

{"confirmed": true
}

Response samples

202
406
421

Content type

application/json

{"data": [{"mittente": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "ener bettica",
"civico": "7",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi"
},
"destinatari": {"nome": "Mario",
"email": "[email protected]",
"cognome": "Rossi",
"dug": "via",
"indirizzo": "umbria",
"civico": "10",
"comune": "roma",
"cap": "00100",
"provincia": "RM",
"nazione": "IT",
"intestazione_completa": "Mario Rossi",
"id": "xxxxxxxe557d71a5b600ee17d",
"state": "NEW"
},
"documento": ["test prova"
],
"opzioni": {"fronteretro": false,
"colori": true,
"autoconfirm": true,
"timestamp_invio": 1687169681
},
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"prodotto": "posta_massiva",
"creation_timestamp": 1687169678,
"update_timestamp": 1687169682,
"username": "[email protected]",
"confirmed": true,
"state": "CONFIRMED",
"documento_validato": {"pdf": "https://test.ws.ufficiopostale.com/Up/pdf/posta_massivayvSPArFg2S7ccrrK99YIuyItJ.pdf",
"jpg": "https://test.ws.ufficiopostale.com/Up/jpg/posta_massivayvSPArFg2S7ccrrK99YIuyItJ.jpg",
"filename": "posta_massivayvSPArFg2S7ccrrK99YIuyItJ.pdf",
"pagine": 1,
"size": 6840,
"callback": {"method": "JSON",
"url": "https://your-webhook.site/",
"user_id": "",
"username": "",
"field": "",
"headers": {"chiave": "valore"
},
"data": { },
"retry": 0,
"scope": null,
"domain": null,
"custom": null
},
"pricing": {"totale": {"importo_totale": 2.2
},
"dettaglio": [{"codice_servizio": "STAMPA",
"descrizione_servizio": "Costo Stampa",
"importo_unitario_totale": 0.29,
"importo_unitario_netto": 0.23,
"importo_unitario_iva": 0.06,
"quantita": 1
},
{"codice_servizio": "spedizione",
"descrizione_servizio": "spedizione",
"importo_unitario_totale": 1.91,
"importo_unitario_netto": 1.91,
"importo_unitario_iva": 0,
"quantita": 1
}
]
},
"confirmed_timestamp": "1687169682,",
"id": "xxxxxxxe557d71a5b600ee13d"
}
}
],
"success": true,
"message": "",
"error": null
}