REST API

Documentation API

Intégrez des étiquettes d'expédition dans votre application avec notre puissante API REST. Obtenez des tarifs en temps réel, créez des étiquettes et suivez les envois de manière programmée.

Authentification

Toutes les requêtes API nécessitent une authentification avec votre clé et secret API. Incluez ces en-têtes dans chaque requête :

headers

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

Avis de sécurité

Gardez votre secret API en sécurité. Ne l'exposez jamais dans le code côté client ou les dépôts publics.

Exemple de requête

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"

Solde du compte

Vérifiez vos soldes de portefeuille crypto et l'historique des transactions. L'API utilise votre portefeuille crypto (BTC, LTC, LTCT) pour les paiements.

GET

/api/v1/account/balance

Obtenir les soldes et transactions du portefeuille crypto

Paramètres de requête

Paramètre	Type	Requis	Description
includeTransactions	`boolean`	Optionnel	Inclure l'historique des transactions
currency	`string`	Optionnel	Filtrer les transactions par devise (BTC, LTC, LTCT)
limit	`number`	Optionnel	Nombre de transactions (défaut : 20, max : 100)

Exemple de requête

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"

Réponse

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

Ajouter des fonds

Pour ajouter des fonds, visitez la page Mon Portefeuille et déposez en BTC, LTC ou LTCT (testnet).

Vérification d'adresse

Vérifiez et standardisez les adresses d'expédition pour assurer la délivrabilité.

POST

/api/v1/shipping/verify-address

Vérifier et corriger une adresse d'expédition

Corps de la requête

Paramètre	Type	Requis	Description
address	`Address`	Requis	Adresse à vérifier
strict	`boolean`	Optionnel	Activer le mode de vérification strict

Exemple de requête

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

Réponse

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

Tarifs d'expédition

Obtenez des tarifs d'expédition en temps réel de plusieurs transporteurs, dont USPS, UPS, FedEx et DHL.

POST

/api/v1/shipping/rates

Calculer les tarifs d'expédition pour un colis

Corps de la requête

