unopost

API x402

Spedire una lettera dal codice, pagare in USDC

App e agenti IA possono spedire una lettera ovunque in Australia e pagare per singola lettera in USDC tramite x402. Niente account, chiave API o abbonamento: bastano un wallet e un client HTTP.

10 USDC a lettera con posta ordinaria20 USDC a lettera con Express Post

Un solo prezzo fino a 20 pagine non piegate, GST inclusa. Pagamento in USDC su Base, gas a nostro carico.

Guida rapidaSpecifica OpenAPI

Perché spedire lettere tramite x402?

La stessa lettera del sito web, pagata via HTTP.

  • Senza account né chiave API Nessuna registrazione. Il codice crea una lettera, riceve un prezzo e paga con un pagamento USDC firmato.
  • Un prezzo fisso a lettera 20 USDC con Express Post, non piegata in busta B4, oppure 10 USDC con posta ordinaria, piegata per entrare nella cassetta delle lettere: il prezzo comprende stampa, busta, affrancatura e tracciamento fino a 12 pagine piegate o 20 non piegate, poi 0.30 USDC a pagina. GST inclusa, e il gas lo paghiamo noi.
  • La stessa lettera del sito web Stampata così come caricata su A4 da 80 g/m², tracciata e spedita lo stesso giorno lavorativo se pagata entro le 14:30 (ora di Melbourne).
  • Rimborsata se non può essere spedita Se non riusciamo a spedirla, rimborsiamo per intero, in USDC, il wallet che ha pagato. Una lettera che annulliamo viene rimborsata allo stesso modo.

A chi è rivolta

  • Agenti IA Un agente che gestisce una controversia sulla cauzione, una richiesta di indennizzo assicurativo o un reclamo al comune può spedire la lettera da sé e pagare dal proprio wallet.
  • App e script Software di gestione immobiliare, legale e di fatturazione che spedisce lettere, senza un conto esercente né un piano mensile.

Guida rapida

  1. Creare una lettera
  2. Caricare il documento
  3. Recuperare una lettera
  4. Pagare e spedire
  5. Seguire la lettera

Cinque richieste portano una lettera dal codice alla posta. Non servono account né chiavi: ci basta il pagamento.

send-letter.sh
# 1. Create the letter
curl -X POST https://unopost.com.au/api/x402 \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "notice.pdf",
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "service": "express",
  "signature": true
}'

# 2. Upload the document to the uploadUrl you got back
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @notice.pdf

# 3. Poll until the status is ready_to_send, and check the price
curl https://unopost.com.au/api/x402/$JOB_ID

# 4. Ask to send it: the 402 says what to pay
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send

# 5. Sign the payment with an x402 client, and send it again
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE"

Endpoint

Gli endpoint sono relativi a https://unopost.com.au. Richieste e risposte sono in JSON; gli errori hanno la forma {"error": "..."}. Riferimento completo: la specifica OpenAPI.

URL di base
https://unopost.com.au
POST/api/x402Crea una lettera. Gratuito.PUTuploadUrlCarica il documento sul link firmato della lettera.GET/api/x402/{jobId}Restituisce stato, prezzo e tracciamento di una lettera.POST/api/x402/{jobId}/sendSi paga in USDC e la lettera va in stampa.

Creare una lettera

POST/api/x402

Inviare con POST il nome del file, l'indirizzo del destinatario e l'indirizzo del mittente. Si ottengono un jobId, un uploadUrl firmato e gli URL per controllare e pagare la lettera.

Corpo della richiesta

