REST API

Документація API

Інтегруйте етикетки доставки у ваш додаток за допомогою потужного REST API. Отримуйте тарифи в реальному часі, створюйте етикетки та відстежуйте відправлення програмно.

Автентифікація

Усі API-запити потребують автентифікації з використанням вашого ключа та секрету API. Додавайте ці заголовки до кожного запиту:

headers

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

Повідомлення про безпеку

Зберігайте ваш секрет API у безпеці. Ніколи не розкривайте його в клієнтському коді або публічних репозиторіях.

Приклад запиту

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"

Баланс акаунту

Перевірте баланс криптогаманця та історію транзакцій. API використовує ваш криптогаманець (BTC, LTC, LTCT) для платежів.

GET

/api/v1/account/balance

Отримати баланси та транзакції криптогаманця

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
includeTransactions	`boolean`	Необов'язковий	Включити історію транзакцій
currency	`string`	Необов'язковий	Фільтрувати транзакції за валютою (BTC, LTC, LTCT)
limit	`number`	Необов'язковий	Кількість транзакцій (за замовчуванням: 20, макс: 100)

Приклад запиту

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"

Відповідь

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

Поповнити баланс

Для поповнення гаманця відвідайте сторінку Мій гаманець та внесіть депозит у BTC, LTC або LTCT (тестнет).

Перевірка адреси

Перевірте та стандартизуйте адреси доставки для забезпечення доставки.

POST

/api/v1/shipping/verify-address

Перевірити та виправити адресу доставки

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
address	`Address`	Обов'язковий	Адреса для перевірки
strict	`boolean`	Необов'язковий	Увімкнути суворий режим перевірки

Приклад запиту

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

Відповідь

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

Тарифи доставки

Отримуйте тарифи доставки в реальному часі від кількох перевізників, включаючи USPS, UPS, FedEx та DHL.

POST

/api/v1/shipping/rates

Розрахувати тарифи доставки для посилки

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
fromAddress	`Address`	Обов'язковий	Об'єкт адреси відправника
toAddress	`Address`	Обов'язковий	Об'єкт адреси отримувача
packageDetails	`Package`	Обов'язковий	Розміри та вага посилки
carriers	`string[]`	Необов'язковий	Фільтрувати за конкретними перевізниками (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Необов'язковий	Обов'язково для міжнародних відправлень

Об'єкт адреси

Параметр	Тип	Обов'язковий	Опис
name	`string`	Обов'язковий	Повне ім'я
company	`string`	Необов'язковий	Назва компанії
street1	`string`	Обов'язковий	Адресний рядок 1
street2	`string`	Необов'язковий	Адресний рядок 2
city	`string`	Обов'язковий	Місто
state	`string`	Обов'язковий	Код штату/області
zip	`string`	Обов'язковий	Поштовий індекс
country	`string`	Обов'язковий	Код країни (US, CA тощо)
phone	`string`	Необов'язковий	Номер телефону
email	`string`	Необов'язковий	Email адреса

Об'єкт посилки

Параметр	Тип	Обов'язковий	Опис
length	`number`	Обов'язковий	Довжина в дюймах
width	`number`	Обов'язковий	Ширина в дюймах
height	`number`	Обов'язковий	Висота в дюймах
weight	`number`	Обов'язковий	Вага в унціях

Об'єкт CustomsInfo

Міжнародні відправлення

Обов'язково при міжнародній доставці (коли fromAddress.country відрізняється від toAddress.country).

Параметр	Тип	Обов'язковий	Опис
contents_type	`string`	Обов'язковий	Тип вмісту: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Необов'язковий	Обов'язково, коли contents_type - 'other'
customs_certify	`boolean`	Обов'язковий	Повинно бути true - підтверджує точність декларації
customs_signer	`string`	Обов'язковий	Ім'я особи, що засвідчує митну декларацію
eel_pfc	`string`	Обов'язковий	Код звільнення від експорту (використовуйте 'NOEEI 30.37(a)' для відправлень менше $2,500)
non_delivery_option	`string`	Обов'язковий	Дія при неможливості доставки: 'return' або 'abandon'
restriction_type	`string`	Обов'язковий	Тип обмеження: 'none', 'other', 'quarantine' або 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Необов'язковий	Обов'язково, коли restriction_type не 'none'
customs_items	`CustomsItem[]`	Обов'язковий	Масив товарів для відправлення (1-100 товарів)

Об'єкт CustomsItem

