REST API

API-Dokumentation

Integrieren Sie Versandetiketten in Ihre Anwendung mit unserer leistungsstarken REST API. Erhalten Sie Echtzeit-Tarife, erstellen Sie Etiketten und verfolgen Sie Sendungen programmatisch.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit Ihrem API-Schlüssel und Geheimnis. Fügen Sie diese Header in jede Anfrage ein:

headers

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

Sicherheitshinweis

Halten Sie Ihr API-Geheimnis sicher. Geben Sie es niemals in clientseitigem Code oder öffentlichen Repositories preis.

Beispielanfrage

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"

Kontostand

Überprüfen Sie Ihre Krypto-Wallet-Guthaben und Transaktionshistorie. Die API verwendet Ihre Krypto-Wallet (BTC, LTC, LTCT) für Zahlungen.

GET

/api/v1/account/balance

Krypto-Wallet-Guthaben und Transaktionen abrufen

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
includeTransactions	`boolean`	Optional	Transaktionshistorie einschließen
currency	`string`	Optional	Transaktionen nach Währung filtern (BTC, LTC, LTCT)
limit	`number`	Optional	Anzahl der Transaktionen (Standard: 20, max: 100)

Beispielanfrage

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"

Antwort

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
    }
  }
}

Guthaben aufladen

Um Guthaben aufzuladen, besuchen Sie die Seite Mein Wallet und zahlen Sie mit BTC, LTC oder LTCT (Testnet) ein.

Adressverifizierung

Verifizieren und standardisieren Sie Versandadressen, um die Zustellbarkeit sicherzustellen.

POST

/api/v1/shipping/verify-address

Versandadresse verifizieren und korrigieren

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
address	`Address`	Erforderlich	Zu verifizierende Adresse
strict	`boolean`	Optional	Strengen Verifizierungsmodus aktivieren

Beispielanfrage

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"
    }
  }'

Antwort

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": []
    }
  }
}

Versandtarife

Erhalten Sie Echtzeit-Versandtarife von mehreren Transportunternehmen, einschließlich USPS, UPS, FedEx und DHL.

POST

/api/v1/shipping/rates

Versandtarife für ein Paket berechnen

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
fromAddress	`Address`	Erforderlich	Absenderadresse-Objekt
toAddress	`Address`	Erforderlich	Empfängeradresse-Objekt
packageDetails	`Package`	Erforderlich	Paketabmessungen und Gewicht
carriers	`string[]`	Optional	Nach bestimmten Transportunternehmen filtern (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optional	Erforderlich für internationale Sendungen

Adress-Objekt

Parameter	Typ	Erforderlich	Beschreibung
name	`string`	Erforderlich	Vollständiger Name
company	`string`	Optional	Firmenname
street1	`string`	Erforderlich	Straßenadresse Zeile 1
street2	`string`	Optional	Straßenadresse Zeile 2
city	`string`	Erforderlich	Stadt
state	`string`	Erforderlich	Bundesland/Provinz-Code
zip	`string`	Erforderlich	Postleitzahl
country	`string`	Erforderlich	Ländercode (US, CA, etc.)
phone	`string`	Optional	Telefonnummer
email	`string`	Optional	E-Mail-Adresse

Paket-Objekt

Parameter	Typ	Erforderlich	Beschreibung
length	`number`	Erforderlich	Länge in Zoll
width	`number`	Erforderlich	Breite in Zoll
height	`number`	Erforderlich	Höhe in Zoll
weight	`number`	Erforderlich	Gewicht in Unzen

CustomsInfo-Objekt

Internationale Sendungen

Erforderlich beim internationalen Versand (wenn fromAddress.country von toAddress.country abweicht).

Parameter	Typ	Erforderlich	Beschreibung
contents_type	`string`	Erforderlich	Inhaltstyp: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optional	Erforderlich wenn contents_type 'other' ist
customs_certify	`boolean`	Erforderlich	Muss true sein - bestätigt die Richtigkeit der Erklärung
customs_signer	`string`	Erforderlich	Name der Person, die die Zollerklärung bestätigt
eel_pfc	`string`	Erforderlich	Exportausnahme-Code (verwenden Sie 'NOEEI 30.37(a)' für Sendungen unter $2.500)
non_delivery_option	`string`	Erforderlich	Was bei Unzustellbarkeit zu tun ist: 'return' oder 'abandon'
restriction_type	`string`	Erforderlich	Beschränkungstyp: 'none', 'other', 'quarantine', oder 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optional	Erforderlich wenn restriction_type nicht 'none' ist
customs_items	`CustomsItem[]`	Erforderlich	Array der zu versendenden Artikel (1-100 Artikel)

CustomsItem-Objekt

Parameter	Typ	Erforderlich	Beschreibung
description	`string`	Erforderlich	Detaillierte Beschreibung des Artikels
quantity	`number`	Erforderlich	Anzahl der Artikel (Minimum: 1)
value	`number`	Erforderlich	Wert in USD (muss größer als 0 sein)
weight	`number`	Erforderlich	Gewicht in Unzen (muss größer als 0 sein)
origin_country	`string`	Erforderlich	2-Buchstaben-Ländercode (z.B. 'US', 'CN')
hs_tariff_number	`string`	Erforderlich	6-10-stelliger HS-Zolltarifcode

Beispielanfrage

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
    }
  }'