fileNamestring · obbligatorio
Il nome del file con la sua estensione: .pdf, .doc, .docx, .jpg, .jpeg o .png.
recipientAddress · obbligatorio
L'indirizzo a cui spedire la lettera.
senderAddress · obbligatorio
L'indirizzo del mittente, stampato sulla busta perché la posta non recapitabile torni indietro.
servicestring · facoltativo
"express" per Express Post (predefinito) oppure "regular" per la posta ordinaria.
duplexboolean · facoltativo
Stampa fronte-retro. Il valore predefinito è false. Le dichiarazioni giurate (statutory declaration) sono sempre stampate solo fronte.
monoboolean · facoltativo
Stampa in bianco e nero. Il valore predefinito è false: un documento che contiene colore viene stampato a colori.
stapleboolean · facoltativo
Pinzatura delle pagine, una volta nell'angolo in alto a sinistra. Solo per documenti fino a 12 pagine; uno più lungo viene rifiutato al calcolo del prezzo. Il valore predefinito è false.
foldboolean · facoltativo
Solo Express Post: piega la lettera in una busta C5 invece di spedirla non piegata in una B4, senza costi aggiuntivi. Ignorato per i documenti di più di 20 pagine, che viaggiano non piegati. Le lettere di posta ordinaria sono sempre piegate.
signatureboolean · facoltativo
Firma alla consegna, 6 USDC in più, con entrambi i servizi. Con regular, la lettera viaggia con Posta raccomandata.

Indirizzo

Il destinatario deve trovarsi in Australia. L'indirizzo del mittente può essere ovunque: indicandone il paese, il codice postale diventa facoltativo. Ogni riga può contenere fino a 40 caratteri.

namestring · facoltativo
Nome e cognome della persona.
companystring · facoltativo
Un'azienda o un'organizzazione.
line1string · obbligatorio
L'indirizzo civico, oppure una casella postale come "PO Box 123".
line2string · facoltativo
Una seconda riga dell'indirizzo.
suburbstring · obbligatorio
Il sobborgo o la località.
statestring · facoltativo
In Australia va omesso: lo determina il codice postale. Se indicato, uno tra ACT, NSW, NT, QLD, SA, TAS, VIC o WA, corrispondente al codice postale.
postcodestring · obbligatorio
Quattro cifre.
countrystring · facoltativo
Solo per l'indirizzo del mittente. Va omesso per l'Australia.
Richiesta
curl -X POST https://unopost.com.au/api/x402 \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "notice.pdf",
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "service": "express",
  "signature": true
}'
Risposta 200
{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "uploadUrl": "https://unopost.com.au/uploads/019d7a7f-a183-752d-9b3b-11511179033b/notice.pdf?Expires=...&Signature=...&Key-Pair-Id=...",
  "statusUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b",
  "sendUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b/send",
  "status": "awaiting_upload"
}

Caricare il documento

PUTuploadUrl

Inviare con PUT i byte grezzi del file a uploadUrl entro 15 minuti. Fino a 50 MB e 80 pagine. L'impaginazione in A4 inizia non appena il caricamento arriva; non c'è nient'altro da chiamare.

Richiesta
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @notice.pdf

Recuperare una lettera

GET/api/x402/{jobId}

Attendere il prezzo

Interrogare ogni pochi secondi finché status non è ready_to_send. A quel punto la risposta contiene il numero di pagine, il prezzo in payment, il sendUrl e un previewUrl per il PDF pronto per la stampa, da controllare prima di pagare.

fold ora segue il servizio, true per la posta ordinaria e false per Express Post, e duplex può essere false: le dichiarazioni giurate (statutory declaration) sono stampate solo fronte. Una lettera di posta ordinaria di oltre 12 pagine viene rifiutata al momento del calcolo del prezzo.

Seguire la lettera

Continuare a interrogare, meno spesso, finché la lettera non è posted e poi delivered. Non ci sono email: ogni aggiornamento compare nello stato.

