REST API

Documentazione API

Integra le etichette di spedizione nella tua applicazione con la nostra potente API REST. Ottieni tariffe in tempo reale, crea etichette e traccia le spedizioni in modo programmato.

Autenticazione

Tutte le richieste API richiedono l'autenticazione con la tua chiave e segreto API. Includi questi header in ogni richiesta:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Avviso di Sicurezza

Mantieni il tuo segreto API al sicuro. Non esporlo mai nel codice lato client o in repository pubblici.

Esempio di Richiesta

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Saldo Account

Controlla i saldi del tuo wallet crypto e la cronologia delle transazioni. L'API utilizza il tuo wallet crypto (BTC, LTC, LTCT) per i pagamenti.

GET

/api/v1/account/balance

Ottieni saldi e transazioni del wallet crypto

Parametri di Query

Parametro	Tipo	Obbligatorio	Descrizione
includeTransactions	`boolean`	Opzionale	Includi cronologia transazioni
currency	`string`	Opzionale	Filtra transazioni per valuta (BTC, LTC, LTCT)
limit	`number`	Opzionale	Numero di transazioni (default: 20, max: 100)

Esempio di Richiesta

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Risposta

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Aggiungi Fondi

Per aggiungere fondi al tuo wallet, visita la pagina Il Mio Wallet e deposita usando BTC, LTC o LTCT (testnet).

Verifica Indirizzo

Verifica e standardizza gli indirizzi di spedizione per garantire la consegnabilità.

POST

/api/v1/shipping/verify-address

Verifica e correggi un indirizzo di spedizione

Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
address	`Address`	Obbligatorio	Indirizzo da verificare
strict	`boolean`	Opzionale	Abilita modalità di verifica rigorosa

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Risposta

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Tariffe di Spedizione

Ottieni tariffe di spedizione in tempo reale da più corrieri inclusi USPS, UPS, FedEx e DHL.

POST

/api/v1/shipping/rates