Параметр	Тип	Обов'язковий	Опис
description	`string`	Обов'язковий	Детальний опис товару
quantity	`number`	Обов'язковий	Кількість товарів (мінімум: 1)
value	`number`	Обов'язковий	Вартість у USD (повинна бути більше 0)
weight	`number`	Обов'язковий	Вага в унціях (повинна бути більше 0)
origin_country	`string`	Обов'язковий	2-літерний код країни (наприклад, 'US', 'CN')
hs_tariff_number	`string`	Обов'язковий	6-10-значний код тарифу HS

Приклад запиту

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

Відповідь

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

Приклад міжнародної доставки

Для міжнародних відправлень включіть об'єкт customsInfo з деклараціями товарів:

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

Створення замовлення

Створюйте та керуйте замовленнями на доставку. Замовлення містять один або більше товарів з етикетками доставки.

GET

/api/v1/orders

Список усіх замовлень

POST

/api/v1/orders

Створити нове замовлення

GET

/api/v1/orders/{id}

Отримати деталі замовлення

Список замовлень - Параметри запиту

Параметр	Тип	Обов'язковий	Опис
limit	`number`	Необов'язковий	Кількість результатів (за замовчуванням: 50, макс: 100)
offset	`number`	Необов'язковий	Зміщення пагінації

Створення замовлення - Тіло запиту

Параметр	Тип	Обов'язковий	Опис
items	`OrderItem[]`	Обов'язковий	Масив товарів замовлення
email	`string`	Необов'язковий	Email клієнта
externalReference	`string`	Необов'язковий	Ваш ID посилання

Об'єкт OrderItem

Спрощений API

Потрібні лише shipmentId та rateId. Адреси, деталі посилки та митна інформація автоматично витягуються з відправлення.

Параметр	Тип	Обов'язковий	Опис
shipmentId	`string`	Обов'язковий	ID відправлення з ендпоінту тарифів
rateId	`string`	Обов'язковий	ID тарифу з ендпоінту тарифів

Приклад: Створення замовлення

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

Відповідь

json

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

Купівля етикеток

Купуйте етикетки доставки для всіх товарів замовлення. Етикетки оплачуються з балансу криптогаманця (BTC, LTC або LTCT).

POST

/api/v1/labels/purchase

Купити етикетки доставки для замовлення

Тіло запиту

Криптоплатіж

API конвертує вартість етикетки з USD у криптовалюту за поточними курсами. У вас повинен бути достатній баланс (включаючи 10% буфер на коливання цін).

Параметр	Тип	Обов'язковий	Опис
orderId	`string`	Обов'язковий	ID замовлення для купівлі етикеток
currency	`string`	Необов'язковий	Криптовалюта для оплати (BTC, LTC, LTCT). Якщо не вказано, автоматично обирається перша валюта з достатнім балансом.

Приклад запиту

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

Відповідь

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 Недостатній баланс

Якщо баланс гаманця занадто низький, API повертає статус 402 з необхідною сумою в криптовалюті.

Відповідь при недостатньому балансі

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

Відстеження

Відстежуйте відправлення за кодом відстеження куплених етикеток.

GET

/api/v1/tracking/{code}

Отримати інформацію про відстеження

Параметри шляху

Параметр	Тип	Обов'язковий	Опис
code	`string`	Обов'язковий	Код відстеження

Приклад запиту

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"

Відповідь

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

Отримуйте сповіщення в реальному часі про події, такі як створення етикеток або оновлення відстеження.

GET

/api/v1/webhooks

Список зареєстрованих webhooks

POST

/api/v1/webhooks

Зареєструвати новий webhook

GET

/api/v1/webhooks/{id}

Отримати деталі webhook

DELETE

/api/v1/webhooks/{id}

Видалити webhook

Доступні події

label.created

Коли етикетка успішно куплена

label.failed

Коли генерація етикетки не вдалася

Реєстрація Webhook - Тіло запиту

Параметр	Тип	Обов'язковий	Опис
webhookUrl	`string`	Обов'язковий	URL для отримання подій webhook
events	`string[]`	Обов'язковий	Масив типів подій для підписки

Приклад: Реєстрація 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"]
  }'

Відповідь

json

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

Перевірка підпису Webhook

Кожен webhook містить заголовок підпису для перевірки. Перевірте підпис за допомогою 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)
  );
}

Приклад 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

Документація API

Автентифікація

headers

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

Повідомлення про безпеку

Приклад запиту

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"

Баланс акаунту

GET

/api/v1/account/balance

Отримати баланси та транзакції криптогаманця

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
includeTransactions	`boolean`	Необов'язковий	Включити історію транзакцій
currency	`string`	Необов'язковий	Фільтрувати транзакції за валютою (BTC, LTC, LTCT)
limit	`number`	Необов'язковий	Кількість транзакцій (за замовчуванням: 20, макс: 100)