Paramètre	Type	Requis	Description
fromAddress	`Address`	Requis	Objet adresse de l'expéditeur
toAddress	`Address`	Requis	Objet adresse du destinataire
packageDetails	`Package`	Requis	Dimensions et poids du colis
carriers	`string[]`	Optionnel	Filtrer par transporteurs spécifiques (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optionnel	Requis pour les envois internationaux

Objet Adresse

Paramètre	Type	Requis	Description
name	`string`	Requis	Nom complet
company	`string`	Optionnel	Nom de l'entreprise
street1	`string`	Requis	Adresse ligne 1
street2	`string`	Optionnel	Adresse ligne 2
city	`string`	Requis	Ville
state	`string`	Requis	Code État/Province
zip	`string`	Requis	Code postal
country	`string`	Requis	Code pays (US, CA, etc.)
phone	`string`	Optionnel	Numéro de téléphone
email	`string`	Optionnel	Adresse e-mail

Objet Colis

Paramètre	Type	Requis	Description
length	`number`	Requis	Longueur en pouces
width	`number`	Requis	Largeur en pouces
height	`number`	Requis	Hauteur en pouces
weight	`number`	Requis	Poids en onces

Objet CustomsInfo

Envois internationaux

Requis lors d'envois internationaux (quand fromAddress.country diffère de toAddress.country).

Paramètre	Type	Requis	Description
contents_type	`string`	Requis	Type de contenu : documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optionnel	Requis quand contents_type est 'other'
customs_certify	`boolean`	Requis	Doit être true - certifie l'exactitude de la déclaration
customs_signer	`string`	Requis	Nom de la personne certifiant la déclaration douanière
eel_pfc	`string`	Requis	Code d'exemption d'exportation (utilisez 'NOEEI 30.37(a)' pour les envois de moins de 2 500 $)
non_delivery_option	`string`	Requis	Action si non livrable : 'return' ou 'abandon'
restriction_type	`string`	Requis	Type de restriction : 'none', 'other', 'quarantine', ou 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optionnel	Requis quand restriction_type n'est pas 'none'
customs_items	`CustomsItem[]`	Requis	Liste des articles expédiés (1-100 articles)

Objet CustomsItem

Paramètre	Type	Requis	Description
description	`string`	Requis	Description détaillée de l'article
quantity	`number`	Requis	Nombre d'articles (minimum : 1)
value	`number`	Requis	Valeur en USD (doit être supérieur à 0)
weight	`number`	Requis	Poids en onces (doit être supérieur à 0)
origin_country	`string`	Requis	Code pays à 2 lettres (ex : 'US', 'CN')
hs_tariff_number	`string`	Requis	Code tarifaire HS à 6-10 chiffres

Exemple de requête

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

Réponse

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

Exemple d'envoi international

Pour les envois internationaux, incluez l'objet customsInfo avec les déclarations d'articles :

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

Créer une commande

Créez et gérez des commandes d'expédition. Les commandes contiennent un ou plusieurs articles d'étiquettes d'expédition.

GET

/api/v1/orders

Lister toutes les commandes

POST

/api/v1/orders

Créer une nouvelle commande

GET

/api/v1/orders/{id}

Obtenir les détails de la commande

Lister les commandes - Paramètres de requête

Paramètre	Type	Requis	Description
limit	`number`	Optionnel	Nombre de résultats (défaut : 50, max : 100)
offset	`number`	Optionnel	Décalage de pagination

Créer une commande - Corps de la requête

Paramètre	Type	Requis	Description
items	`OrderItem[]`	Requis	Liste des articles de la commande
email	`string`	Optionnel	E-mail du client
externalReference	`string`	Optionnel	Votre ID de référence

Objet OrderItem

API simplifiée

Seuls shipmentId et rateId sont requis. Les adresses, détails du colis et informations douanières sont automatiquement extraits de l'envoi.

Paramètre	Type	Requis	Description
shipmentId	`string`	Requis	ID d'envoi du endpoint des tarifs
rateId	`string`	Requis	ID de tarif du endpoint des tarifs

Exemple : Créer une commande

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

Réponse

json

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

Acheter des étiquettes

Achetez des étiquettes d'expédition pour tous les articles d'une commande. Les étiquettes sont achetées avec votre solde de portefeuille crypto (BTC, LTC ou LTCT).

POST

/api/v1/labels/purchase

Acheter des étiquettes d'expédition pour une commande

Corps de la requête

Paiement crypto

L'API convertira le coût de l'étiquette en USD vers crypto aux taux actuels. Vous devez avoir un solde suffisant (incluant 10% de marge pour les fluctuations de prix).

Paramètre	Type	Requis	Description
orderId	`string`	Requis	ID de commande pour l'achat d'étiquettes
currency	`string`	Optionnel	Crypto-monnaie pour le paiement (BTC, LTC, LTCT). Si non spécifié, sélectionne automatiquement la première devise avec un solde suffisant.

Exemple de requête

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

Réponse

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 Solde insuffisant

Si le solde de votre portefeuille est trop bas, l'API renvoie un statut 402 avec le montant crypto requis.

Réponse solde insuffisant

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

Suivi

Suivez les envois en utilisant le code de suivi des étiquettes achetées.

GET

/api/v1/tracking/{code}

Obtenir les informations de suivi

Paramètres de chemin

Paramètre	Type	Requis	Description
code	`string`	Requis	Code de suivi

Exemple de requête

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"

Réponse

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

Recevez des notifications en temps réel lors d'événements comme la création d'étiquettes ou les mises à jour de suivi.

GET

/api/v1/webhooks

Lister les webhooks enregistrés

POST

/api/v1/webhooks

Enregistrer un nouveau webhook

GET

/api/v1/webhooks/{id}

Obtenir les détails du webhook

DELETE

/api/v1/webhooks/{id}

Supprimer un webhook

Événements disponibles

label.created

Quand une étiquette est achetée avec succès

label.failed

Quand la génération d'étiquette échoue

Enregistrer un webhook - Corps de la requête

Paramètre	Type	Requis	Description
webhookUrl	`string`	Requis	URL pour recevoir les événements webhook
events	`string[]`	Requis	Liste des types d'événements à souscrire

Exemple : Enregistrer un 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"]
  }'

Réponse

json

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

Vérification de signature webhook

Chaque webhook inclut un en-tête de signature pour vérification. Vérifiez la signature avec 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)
  );
}

Exemple de 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

Documentation API

Intégrez des étiquettes d'expédition dans votre application avec notre puissante API REST. Obtenez des tarifs en temps réel, créez des étiquettes et suivez les envois de manière programmée.

Authentification

Toutes les requêtes API nécessitent une authentification avec votre clé et secret API. Incluez ces en-têtes dans chaque requête :

headers

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

Avis de sécurité

Gardez votre secret API en sécurité. Ne l'exposez jamais dans le code côté client ou les dépôts publics.

Exemple de requête

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"

Solde du compte

Vérifiez vos soldes de portefeuille crypto et l'historique des transactions. L'API utilise votre portefeuille crypto (BTC, LTC, LTCT) pour les paiements.

GET

/api/v1/account/balance

Obtenir les soldes et transactions du portefeuille crypto

Paramètres de requête