Calcola le tariffe di spedizione per un pacco

Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
fromAddress	`Address`	Obbligatorio	Oggetto indirizzo mittente
toAddress	`Address`	Obbligatorio	Oggetto indirizzo destinatario
packageDetails	`Package`	Obbligatorio	Dimensioni e peso del pacco
carriers	`string[]`	Opzionale	Filtra per corrieri specifici (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opzionale	Obbligatorio per spedizioni internazionali

Oggetto Indirizzo

Parametro	Tipo	Obbligatorio	Descrizione
name	`string`	Obbligatorio	Nome completo
company	`string`	Opzionale	Nome azienda
street1	`string`	Obbligatorio	Indirizzo riga 1
street2	`string`	Opzionale	Indirizzo riga 2
city	`string`	Obbligatorio	Città
state	`string`	Obbligatorio	Codice stato/provincia
zip	`string`	Obbligatorio	CAP/Codice postale
country	`string`	Obbligatorio	Codice paese (US, CA, ecc.)
phone	`string`	Opzionale	Numero di telefono
email	`string`	Opzionale	Indirizzo email

Oggetto Pacco

Parametro	Tipo	Obbligatorio	Descrizione
length	`number`	Obbligatorio	Lunghezza in pollici
width	`number`	Obbligatorio	Larghezza in pollici
height	`number`	Obbligatorio	Altezza in pollici
weight	`number`	Obbligatorio	Peso in once

Oggetto CustomsInfo

Spedizioni Internazionali

Obbligatorio per spedizioni internazionali (quando fromAddress.country differisce da toAddress.country).

Parametro	Tipo	Obbligatorio	Descrizione
contents_type	`string`	Obbligatorio	Tipo di contenuto: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opzionale	Obbligatorio quando contents_type è 'other'
customs_certify	`boolean`	Obbligatorio	Deve essere true - certifica l'accuratezza della dichiarazione
customs_signer	`string`	Obbligatorio	Nome della persona che certifica la dichiarazione doganale
eel_pfc	`string`	Obbligatorio	Codice di esenzione all'esportazione (usa 'NOEEI 30.37(a)' per spedizioni sotto $2.500)
non_delivery_option	`string`	Obbligatorio	Cosa fare se non consegnabile: 'return' o 'abandon'
restriction_type	`string`	Obbligatorio	Tipo di restrizione: 'none', 'other', 'quarantine', o 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opzionale	Obbligatorio quando restriction_type non è 'none'
customs_items	`CustomsItem[]`	Obbligatorio	Array degli articoli spediti (1-100 articoli)

Oggetto CustomsItem

Parametro	Tipo	Obbligatorio	Descrizione
description	`string`	Obbligatorio	Descrizione dettagliata dell'articolo
quantity	`number`	Obbligatorio	Quantità di articoli (minimo: 1)
value	`number`	Obbligatorio	Valore in USD (deve essere maggiore di 0)
weight	`number`	Obbligatorio	Peso in once (deve essere maggiore di 0)
origin_country	`string`	Obbligatorio	Codice paese a 2 lettere (es., 'US', 'CN')
hs_tariff_number	`string`	Obbligatorio	Codice tariffario HS a 6-10 cifre

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Risposta

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

Esempio Spedizione Internazionale

Per spedizioni internazionali, includi l'oggetto customsInfo con le dichiarazioni degli articoli:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Crea Ordine

Crea e gestisci ordini di spedizione. Gli ordini contengono uno o più articoli di etichette di spedizione.

GET

/api/v1/orders

Elenca tutti gli ordini

POST

/api/v1/orders

Crea un nuovo ordine

GET

/api/v1/orders/{id}

Ottieni dettagli ordine

Elenca Ordini - Parametri di Query

Parametro	Tipo	Obbligatorio	Descrizione
limit	`number`	Opzionale	Numero di risultati (default: 50, max: 100)
offset	`number`	Opzionale	Offset paginazione

Crea Ordine - Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
items	`OrderItem[]`	Obbligatorio	Array degli articoli dell'ordine
email	`string`	Opzionale	Email del cliente
externalReference	`string`	Opzionale	Il tuo ID di riferimento

Oggetto OrderItem

API Semplificata

Solo shipmentId e rateId sono obbligatori. Indirizzi, dettagli del pacco e informazioni doganali vengono estratti automaticamente dalla spedizione.

Parametro	Tipo	Obbligatorio	Descrizione
shipmentId	`string`	Obbligatorio	ID spedizione dall'endpoint tariffe
rateId	`string`	Obbligatorio	ID tariffa dall'endpoint tariffe

Esempio: Crea Ordine

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Risposta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Acquista Etichette

Acquista etichette di spedizione per tutti gli articoli di un ordine. Le etichette vengono acquistate usando il saldo del tuo wallet crypto (BTC, LTC o LTCT).

POST

/api/v1/labels/purchase

Acquista etichette di spedizione per un ordine

Corpo della Richiesta

Pagamento Crypto

L'API convertirà il costo dell'etichetta in USD in crypto ai tassi correnti. Devi avere saldo sufficiente (incluso 10% di buffer per le fluttuazioni di prezzo).

Parametro	Tipo	Obbligatorio	Descrizione
orderId	`string`	Obbligatorio	ID ordine per acquistare etichette
currency	`string`	Opzionale	Valuta crypto per il pagamento (BTC, LTC, LTCT). Se non specificato, seleziona automaticamente la prima valuta con saldo sufficiente.

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Risposta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Saldo Insufficiente

Se il saldo del tuo wallet è troppo basso, l'API restituisce uno stato 402 con l'importo crypto richiesto.

Risposta Saldo Insufficiente

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Tracciamento

Traccia le spedizioni usando il codice di tracciamento delle etichette acquistate.

GET

/api/v1/tracking/{code}

Ottieni informazioni di tracciamento

Parametri di Percorso

Parametro	Tipo	Obbligatorio	Descrizione
code	`string`	Obbligatorio	Codice di tracciamento

Esempio di Richiesta

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Risposta

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Ricevi notifiche in tempo reale quando si verificano eventi, come la creazione di etichette o gli aggiornamenti di tracciamento.

GET

/api/v1/webhooks

Elenca webhooks registrati

POST

/api/v1/webhooks

Registra un nuovo webhook

GET

/api/v1/webhooks/{id}

Ottieni dettagli webhook

DELETE

/api/v1/webhooks/{id}

Elimina un webhook

Eventi Disponibili

label.created

Quando un'etichetta viene acquistata con successo

label.failed

Quando la generazione dell'etichetta fallisce

Registra Webhook - Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
webhookUrl	`string`	Obbligatorio	URL per ricevere eventi webhook
events	`string[]`	Obbligatorio	Array dei tipi di eventi da sottoscrivere

Esempio: Registra Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Risposta

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Verifica Firma Webhook

Ogni webhook include un header di firma per la verifica. Verifica la firma usando HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Esempio Payload Webhook

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

REST API

Documentazione API

Integra le etichette di spedizione nella tua applicazione con la nostra potente API REST. Ottieni tariffe in tempo reale, crea etichette e traccia le spedizioni in modo programmato.

Autenticazione

Tutte le richieste API richiedono l'autenticazione con la tua chiave e segreto API. Includi questi header in ogni richiesta:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Avviso di Sicurezza

Mantieni il tuo segreto API al sicuro. Non esporlo mai nel codice lato client o in repository pubblici.

Esempio di Richiesta

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Saldo Account

Controlla i saldi del tuo wallet crypto e la cronologia delle transazioni. L'API utilizza il tuo wallet crypto (BTC, LTC, LTCT) per i pagamenti.

GET

/api/v1/account/balance

Ottieni saldi e transazioni del wallet crypto

Parametri di Query

Parametro	Tipo	Obbligatorio	Descrizione
includeTransactions	`boolean`	Opzionale	Includi cronologia transazioni
currency	`string`	Opzionale	Filtra transazioni per valuta (BTC, LTC, LTCT)
limit	`number`	Opzionale	Numero di transazioni (default: 20, max: 100)

Esempio di Richiesta

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Risposta

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Aggiungi Fondi

Per aggiungere fondi al tuo wallet, visita la pagina Il Mio Wallet e deposita usando BTC, LTC o LTCT (testnet).

Verifica Indirizzo

Verifica e standardizza gli indirizzi di spedizione per garantire la consegnabilità.

POST

/api/v1/shipping/verify-address

Verifica e correggi un indirizzo di spedizione

Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
address	`Address`	Obbligatorio	Indirizzo da verificare
strict	`boolean`	Opzionale	Abilita modalità di verifica rigorosa

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Risposta

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Tariffe di Spedizione

Ottieni tariffe di spedizione in tempo reale da più corrieri inclusi USPS, UPS, FedEx e DHL.

POST

/api/v1/shipping/rates

Calcola le tariffe di spedizione per un pacco

Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
fromAddress	`Address`	Obbligatorio	Oggetto indirizzo mittente
toAddress	`Address`	Obbligatorio	Oggetto indirizzo destinatario
packageDetails	`Package`	Obbligatorio	Dimensioni e peso del pacco
carriers	`string[]`	Opzionale	Filtra per corrieri specifici (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opzionale	Obbligatorio per spedizioni internazionali

Oggetto Indirizzo

Parametro	Tipo	Obbligatorio	Descrizione
name	`string`	Obbligatorio	Nome completo
company	`string`	Opzionale	Nome azienda
street1	`string`	Obbligatorio	Indirizzo riga 1
street2	`string`	Opzionale	Indirizzo riga 2
city	`string`	Obbligatorio	Città
state	`string`	Obbligatorio	Codice stato/provincia
zip	`string`	Obbligatorio	CAP/Codice postale
country	`string`	Obbligatorio	Codice paese (US, CA, ecc.)
phone	`string`	Opzionale	Numero di telefono
email	`string`	Opzionale	Indirizzo email

Oggetto Pacco

Parametro	Tipo	Obbligatorio	Descrizione
length	`number`	Obbligatorio	Lunghezza in pollici
width	`number`	Obbligatorio	Larghezza in pollici
height	`number`	Obbligatorio	Altezza in pollici
weight	`number`	Obbligatorio	Peso in once

Oggetto CustomsInfo

Spedizioni Internazionali

Obbligatorio per spedizioni internazionali (quando fromAddress.country differisce da toAddress.country).

Parametro	Tipo	Obbligatorio	Descrizione
contents_type	`string`	Obbligatorio	Tipo di contenuto: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opzionale	Obbligatorio quando contents_type è 'other'
customs_certify	`boolean`	Obbligatorio	Deve essere true - certifica l'accuratezza della dichiarazione
customs_signer	`string`	Obbligatorio	Nome della persona che certifica la dichiarazione doganale
eel_pfc	`string`	Obbligatorio	Codice di esenzione all'esportazione (usa 'NOEEI 30.37(a)' per spedizioni sotto $2.500)
non_delivery_option	`string`	Obbligatorio	Cosa fare se non consegnabile: 'return' o 'abandon'
restriction_type	`string`	Obbligatorio	Tipo di restrizione: 'none', 'other', 'quarantine', o 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opzionale	Obbligatorio quando restriction_type non è 'none'
customs_items	`CustomsItem[]`	Obbligatorio	Array degli articoli spediti (1-100 articoli)

Oggetto CustomsItem

Parametro	Tipo	Obbligatorio	Descrizione
description	`string`	Obbligatorio	Descrizione dettagliata dell'articolo
quantity	`number`	Obbligatorio	Quantità di articoli (minimo: 1)
value	`number`	Obbligatorio	Valore in USD (deve essere maggiore di 0)
weight	`number`	Obbligatorio	Peso in once (deve essere maggiore di 0)
origin_country	`string`	Obbligatorio	Codice paese a 2 lettere (es., 'US', 'CN')
hs_tariff_number	`string`	Obbligatorio	Codice tariffario HS a 6-10 cifre

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Risposta

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

Esempio Spedizione Internazionale

Per spedizioni internazionali, includi l'oggetto customsInfo con le dichiarazioni degli articoli:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Crea Ordine

Crea e gestisci ordini di spedizione. Gli ordini contengono uno o più articoli di etichette di spedizione.

GET

/api/v1/orders

Elenca tutti gli ordini

POST

/api/v1/orders

Crea un nuovo ordine

GET

/api/v1/orders/{id}

Ottieni dettagli ordine

Elenca Ordini - Parametri di Query

Parametro	Tipo	Obbligatorio	Descrizione
limit	`number`	Opzionale	Numero di risultati (default: 50, max: 100)
offset	`number`	Opzionale	Offset paginazione

Crea Ordine - Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
items	`OrderItem[]`	Obbligatorio	Array degli articoli dell'ordine
email	`string`	Opzionale	Email del cliente
externalReference	`string`	Opzionale	Il tuo ID di riferimento

Oggetto OrderItem

API Semplificata

Solo shipmentId e rateId sono obbligatori. Indirizzi, dettagli del pacco e informazioni doganali vengono estratti automaticamente dalla spedizione.

Parametro	Tipo	Obbligatorio	Descrizione
shipmentId	`string`	Obbligatorio	ID spedizione dall'endpoint tariffe
rateId	`string`	Obbligatorio	ID tariffa dall'endpoint tariffe

Esempio: Crea Ordine

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Risposta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Acquista Etichette

Acquista etichette di spedizione per tutti gli articoli di un ordine. Le etichette vengono acquistate usando il saldo del tuo wallet crypto (BTC, LTC o LTCT).

POST

/api/v1/labels/purchase

Acquista etichette di spedizione per un ordine

Corpo della Richiesta

Pagamento Crypto

L'API convertirà il costo dell'etichetta in USD in crypto ai tassi correnti. Devi avere saldo sufficiente (incluso 10% di buffer per le fluttuazioni di prezzo).

Parametro	Tipo	Obbligatorio	Descrizione
orderId	`string`	Obbligatorio	ID ordine per acquistare etichette
currency	`string`	Opzionale	Valuta crypto per il pagamento (BTC, LTC, LTCT). Se non specificato, seleziona automaticamente la prima valuta con saldo sufficiente.

Esempio di Richiesta

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Risposta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Saldo Insufficiente

Se il saldo del tuo wallet è troppo basso, l'API restituisce uno stato 402 con l'importo crypto richiesto.

Risposta Saldo Insufficiente

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Tracciamento

Traccia le spedizioni usando il codice di tracciamento delle etichette acquistate.

GET

/api/v1/tracking/{code}

Ottieni informazioni di tracciamento

Parametri di Percorso

Parametro	Tipo	Obbligatorio	Descrizione
code	`string`	Obbligatorio	Codice di tracciamento

Esempio di Richiesta

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Risposta

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Ricevi notifiche in tempo reale quando si verificano eventi, come la creazione di etichette o gli aggiornamenti di tracciamento.

GET

/api/v1/webhooks

Elenca webhooks registrati

POST

/api/v1/webhooks

Registra un nuovo webhook

GET

/api/v1/webhooks/{id}

Ottieni dettagli webhook

DELETE

/api/v1/webhooks/{id}

Elimina un webhook

Eventi Disponibili

label.created

Quando un'etichetta viene acquistata con successo

label.failed

Quando la generazione dell'etichetta fallisce

Registra Webhook - Corpo della Richiesta

Parametro	Tipo	Obbligatorio	Descrizione
webhookUrl	`string`	Obbligatorio	URL per ricevere eventi webhook
events	`string[]`	Obbligatorio	Array dei tipi di eventi da sottoscrivere

Esempio: Registra Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Risposta

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Verifica Firma Webhook

Ogni webhook include un header di firma per la verifica. Verifica la firma usando HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Esempio Payload Webhook

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

Documentazione API

Autenticazione

Esempio di Richiesta

Saldo Account

Parametri di Query

Esempio di Richiesta

Risposta

Verifica Indirizzo

Corpo della Richiesta

Esempio di Richiesta

Risposta

Tariffe di Spedizione

Corpo della Richiesta

Oggetto Indirizzo

Oggetto Pacco

Oggetto CustomsInfo

Oggetto CustomsItem

Esempio di Richiesta

Risposta

Esempio Spedizione Internazionale

Crea Ordine

Elenca Ordini - Parametri di Query

Crea Ordine - Corpo della Richiesta

Oggetto OrderItem

Esempio: Crea Ordine

Risposta

Acquista Etichette

Corpo della Richiesta

Esempio di Richiesta

Risposta

Risposta Saldo Insufficiente

Tracciamento

Parametri di Percorso

Esempio di Richiesta

Risposta

Webhooks

Eventi Disponibili

Registra Webhook - Corpo della Richiesta

Esempio: Registra Webhook

Risposta

Verifica Firma Webhook

Esempio Payload Webhook

Carrello

Il tuo carrello è vuoto

Documentazione API

Autenticazione

Esempio di Richiesta

Saldo Account

Parametri di Query

Esempio di Richiesta

Risposta

Verifica Indirizzo

Corpo della Richiesta

Esempio di Richiesta

Risposta

Tariffe di Spedizione

Corpo della Richiesta

Oggetto Indirizzo

Oggetto Pacco

Oggetto CustomsInfo

Oggetto CustomsItem

Esempio di Richiesta

Risposta

Esempio Spedizione Internazionale

Crea Ordine

Elenca Ordini - Parametri di Query

Crea Ordine - Corpo della Richiesta

Oggetto OrderItem

Esempio: Crea Ordine

Risposta

Acquista Etichette

Corpo della Richiesta

Esempio di Richiesta

Risposta

Risposta Saldo Insufficiente

Tracciamento

Parametri di Percorso

Esempio di Richiesta

Risposta

Webhooks