Antwort

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"
      }
    ]
  }
}

Internationales Versandbeispiel

Für internationale Sendungen fügen Sie das customsInfo-Objekt mit Artikeldeklarationen hinzu:

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"
        }
      ]
    }
  }'

Bestellung erstellen

Erstellen und verwalten Sie Versandaufträge. Aufträge enthalten einen oder mehrere Versandetiketten-Artikel.

GET

/api/v1/orders

Alle Aufträge auflisten

POST

/api/v1/orders

Neuen Auftrag erstellen

GET

/api/v1/orders/{id}

Auftragsdetails abrufen

Aufträge auflisten - Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
limit	`number`	Optional	Anzahl der Ergebnisse (Standard: 50, max: 100)
offset	`number`	Optional	Paginierungs-Offset

Auftrag erstellen - Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
items	`OrderItem[]`	Erforderlich	Array von Auftragsartikeln
email	`string`	Optional	Kunden-E-Mail
externalReference	`string`	Optional	Ihre Referenz-ID

OrderItem-Objekt

Vereinfachte API

Nur shipmentId und rateId sind erforderlich. Adressen, Paketdetails und Zollinformationen werden automatisch aus der Sendung extrahiert.

Parameter	Typ	Erforderlich	Beschreibung
shipmentId	`string`	Erforderlich	Sendungs-ID vom Tarif-Endpunkt
rateId	`string`	Erforderlich	Tarif-ID vom Tarif-Endpunkt

Beispiel: Auftrag erstellen

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"
  }'

Antwort

json

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

Etiketten kaufen

Kaufen Sie Versandetiketten für alle Artikel eines Auftrags. Etiketten werden mit Ihrem Krypto-Wallet-Guthaben (BTC, LTC oder LTCT) gekauft.

POST

/api/v1/labels/purchase

Versandetiketten für einen Auftrag kaufen

Anfragekörper

Krypto-Zahlung

Die API konvertiert die Etikettenkosten in USD zu Krypto zu aktuellen Kursen. Sie müssen ausreichend Guthaben haben (einschließlich 10% Puffer für Preisschwankungen).

Parameter	Typ	Erforderlich	Beschreibung
orderId	`string`	Erforderlich	Auftrags-ID für Etikettenkauf
currency	`string`	Optional	Kryptowährung für Zahlung (BTC, LTC, LTCT). Wenn nicht angegeben, wird automatisch die erste Währung mit ausreichendem Guthaben gewählt.

Beispielanfrage

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"
  }'

Antwort

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 Unzureichendes Guthaben

Wenn Ihr Wallet-Guthaben zu niedrig ist, gibt die API einen 402-Status mit dem erforderlichen Krypto-Betrag zurück.

Antwort bei unzureichendem Guthaben

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"
}

Sendungsverfolgung

Verfolgen Sie Sendungen mit dem Tracking-Code von gekauften Etiketten.

GET

/api/v1/tracking/{code}

Tracking-Informationen abrufen

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
code	`string`	Erforderlich	Tracking-Code

Beispielanfrage

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"

Antwort

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