Paramètre	Type	Requis	Description
includeTransactions	`boolean`	Optionnel	Inclure l'historique des transactions
currency	`string`	Optionnel	Filtrer les transactions par devise (BTC, LTC, LTCT)
limit	`number`	Optionnel	Nombre de transactions (défaut : 20, max : 100)

Exemple de requête

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"

Réponse

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

Ajouter des fonds

Pour ajouter des fonds, visitez la page Mon Portefeuille et déposez en BTC, LTC ou LTCT (testnet).

Vérification d'adresse

Vérifiez et standardisez les adresses d'expédition pour assurer la délivrabilité.

POST

/api/v1/shipping/verify-address

Vérifier et corriger une adresse d'expédition

Corps de la requête

Paramètre	Type	Requis	Description
address	`Address`	Requis	Adresse à vérifier
strict	`boolean`	Optionnel	Activer le mode de vérification strict

Exemple de requête

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

Réponse

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

Tarifs d'expédition

Obtenez des tarifs d'expédition en temps réel de plusieurs transporteurs, dont USPS, UPS, FedEx et DHL.

POST

/api/v1/shipping/rates

Calculer les tarifs d'expédition pour un colis

Corps de la requête

Paramètre	Type	Requis	Description
fromAddress	`Address`	Requis	Objet adresse de l'expéditeur
toAddress	`Address`	Requis	Objet adresse du destinataire
packageDetails	`Package`	Requis	Dimensions et poids du colis
carriers	`string[]`	Optionnel	Filtrer par transporteurs spécifiques (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optionnel	Requis pour les envois internationaux

Objet Adresse

Paramètre	Type	Requis	Description
name	`string`	Requis	Nom complet
company	`string`	Optionnel	Nom de l'entreprise
street1	`string`	Requis	Adresse ligne 1
street2	`string`	Optionnel	Adresse ligne 2
city	`string`	Requis	Ville
state	`string`	Requis	Code État/Province
zip	`string`	Requis	Code postal
country	`string`	Requis	Code pays (US, CA, etc.)
phone	`string`	Optionnel	Numéro de téléphone
email	`string`	Optionnel	Adresse e-mail

Objet Colis

Paramètre	Type	Requis	Description
length	`number`	Requis	Longueur en pouces
width	`number`	Requis	Largeur en pouces
height	`number`	Requis	Hauteur en pouces
weight	`number`	Requis	Poids en onces

Objet CustomsInfo

Envois internationaux

Requis lors d'envois internationaux (quand fromAddress.country diffère de toAddress.country).

Paramètre	Type	Requis	Description
contents_type	`string`	Requis	Type de contenu : documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optionnel	Requis quand contents_type est 'other'
customs_certify	`boolean`	Requis	Doit être true - certifie l'exactitude de la déclaration
customs_signer	`string`	Requis	Nom de la personne certifiant la déclaration douanière
eel_pfc	`string`	Requis	Code d'exemption d'exportation (utilisez 'NOEEI 30.37(a)' pour les envois de moins de 2 500 $)
non_delivery_option	`string`	Requis	Action si non livrable : 'return' ou 'abandon'
restriction_type	`string`	Requis	Type de restriction : 'none', 'other', 'quarantine', ou 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optionnel	Requis quand restriction_type n'est pas 'none'
customs_items	`CustomsItem[]`	Requis	Liste des articles expédiés (1-100 articles)

Objet CustomsItem

Paramètre	Type	Requis	Description
description	`string`	Requis	Description détaillée de l'article
quantity	`number`	Requis	Nombre d'articles (minimum : 1)
value	`number`	Requis	Valeur en USD (doit être supérieur à 0)
weight	`number`	Requis	Poids en onces (doit être supérieur à 0)
origin_country	`string`	Requis	Code pays à 2 lettres (ex : 'US', 'CN')
hs_tariff_number	`string`	Requis	Code tarifaire HS à 6-10 chiffres

Exemple de requête

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

Réponse

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

Exemple d'envoi international

Pour les envois internationaux, incluez l'objet customsInfo avec les déclarations d'articles :

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

Créer une commande

Créez et gérez des commandes d'expédition. Les commandes contiennent un ou plusieurs articles d'étiquettes d'expédition.

GET

/api/v1/orders

Lister toutes les commandes

POST

/api/v1/orders

Créer une nouvelle commande

GET

/api/v1/orders/{id}

Obtenir les détails de la commande

Lister les commandes - Paramètres de requête

Paramètre	Type	Requis	Description
limit	`number`	Optionnel	Nombre de résultats (défaut : 50, max : 100)
offset	`number`	Optionnel	Décalage de pagination

Créer une commande - Corps de la requête

Paramètre	Type	Requis	Description
items	`OrderItem[]`	Requis	Liste des articles de la commande
email	`string`	Optionnel	E-mail du client
externalReference	`string`	Optionnel	Votre ID de référence

Objet OrderItem

API simplifiée

Seuls shipmentId et rateId sont requis. Les adresses, détails du colis et informations douanières sont automatiquement extraits de l'envoi.

Paramètre	Type	Requis	Description
shipmentId	`string`	Requis	ID d'envoi du endpoint des tarifs
rateId	`string`	Requis	ID de tarif du endpoint des tarifs

Exemple : Créer une commande

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

Réponse

json

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

Acheter des étiquettes

Achetez des étiquettes d'expédition pour tous les articles d'une commande. Les étiquettes sont achetées avec votre solde de portefeuille crypto (BTC, LTC ou LTCT).

POST

/api/v1/labels/purchase

Acheter des étiquettes d'expédition pour une commande

Corps de la requête

Paiement crypto

L'API convertira le coût de l'étiquette en USD vers crypto aux taux actuels. Vous devez avoir un solde suffisant (incluant 10% de marge pour les fluctuations de prix).

Paramètre	Type	Requis	Description
orderId	`string`	Requis	ID de commande pour l'achat d'étiquettes
currency	`string`	Optionnel	Crypto-monnaie pour le paiement (BTC, LTC, LTCT). Si non spécifié, sélectionne automatiquement la première devise avec un solde suffisant.

Exemple de requête

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

Réponse

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 Solde insuffisant

Si le solde de votre portefeuille est trop bas, l'API renvoie un statut 402 avec le montant crypto requis.

Réponse solde insuffisant

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

Suivi

Suivez les envois en utilisant le code de suivi des étiquettes achetées.

GET

/api/v1/tracking/{code}

Obtenir les informations de suivi

Paramètres de chemin

Paramètre	Type	Requis	Description
code	`string`	Requis	Code de suivi

Exemple de requête

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"

Réponse

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

Recevez des notifications en temps réel lors d'événements comme la création d'étiquettes ou les mises à jour de suivi.

GET

/api/v1/webhooks

Lister les webhooks enregistrés

POST

/api/v1/webhooks

Enregistrer un nouveau webhook

GET

/api/v1/webhooks/{id}

Obtenir les détails du webhook

DELETE

/api/v1/webhooks/{id}

Supprimer un webhook

Événements disponibles

label.created

Quand une étiquette est achetée avec succès

label.failed

Quand la génération d'étiquette échoue

Enregistrer un webhook - Corps de la requête

Paramètre	Type	Requis	Description
webhookUrl	`string`	Requis	URL pour recevoir les événements webhook
events	`string[]`	Requis	Liste des types d'événements à souscrire

Exemple : Enregistrer un 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"]
  }'

