Run with Postman
logo
Documentation Powered by Redocly

Ufficio Postale

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

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

  1. Create a new mail with a POST request
  2. Check the prices and confirm it with a PATCH, or use autoconfirm: true
  3. 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

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

    Content type
    application/json
    {
    • "data": [
      ],
    • "message": "1 Risultati",
    • "success": true,
    • "error": null
    }

    Send a Raccomandata. You should provide informatio

    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

    Authorizations:
    bearerAuth
      Request Body schema: application/json
      object
      object
      Array of Recipient (object) or Casella postale (object) <= 2 items [ items ]
      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.

      The maximum number of pages is currently 50, or 100 is using the fronteretro option.

      Responses

      Response Schema: application/json
      object
      object
      Array of objects[ items ]
      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.

      The maximum number of pages is currently 50, or 100 is using the fronteretro option.

      object (documento_validato)

      The output of the document generation process.

      Request samples

      Content type
      application/json
      {
      • "mittente": {
        },
      • "destinatari": [
        ],
      • "documento": [
        ],
      • "opzioni": {
        }
      }

      Response samples

      Content type
      application/json
      {
      • "data": [