My Postal Network

API per il gestionale dei clienti

Il vostro gestionale o il vostro sito invia le lettere all'agenzia e ne segue la consegna, senza riscriverle a mano.

Come iniziare

La chiave API ve la dà la vostra agenzia postale. Va mandata in ogni richiesta nell'intestazione X-Api-Key; tenetela riservata come una password (se pensate che qualcuno l'abbia vista, chiedete all'agenzia di revocarla e generarne un'altra).

Indirizzo di base: https://connect.mypostalnetwork.it/api/v1
Formato: JSON (UTF-8), nomi dei campi in camelCase, date in formato ISO 8601 con il fuso orario (ora italiana, es. 2026-10-07T14:05:12+02:00).
Connessione: solo HTTPS.

curl -H "X-Api-Key: mpn_LaVostraChiave" https://connect.mypostalnetwork.it/api/v1/info

Le operazioni

GET /info

Verifica la chiave: risponde con il nome del cliente e dell'agenzia.

{ "cliente": "Rossi Mario S.r.l.", "agenzia": "Agenzia Demo", "versione": "1" }

GET /prodotti

I prodotti che potete usare, con il vostro prezzo (IVA esclusa). L'id va indicato in prodottoId quando create una lettera. tracciato dice se la lettera riceve un codice a barre da seguire.

[
  { "id": 11713, "nome": "Raccomandata A/R", "fascia": "0,00-20,00", "prezzo": 4.30, "iva": 22, "tracciato": true },
  { "id": 11720, "nome": "Posta ordinaria",  "fascia": "0,00-20,00", "prezzo": 0.90, "iva": 22, "tracciato": false }
]

POST /lettere

Crea fino a 500 lettere per chiamata. Finiscono tutte nella distinta del giorno «inviata dal gestionale», che l'agenzia lavora come le altre (etichette, ritiro, consegna). Se una lettera non va bene non ne viene creata nessuna: la risposta 400 elenca tutti gli errori.

Il riferimento (per esempio il vostro numero d'ordine, fino a 100 caratteri) è facoltativo ma consigliato: se rimandate una lettera con un riferimento già usato non ne viene creata un'altra, vi torna quella di prima con giaPresente: true. Così potete ripetere senza timore una richiesta andata in errore di rete.

POST https://connect.mypostalnetwork.it/api/v1/lettere
X-Api-Key: mpn_LaVostraChiave
Content-Type: application/json

{
  "lettere": [
    {
      "riferimento": "ORD-2026-1001",
      "prodottoId": 11713,
      "destinatario": {
        "nome": "Mario Bianchi", "nome2": "c/o Studio Verdi",
        "via": "Via Roma 10", "cap": "50122", "citta": "Firenze", "provincia": "FI",
        "email": "mario.bianchi@example.com", "cellulare": "+39 333 123 4567"
      }
    }
  ]
}

Risposta 201 (oppure 200 se tutte le lettere erano già presenti):

{
  "distinta": { "id": 17070, "numero": 245, "data": "2026-10-07T14:05:12+02:00" },
  "lettere": [ { "id": 134400, "riferimento": "ORD-2026-1001", "codiceABarre": "001260000412", "giaPresente": false } ]
}

Campo	Obbligatorio	Note
`prodottoId`	sì	da `GET /prodotti`
`destinatario.nome`	sì	fino a 150 caratteri; `nome2` per la seconda riga
`destinatario.via`	sì	fino a 150 caratteri, con il numero civico
`destinatario.cap`, `citta`	sì	CAP fino a 5 caratteri, città fino a 50
`destinatario.provincia`	no	sigla, per esempio `FI`
`destinatario.email`	no	riceve gli avvisi di consegna, se l'agenzia li ha attivati per voi
`destinatario.cellulare`	no	riceve gli avvisi via SMS, se l'agenzia li ha attivati per voi; un cellulare italiano o con il prefisso internazionale
`riferimento`	no	vostro codice, fino a 100 caratteri, unico
`mittente`	no	`nome`, `via`, `cap`, `citta`, `provincia`: solo se da stampare diverso dal vostro
`restituireA`	no	a chi rendere la lettera se non si consegna, fino a 250 caratteri
`amministratoId`	no	fuori dall'elenco, per gli amministratori (es. di condominio): l'amministrato mittente

GET /lettere

Le vostre lettere con lo stato e l'ultimo esito, dalla più recente (al massimo 1000). Filtri, tutti facoltativi:

codice: il codice a barre;
riferimento: il vostro riferimento;
dal, al: date della distinta (AAAA-MM-GG), predefinito gli ultimi 30 giorni.

curl -H "X-Api-Key: mpn_LaVostraChiave" "https://connect.mypostalnetwork.it/api/v1/lettere?riferimento=ORD-2026-1001"

[
  {
    "id": 134400, "codiceABarre": "001260000412", "riferimento": "ORD-2026-1001",
    "prodotto": "Raccomandata A/R", "destinatario": "Mario Bianchi c/o Studio Verdi",
    "indirizzo": "Via Roma 10 50122 Firenze (FI)", "dataDistinta": "2026-10-07T14:05:12+02:00", "numeroDistinta": 245,
    "stato": "consegnata",
    "ultimoEsito": { "data": "2026-10-08T10:41:00+02:00", "descrizione": "Consegnata", "categoria": "consegnata" }
  }
]

GET /lettere/{id}

Una lettera con tutti i suoi esiti, dal più vecchio (campo esiti). 404 se la lettera non è vostra o non esiste.

Stati ed esiti

I nomi degli esiti li sceglie l'agenzia; la categoria dice cosa significano, e lo stato della lettera è la categoria dell'ultimo esito che non sia un semplice passaggio di lavorazione.

Stato / categoria	Significato
`in_lavorazione`	presa in carico o in consegna
`consegnata`	consegnata al destinatario (o ritirata)
`da_ritentare` (categoria `tentativo_non_riuscito`)	assente, in giacenza: la consegna si riprova
`non_recapitabile`	indirizzo inesatto, destinatario sconosciuto, rifiutata…
`affidata_ad_altri`	affidata a un altro vettore
`restituita`	non recapitabile e già resa al mittente

Errori e limiti

In caso di errore la risposta ha sempre un codice errore e un messaggio in italiano:

{
  "errore": "dati_non_validi",
  "messaggio": "La richiesta contiene dati non validi: nessuna lettera è stata creata.",
  "dettagli": [ { "lettera": 0, "campo": "destinatario.cap", "messaggio": "Campo obbligatorio." } ]
}

Codice HTTP	Quando
`400`	dati non validi (`dettagli` indica lettera, da 0, e campo)
`401`	chiave mancante, sbagliata o revocata, oppure API non compresa nel contratto dell'agenzia
`404`	lettera non trovata
`429`	più di 120 chiamate al minuto con la stessa chiave: riprovare dopo i secondi indicati in `Retry-After`
`500`	errore imprevisto: riprovare; se si ripete, sentire l'agenzia

Ogni chiamata viene registrata (ora, operazione, esito): l'agenzia vede l'elenco e può aiutarvi a capire un errore.