Richiesta
curl https://unopost.com.au/api/x402/$JOB_ID
Risposta 200 · ready_to_send
{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "service": "express",
  "duplex": false,
  "mono": false,
  "fold": false,
  "signature": true,
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "pageCount": 3,
  "status": "ready_to_send",
  "previewUrl": "/preview/019d7a7f-a183-752d-9b3b-11511179033b/notice.pdf?Expires=...&Signature=...&Key-Pair-Id=...",
  "payment": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountAtomic": "20000000",
    "amountDisplay": "20 USDC",
    "payTo": "0x1111111111111111111111111111111111111111",
    "expiresAt": "2026-09-25T02:15:00Z"
  },
  "sendUrl": "/api/x402/019d7a7f-a183-752d-9b3b-11511179033b/send"
}
Risposta 200 · posted
{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "service": "express",
  "duplex": false,
  "mono": false,
  "fold": false,
  "signature": true,
  "recipient": {
    "name": "Ruth Mitchell",
    "line1": "7 High Street",
    "suburb": "Echuca",
    "postcode": "3564"
  },
  "sender": {
    "name": "Sam Nguyen",
    "company": "Nguyen Property",
    "line1": "14 Carnarvon Street",
    "suburb": "Broome",
    "postcode": "6725"
  },
  "pageCount": 3,
  "status": "posted",
  "providerReference": "LTR-8F3A21C9"
}

Pagare e spedire

POST/api/x402/{jobId}/send

Inviare un POST a sendUrl senza pagamento. La risposta è 402 Payment Required, con i requisiti di pagamento codificati in base64 nell'intestazione PAYMENT-REQUIRED.

Firmare il pagamento come descritto dal protocollo x402 (o lasciarlo fare a una libreria client x402) e reinviare la richiesta con il payload in un'intestazione PAYMENT-SIGNATURE. Verifichiamo e regoliamo il pagamento, e la lettera va in stampa. L'intestazione PAYMENT-RESPONSE contiene il regolamento.

Un 409 con job not ready to send subito dopo ready_to_send? Attendere un momento e riprovare. Una nuova chiamata dopo il pagamento restituisce lo stato senza addebitare due volte.

Richiesta
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send
Risposta 402
HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...

{
  "error": "payment required"
}
Intestazione PAYMENT-REQUIRED, decodificata da base64
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "20000000",
      "payTo": "0x1111111111111111111111111111111111111111",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
Richiesta
curl -i -X POST https://unopost.com.au/api/x402/$JOB_ID/send \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE"
Risposta 202
HTTP/2 202
payment-response: eyJzdWNjZXNzIjp0cnVlLC...

{
  "jobId": "019d7a7f-a183-752d-9b3b-11511179033b",
  "status": "sending"
}

Stati

awaiting_upload
In attesa del file.
processing
Impaginazione del documento in A4 e calcolo del prezzo.
ready_to_send
Prezzo calcolato, in attesa di pagamento. Il preventivo vale 7 giorni.
sending
Pagata e in coda di stampa.
retrying
La stampa ha incontrato un problema; riproviamo automaticamente.
posted
Stampata e affidata ad Australia Post.
delivered
Consegnata da Australia Post. Il documento è stato eliminato alla spedizione.
failed
Non spedita; il motivo è in error, per esempio un preventivo scaduto senza pagamento. Una lettera pagata che non può essere spedita viene rimborsata per intero.
refunded
Il pagamento è tornato al wallet che lo aveva effettuato.

Errori

400
Richiesta non valida: per esempio un campo mancante, un tipo di file non supportato, una riga dell'indirizzo di oltre 40 caratteri, un codice postale che non appartiene allo stato, la firma alla consegna con la posta ordinaria, o una lettera di posta ordinaria di più di 12 pagine.
402
È richiesto il pagamento, oppure non è stato possibile verificare o regolare il pagamento. error ne indica il motivo.
404
Non esiste alcuna lettera con quel jobId.
409
job not ready to send: attendere ready_to_send e riprovare. quote expired: creare di nuovo la lettera.

Domande frequenti

Che cos'è x402?