Приклад запиту

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"

Відповідь

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

Поповнити баланс

Для поповнення гаманця відвідайте сторінку Мій гаманець та внесіть депозит у BTC, LTC або LTCT (тестнет).

Перевірка адреси

Перевірте та стандартизуйте адреси доставки для забезпечення доставки.

POST

/api/v1/shipping/verify-address

Перевірити та виправити адресу доставки

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
address	`Address`	Обов'язковий	Адреса для перевірки
strict	`boolean`	Необов'язковий	Увімкнути суворий режим перевірки

Приклад запиту

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

Відповідь

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

Тарифи доставки

Отримуйте тарифи доставки в реальному часі від кількох перевізників, включаючи USPS, UPS, FedEx та DHL.

POST

/api/v1/shipping/rates

Розрахувати тарифи доставки для посилки

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
fromAddress	`Address`	Обов'язковий	Об'єкт адреси відправника
toAddress	`Address`	Обов'язковий	Об'єкт адреси отримувача
packageDetails	`Package`	Обов'язковий	Розміри та вага посилки
carriers	`string[]`	Необов'язковий	Фільтрувати за конкретними перевізниками (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Необов'язковий	Обов'язково для міжнародних відправлень

Об'єкт адреси

Параметр	Тип	Обов'язковий	Опис
name	`string`	Обов'язковий	Повне ім'я
company	`string`	Необов'язковий	Назва компанії
street1	`string`	Обов'язковий	Адресний рядок 1
street2	`string`	Необов'язковий	Адресний рядок 2
city	`string`	Обов'язковий	Місто
state	`string`	Обов'язковий	Код штату/області
zip	`string`	Обов'язковий	Поштовий індекс
country	`string`	Обов'язковий	Код країни (US, CA тощо)
phone	`string`	Необов'язковий	Номер телефону
email	`string`	Необов'язковий	Email адреса

Об'єкт посилки

Параметр	Тип	Обов'язковий	Опис
length	`number`	Обов'язковий	Довжина в дюймах
width	`number`	Обов'язковий	Ширина в дюймах
height	`number`	Обов'язковий	Висота в дюймах
weight	`number`	Обов'язковий	Вага в унціях

Об'єкт CustomsInfo

Міжнародні відправлення

Обов'язково при міжнародній доставці (коли fromAddress.country відрізняється від toAddress.country).

Параметр	Тип	Обов'язковий	Опис
contents_type	`string`	Обов'язковий	Тип вмісту: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Необов'язковий	Обов'язково, коли contents_type - 'other'
customs_certify	`boolean`	Обов'язковий	Повинно бути true - підтверджує точність декларації
customs_signer	`string`	Обов'язковий	Ім'я особи, що засвідчує митну декларацію
eel_pfc	`string`	Обов'язковий	Код звільнення від експорту (використовуйте 'NOEEI 30.37(a)' для відправлень менше $2,500)
non_delivery_option	`string`	Обов'язковий	Дія при неможливості доставки: 'return' або 'abandon'
restriction_type	`string`	Обов'язковий	Тип обмеження: 'none', 'other', 'quarantine' або 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Необов'язковий	Обов'язково, коли restriction_type не 'none'
customs_items	`CustomsItem[]`	Обов'язковий	Масив товарів для відправлення (1-100 товарів)

Об'єкт CustomsItem

Параметр	Тип	Обов'язковий	Опис
description	`string`	Обов'язковий	Детальний опис товару
quantity	`number`	Обов'язковий	Кількість товарів (мінімум: 1)
value	`number`	Обов'язковий	Вартість у USD (повинна бути більше 0)
weight	`number`	Обов'язковий	Вага в унціях (повинна бути більше 0)
origin_country	`string`	Обов'язковий	2-літерний код країни (наприклад, 'US', 'CN')
hs_tariff_number	`string`	Обов'язковий	6-10-значний код тарифу HS

Приклад запиту

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

Відповідь

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

Приклад міжнародної доставки

Для міжнародних відправлень включіть об'єкт customsInfo з деклараціями товарів:

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

Створення замовлення

GET

/api/v1/orders

Список усіх замовлень

POST

/api/v1/orders

Створити нове замовлення

GET

/api/v1/orders/{id}

Отримати деталі замовлення

Список замовлень - Параметри запиту

Параметр	Тип	Обов'язковий	Опис
limit	`number`	Необов'язковий	Кількість результатів (за замовчуванням: 50, макс: 100)
offset	`number`	Необов'язковий	Зміщення пагінації

