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