Un protocollo aperto per pagare via HTTP. Il server risponde 402 Payment Required con un prezzo; il client firma un pagamento in stablecoin e reinvia la richiesta. Niente account, carta o fattura.

Che cosa serve?

Un wallet su Base con USDC a sufficienza e un client HTTP. Non servono ETH per il gas: il pagamento è un'autorizzazione firmata al trasferimento di USDC, e la commissione di rete è a nostro carico.

Quanto costa una lettera?

20 USDC con Express Post fino a 20 pagine, poi 0.30 USDC a pagina, oppure 10 USDC con posta ordinaria per una lettera fino a 12 pagine, GST inclusa. La firma alla consegna costa 6 USDC in più con entrambi i servizi; la posta ordinaria con firma è la Posta raccomandata, 16 USDC. Il tracciamento, la stampa fronte-retro e in bianco e nero, la pinzatura fino a 12 pagine e la piegatura di una lettera Express Post in una busta DL con finestra sono gratuiti. La risposta di stato mostra il prezzo esatto prima del pagamento.

Si può controllare la lettera prima di pagare?

Sì. Quando è pronta per l'invio, previewUrl è il PDF pronto per la stampa, impaginato in A4 esattamente come verrà stampato. Non viene addebitato nulla fino al pagamento.

Quando viene spedita e quanto impiega ad arrivare?

Le lettere pagate entro le 14:30 (ora di Melbourne) di un giorno lavorativo sono spedite il giorno stesso; quelle pagate più tardi, il giorno lavorativo successivo. Express Post arriva di norma il giorno lavorativo successivo all'interno della rete Express Post, la posta ordinaria in 3-7 giorni lavorativi.

E se la lettera non può essere spedita?

Lo stato diventa failed e rimborsiamo l'intero importo in USDC al wallet che ha pagato, sia che l'invio sia fallito sia che l'abbiamo annullato noi. Per qualsiasi altra questione, scrivere a support@unopost.com.au indicando il jobId.

Che cosa succede al documento?

È cifrato in transito e viene eliminato definitivamente, insieme alla copia pronta per la stampa, una volta che la lettera è affidata ad Australia Post. Se una lettera non viene pagata o non può essere spedita, il documento è eliminato dopo 14 giorni.

Dove possono essere spedite le lettere?

A qualsiasi indirizzo in Australia, comprese le caselle postali (PO Box), in ogni stato e territorio. L'API non spedisce all'estero.

Chi è responsabile di ciò che invia un agente?

Chi paga. Ogni lettera pagata dal proprio wallet è propria, compresa quella scritta e inviata da un agente su proprie istruzioni, e occorre avere il diritto di inviarne il contenuto. Le nostre condizioni elencano ciò che non può viaggiare per posta: sostituzione di persona, molestie, truffe, pubblicità non richiesta in massa e tutto ciò che viola un provvedimento giudiziario. Annulliamo le lettere che violano queste regole e le rimborsiamo per intero. Chi spedisce per conto di altri risponde del loro documento come se fosse proprio.

Prezzi

VocePrezzo
Posta ordinaria, piegata per entrare nella cassetta delle lettere: fino a 12 pagine10 USDC
Posta raccomandata, cioè posta ordinaria con firma alla consegna: fino a 12 pagine16 USDC
Express Post, non piegata in busta B4: 20 pagine incluse, poi 0.30 USDC per ogni pagina in più20 USDC
Express Post con firma alla consegna: 20 pagine incluse, poi 0.30 USDC per ogni pagina in più26 USDC
Tracciamento, stampa a colori, fronte-retro o in bianco e nero, e pinzaturaGratis
Commissione di rete (gas)A nostro carico

I prezzi sono in USDC su Base. Il prezzo viene fissato una volta impaginato il documento in A4; i preventivi valgono 7 giorni.

I prezzi possono cambiare. L'uso di questo servizio è soggetto alle nostre Condizioni di servizio e alla nostra Informativa sulla privacy.