Erhalten Sie Echtzeit-Benachrichtigungen bei Ereignissen wie Etikettenerstellung oder Tracking-Updates.

GET

/api/v1/webhooks

Registrierte Webhooks auflisten

POST

/api/v1/webhooks

Neuen Webhook registrieren

GET

/api/v1/webhooks/{id}

Webhook-Details abrufen

DELETE

/api/v1/webhooks/{id}

Webhook löschen

Verfügbare Ereignisse

label.created

Wenn ein Etikett erfolgreich gekauft wird

label.failed

Wenn die Etikettenerstellung fehlschlägt

Webhook registrieren - Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
webhookUrl	`string`	Erforderlich	URL zum Empfangen von Webhook-Ereignissen
events	`string[]`	Erforderlich	Array von Ereignistypen zum Abonnieren

Beispiel: Webhook registrieren

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"]
  }'

Antwort

json

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

Webhook-Signaturverifizierung

Jeder Webhook enthält einen Signatur-Header zur Verifizierung. Verifizieren Sie die Signatur mit 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)
  );
}

Webhook-Payload-Beispiel

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

API-Dokumentation

Integrieren Sie Versandetiketten in Ihre Anwendung mit unserer leistungsstarken REST API. Erhalten Sie Echtzeit-Tarife, erstellen Sie Etiketten und verfolgen Sie Sendungen programmatisch.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit Ihrem API-Schlüssel und Geheimnis. Fügen Sie diese Header in jede Anfrage ein:

headers

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

Sicherheitshinweis

Halten Sie Ihr API-Geheimnis sicher. Geben Sie es niemals in clientseitigem Code oder öffentlichen Repositories preis.

Beispielanfrage

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"

Kontostand

Überprüfen Sie Ihre Krypto-Wallet-Guthaben und Transaktionshistorie. Die API verwendet Ihre Krypto-Wallet (BTC, LTC, LTCT) für Zahlungen.

GET

/api/v1/account/balance

Krypto-Wallet-Guthaben und Transaktionen abrufen

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
includeTransactions	`boolean`	Optional	Transaktionshistorie einschließen
currency	`string`	Optional	Transaktionen nach Währung filtern (BTC, LTC, LTCT)
limit	`number`	Optional	Anzahl der Transaktionen (Standard: 20, max: 100)

Beispielanfrage

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"

Antwort

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
    }
  }
}

Guthaben aufladen

Um Guthaben aufzuladen, besuchen Sie die Seite Mein Wallet und zahlen Sie mit BTC, LTC oder LTCT (Testnet) ein.

Adressverifizierung

Verifizieren und standardisieren Sie Versandadressen, um die Zustellbarkeit sicherzustellen.

POST

/api/v1/shipping/verify-address

Versandadresse verifizieren und korrigieren

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
address	`Address`	Erforderlich	Zu verifizierende Adresse
strict	`boolean`	Optional	Strengen Verifizierungsmodus aktivieren

Beispielanfrage

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"
    }
  }'

Antwort

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": []
    }
  }
}

Versandtarife

Erhalten Sie Echtzeit-Versandtarife von mehreren Transportunternehmen, einschließlich USPS, UPS, FedEx und DHL.

POST

/api/v1/shipping/rates