Створення замовлення - Тіло запиту

Параметр	Тип	Обов'язковий	Опис
items	`OrderItem[]`	Обов'язковий	Масив товарів замовлення
email	`string`	Необов'язковий	Email клієнта
externalReference	`string`	Необов'язковий	Ваш ID посилання

Об'єкт OrderItem

Спрощений API

Параметр	Тип	Обов'язковий	Опис
shipmentId	`string`	Обов'язковий	ID відправлення з ендпоінту тарифів
rateId	`string`	Обов'язковий	ID тарифу з ендпоінту тарифів

Приклад: Створення замовлення

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

Відповідь

json

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

Купівля етикеток

POST

/api/v1/labels/purchase

Купити етикетки доставки для замовлення

Тіло запиту

Криптоплатіж

Параметр	Тип	Обов'язковий	Опис
orderId	`string`	Обов'язковий	ID замовлення для купівлі етикеток
currency	`string`	Необов'язковий	Криптовалюта для оплати (BTC, LTC, LTCT). Якщо не вказано, автоматично обирається перша валюта з достатнім балансом.

Приклад запиту

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

Відповідь

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 Недостатній баланс

Якщо баланс гаманця занадто низький, API повертає статус 402 з необхідною сумою в криптовалюті.

Відповідь при недостатньому балансі

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

Відстеження

Відстежуйте відправлення за кодом відстеження куплених етикеток.

GET

/api/v1/tracking/{code}

Отримати інформацію про відстеження

Параметри шляху

Параметр	Тип	Обов'язковий	Опис
code	`string`	Обов'язковий	Код відстеження

Приклад запиту

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"

Відповідь

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

Отримуйте сповіщення в реальному часі про події, такі як створення етикеток або оновлення відстеження.

GET

/api/v1/webhooks

Список зареєстрованих webhooks

POST

/api/v1/webhooks

Зареєструвати новий webhook

GET

/api/v1/webhooks/{id}

Отримати деталі webhook

DELETE

/api/v1/webhooks/{id}

Видалити webhook

Доступні події

label.created

Коли етикетка успішно куплена

label.failed

Коли генерація етикетки не вдалася

Реєстрація Webhook - Тіло запиту

Параметр	Тип	Обов'язковий	Опис
webhookUrl	`string`	Обов'язковий	URL для отримання подій webhook
events	`string[]`	Обов'язковий	Масив типів подій для підписки

Приклад: Реєстрація 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"]
  }'

Відповідь

json

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

Перевірка підпису Webhook

Кожен webhook містить заголовок підпису для перевірки. Перевірте підпис за допомогою 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)
  );
}

Приклад 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"
    }
  }
}

Документація API

Автентифікація

Приклад запиту

Баланс акаунту

Параметри запиту

Приклад запиту

Відповідь

Перевірка адреси

Тіло запиту

Приклад запиту

Відповідь

Тарифи доставки

Тіло запиту

Об'єкт адреси

Об'єкт посилки

Об'єкт CustomsInfo

Об'єкт CustomsItem

Приклад запиту

Відповідь

Приклад міжнародної доставки

Створення замовлення

Список замовлень - Параметри запиту

Створення замовлення - Тіло запиту

Об'єкт OrderItem

Приклад: Створення замовлення

Відповідь

Купівля етикеток

Тіло запиту

Приклад запиту

Відповідь

Відповідь при недостатньому балансі

Відстеження

Параметри шляху

Приклад запиту

Відповідь

Webhooks

Доступні події

Реєстрація Webhook - Тіло запиту

Приклад: Реєстрація Webhook

Відповідь

Перевірка підпису Webhook

Приклад payload Webhook

Кошик

Ваш кошик порожній

Документація API

Автентифікація

Приклад запиту

Баланс акаунту

Параметри запиту

Приклад запиту

Відповідь

Перевірка адреси

Тіло запиту

Приклад запиту

Відповідь

Тарифи доставки

Тіло запиту

Об'єкт адреси

Об'єкт посилки

Об'єкт CustomsInfo

Об'єкт CustomsItem

Приклад запиту

Відповідь

Приклад міжнародної доставки

Створення замовлення

Список замовлень - Параметри запиту

Створення замовлення - Тіло запиту

Об'єкт OrderItem

Приклад: Створення замовлення

Відповідь

Купівля етикеток

Тіло запиту

Приклад запиту

Відповідь

Відповідь при недостатньому балансі

Відстеження

Параметри шляху

Приклад запиту

Відповідь

Webhooks