Réponse

json

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

Vérification de signature webhook

Chaque webhook inclut un en-tête de signature pour vérification. Vérifiez la signature avec 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)
  );
}

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

Documentation API

Authentification

Exemple de requête

Solde du compte

Paramètres de requête

Exemple de requête

Réponse

Vérification d'adresse

Corps de la requête

Exemple de requête

Réponse

Tarifs d'expédition

Corps de la requête

Objet Adresse

Objet Colis

Objet CustomsInfo

Objet CustomsItem

Exemple de requête

Réponse

Exemple d'envoi international

Créer une commande

Lister les commandes - Paramètres de requête

Créer une commande - Corps de la requête

Objet OrderItem

Exemple : Créer une commande

Réponse

Acheter des étiquettes

Corps de la requête

Exemple de requête

Réponse

Réponse solde insuffisant

Suivi

Paramètres de chemin

Exemple de requête

Réponse

Webhooks

Événements disponibles

Enregistrer un webhook - Corps de la requête

Exemple : Enregistrer un webhook

Réponse

Vérification de signature webhook

Exemple de payload webhook

Panier

Votre panier est vide

Documentation API

Authentification

Exemple de requête

Solde du compte

Paramètres de requête

Exemple de requête

Réponse

Vérification d'adresse

Corps de la requête

Exemple de requête

Réponse

Tarifs d'expédition

Corps de la requête

Objet Adresse

Objet Colis

Objet CustomsInfo

Objet CustomsItem

Exemple de requête

Réponse

Exemple d'envoi international

Créer une commande

Lister les commandes - Paramètres de requête

Créer une commande - Corps de la requête

Objet OrderItem

Exemple : Créer une commande

Réponse

Acheter des étiquettes

Corps de la requête

Exemple de requête

Réponse

Réponse solde insuffisant

Suivi

Paramètres de chemin

Exemple de requête

Réponse

Webhooks