Versandtarife für ein Paket berechnen

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
fromAddress	`Address`	Erforderlich	Absenderadresse-Objekt
toAddress	`Address`	Erforderlich	Empfängeradresse-Objekt
packageDetails	`Package`	Erforderlich	Paketabmessungen und Gewicht
carriers	`string[]`	Optional	Nach bestimmten Transportunternehmen filtern (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optional	Erforderlich für internationale Sendungen

Adress-Objekt

Parameter	Typ	Erforderlich	Beschreibung
name	`string`	Erforderlich	Vollständiger Name
company	`string`	Optional	Firmenname
street1	`string`	Erforderlich	Straßenadresse Zeile 1
street2	`string`	Optional	Straßenadresse Zeile 2
city	`string`	Erforderlich	Stadt
state	`string`	Erforderlich	Bundesland/Provinz-Code
zip	`string`	Erforderlich	Postleitzahl
country	`string`	Erforderlich	Ländercode (US, CA, etc.)
phone	`string`	Optional	Telefonnummer
email	`string`	Optional	E-Mail-Adresse

Paket-Objekt

Parameter	Typ	Erforderlich	Beschreibung
length	`number`	Erforderlich	Länge in Zoll
width	`number`	Erforderlich	Breite in Zoll
height	`number`	Erforderlich	Höhe in Zoll
weight	`number`	Erforderlich	Gewicht in Unzen

CustomsInfo-Objekt

Internationale Sendungen

Erforderlich beim internationalen Versand (wenn fromAddress.country von toAddress.country abweicht).

Parameter	Typ	Erforderlich	Beschreibung
contents_type	`string`	Erforderlich	Inhaltstyp: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optional	Erforderlich wenn contents_type 'other' ist
customs_certify	`boolean`	Erforderlich	Muss true sein - bestätigt die Richtigkeit der Erklärung
customs_signer	`string`	Erforderlich	Name der Person, die die Zollerklärung bestätigt
eel_pfc	`string`	Erforderlich	Exportausnahme-Code (verwenden Sie 'NOEEI 30.37(a)' für Sendungen unter $2.500)
non_delivery_option	`string`	Erforderlich	Was bei Unzustellbarkeit zu tun ist: 'return' oder 'abandon'
restriction_type	`string`	Erforderlich	Beschränkungstyp: 'none', 'other', 'quarantine', oder 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optional	Erforderlich wenn restriction_type nicht 'none' ist
customs_items	`CustomsItem[]`	Erforderlich	Array der zu versendenden Artikel (1-100 Artikel)

CustomsItem-Objekt

Parameter	Typ	Erforderlich	Beschreibung
description	`string`	Erforderlich	Detaillierte Beschreibung des Artikels
quantity	`number`	Erforderlich	Anzahl der Artikel (Minimum: 1)
value	`number`	Erforderlich	Wert in USD (muss größer als 0 sein)
weight	`number`	Erforderlich	Gewicht in Unzen (muss größer als 0 sein)
origin_country	`string`	Erforderlich	2-Buchstaben-Ländercode (z.B. 'US', 'CN')
hs_tariff_number	`string`	Erforderlich	6-10-stelliger HS-Zolltarifcode

Beispielanfrage

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
    }
  }'

Antwort

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"
      }
    ]
  }
}

Internationales Versandbeispiel

Für internationale Sendungen fügen Sie das customsInfo-Objekt mit Artikeldeklarationen hinzu:

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"
        }
      ]
    }
  }'

Bestellung erstellen

Erstellen und verwalten Sie Versandaufträge. Aufträge enthalten einen oder mehrere Versandetiketten-Artikel.

GET

/api/v1/orders

Alle Aufträge auflisten

POST

/api/v1/orders

Neuen Auftrag erstellen

GET

/api/v1/orders/{id}

Auftragsdetails abrufen

Aufträge auflisten - Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
limit	`number`	Optional	Anzahl der Ergebnisse (Standard: 50, max: 100)
offset	`number`	Optional	Paginierungs-Offset

Auftrag erstellen - Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
items	`OrderItem[]`	Erforderlich	Array von Auftragsartikeln
email	`string`	Optional	Kunden-E-Mail
externalReference	`string`	Optional	Ihre Referenz-ID

OrderItem-Objekt

Vereinfachte API

Nur shipmentId und rateId sind erforderlich. Adressen, Paketdetails und Zollinformationen werden automatisch aus der Sendung extrahiert.

Parameter	Typ	Erforderlich	Beschreibung
shipmentId	`string`	Erforderlich	Sendungs-ID vom Tarif-Endpunkt
rateId	`string`	Erforderlich	Tarif-ID vom Tarif-Endpunkt

Beispiel: Auftrag erstellen

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"
  }'

Antwort

json

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

Etiketten kaufen

Kaufen Sie Versandetiketten für alle Artikel eines Auftrags. Etiketten werden mit Ihrem Krypto-Wallet-Guthaben (BTC, LTC oder LTCT) gekauft.

POST

/api/v1/labels/purchase

Versandetiketten für einen Auftrag kaufen

Anfragekörper

Krypto-Zahlung

Die API konvertiert die Etikettenkosten in USD zu Krypto zu aktuellen Kursen. Sie müssen ausreichend Guthaben haben (einschließlich 10% Puffer für Preisschwankungen).

Parameter	Typ	Erforderlich	Beschreibung
orderId	`string`	Erforderlich	Auftrags-ID für Etikettenkauf
currency	`string`	Optional	Kryptowährung für Zahlung (BTC, LTC, LTCT). Wenn nicht angegeben, wird automatisch die erste Währung mit ausreichendem Guthaben gewählt.

Beispielanfrage

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"
  }'

Antwort

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 Unzureichendes Guthaben

Wenn Ihr Wallet-Guthaben zu niedrig ist, gibt die API einen 402-Status mit dem erforderlichen Krypto-Betrag zurück.

Antwort bei unzureichendem Guthaben

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"
}

Sendungsverfolgung

Verfolgen Sie Sendungen mit dem Tracking-Code von gekauften Etiketten.

GET

/api/v1/tracking/{code}

Tracking-Informationen abrufen

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
code	`string`	Erforderlich	Tracking-Code

Beispielanfrage

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"

Antwort

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

Erhalten Sie Echtzeit-Benachrichtigungen bei Ereignissen wie Etikettenerstellung oder Tracking-Updates.

GET

/api/v1/webhooks

Registrierte Webhooks auflisten

POST

/api/v1/webhooks

Neuen Webhook registrieren

GET

/api/v1/webhooks/{id}

Webhook-Details abrufen

DELETE

/api/v1/webhooks/{id}

Webhook löschen

Verfügbare Ereignisse

label.created

Wenn ein Etikett erfolgreich gekauft wird

label.failed

Wenn die Etikettenerstellung fehlschlägt

Webhook registrieren - Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
webhookUrl	`string`	Erforderlich	URL zum Empfangen von Webhook-Ereignissen
events	`string[]`	Erforderlich	Array von Ereignistypen zum Abonnieren

Beispiel: Webhook registrieren

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"]
  }'

Antwort

json

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

Webhook-Signaturverifizierung

Jeder Webhook enthält einen Signatur-Header zur Verifizierung. Verifizieren Sie die Signatur mit 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)
  );
}

Webhook-Payload-Beispiel

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"
    }
  }
}

API-Dokumentation

Authentifizierung

Beispielanfrage

Kontostand

Abfrageparameter

Beispielanfrage

Antwort

Adressverifizierung

Anfragekörper

Beispielanfrage

Antwort

Versandtarife

Anfragekörper

Adress-Objekt

Paket-Objekt

CustomsInfo-Objekt

CustomsItem-Objekt

Beispielanfrage

Antwort

Internationales Versandbeispiel

Bestellung erstellen

Aufträge auflisten - Abfrageparameter

Auftrag erstellen - Anfragekörper

OrderItem-Objekt

Beispiel: Auftrag erstellen

Antwort

Etiketten kaufen

Anfragekörper

Beispielanfrage

Antwort

Antwort bei unzureichendem Guthaben

Sendungsverfolgung

Pfadparameter

Beispielanfrage

Antwort

Webhooks

Verfügbare Ereignisse

Webhook registrieren - Anfragekörper

Beispiel: Webhook registrieren

Antwort

Webhook-Signaturverifizierung

Webhook-Payload-Beispiel

Warenkorb

Ihr Warenkorb ist leer

API-Dokumentation

Authentifizierung

Beispielanfrage

Kontostand

Abfrageparameter

Beispielanfrage

Antwort

Adressverifizierung

Anfragekörper

Beispielanfrage

Antwort

Versandtarife

Anfragekörper

Adress-Objekt

Paket-Objekt

CustomsInfo-Objekt

CustomsItem-Objekt

Beispielanfrage

Antwort

Internationales Versandbeispiel

Bestellung erstellen

Aufträge auflisten - Abfrageparameter

Auftrag erstellen - Anfragekörper

OrderItem-Objekt

Beispiel: Auftrag erstellen

Antwort

Etiketten kaufen

Anfragekörper

Beispielanfrage

Antwort

Antwort bei unzureichendem Guthaben

Sendungsverfolgung

Pfadparameter

Beispielanfrage

Antwort

Webhooks