Разработчикам · Почтовый API
Почтовый API, спецификация v1
HTTPS и JSON. Имена полей в snake_case, даты в формате YYYY-MM-DD, денежные суммы в виде десятичной строки. Мы проверяем каждое отправление в том же запросе, поэтому ответ содержит результат.
Спецификация v1ПланируетсяЭндпоинты запланированы. До запуска в рабочей среде мы открываем тестовую среду для каждого клиента.
Основные сведения
| Параметр | Значение |
|---|---|
| Рабочая среда | https://api.alliedchb.com/v1 |
| Тестовая среда | https://api-test.alliedchb.com/v1 |
| Аутентификация | Заголовки X-Client-Id и X-Client-Secret, одна пара для каждой среды. Секрет мы передаем по защищенному каналу. |
| Трассировка | Необязательный заголовок X-Request-Id. |
| Идемпотентность | По item_id: повторный POST с тем же номером S10 возвращает DUPLICATE. |
| Размер пакета | От 1 до 5,000 отправлений в каждом запросе. |
| Схема | postal-items.v1.json (JSON Schema 2020-12). |
Эндпоинты
- POST/v1/itemsПередача пакета отправлений. Каждое отправление получает свой результат.
- GET/v1/items/{item_id}История статусов одного отправления: номер декларации, события CBP и FDA и пошлина.
- GET/v1/healthПроверка работы сервиса. Без аутентификации.
Передача пакета
Один и тот же запрос на трех языках программирования. Тело запроса: пакет
postal-items.v1.curl -X POST https://api-test.alliedchb.com/v1/items \ -H "X-Client-Id: $ALLIED_CLIENT_ID" \ -H "X-Client-Secret: $ALLIED_CLIENT_SECRET" \ -H "Content-Type: application/json" \ --data @postal-items.v1.example.jsonОтвет: один результат на каждое отправление
200 OK · application/json
{ "batch_ref": "POST-DISPATCH-2026-10-01-A", "results": [ { "item_id": "CP123456785CA", "result": "ACCEPTED", "route": "ET13", "ace_bill": { "mode": "AIR", "bill_type": "R", "issuer": "", "number": "SFPCP123456785CA" }, "warnings": [], "field_errors": [] } ]}Ошибки
Если ошибка относится ко всему запросу, ответ имеет такую структуру. Проблема с одним отправлением возвращается в результате этого отправления.
| HTTP | Ошибка | Когда |
|---|---|---|
| 400 | INVALID_JSON | Тело запроса не является корректным JSON. |
| 401 | UNAUTHORIZED | Идентификатор клиента или секрет отсутствует или неверен. |
| 422 | VALIDATION_ERROR | Пакет не соответствует схеме. В field_errors указана каждая проблема. |
| 429 | RATE_LIMITED | Слишком много запросов. Подождите, затем отправьте запрос снова. |
| 500 | SERVER_ERROR | Ошибка на нашей стороне. Отправьте тот же пакет снова: для повторно переданного отправления вернется DUPLICATE. |
422 · VALIDATION_ERROR
{ "error": "VALIDATION_ERROR", "message": "The batch does not match postal-items.v1.json", "field_errors": [ { "field": "items[3].contents[0].hs_code", "code": "SCHEMA", "message": "required" } ]}Коды проверки
Мы проверяем каждое отправление по этим правилам.
| Код | Правило | Результат |
|---|---|---|
| SCHEMA | Отправление соответствует postal-items.v1.json. | Отклонение |
| S10_FORMAT | 2 буквы, 8 цифр, 1 контрольная цифра и 2-буквенный код страны. | Отклонение |
| S10_CHECK_DIGIT | Веса 8 6 4 2 3 5 9 7. Результат 10 заменяется на 0, а 11 на 5. | Отклонение |
| ZIP_UNKNOWN | Индекс ZIP адресата является действительным индексом ZIP США. | Отклонение |
| S10_US_ISSUED | Номер заканчивается на US, то есть его выдала USPS. Для декларации типа 13 нужен номер от иностранного почтового оператора. | Предупреждение |
| OVER_2500 | Стоимость отправления превышает $2,500 по обменному курсу CBP. | Полная декларация |
| DUPLICATE | Этот номер S10 у нас уже есть. | Дубликат |
Список статусов
Статус отправления в
GET /v1/items/{item_id}.| Статус | Значение |
|---|---|
| RECEIVED | Мы получили данные отправления. |
| VALIDATED | Отправление прошло проверки. |
| FILED | Мы отправили декларацию в CBP. Номер декларации указан в ответе. |
| CBP_RELEASED | CBP выпустила отправление. |
| CBP_HOLD | CBP задерживает отправление. |
| FDA_HOLD | FDA задерживает отправление для проверки. |
| FDA_MAY_PROCEED | FDA выпустило отправление. |
| REJECTED | Отправление не прошло проверку. В ответе указана каждая проблема. |
Начните с тестирования данных
Пришлите нам образец данных отправки в JSON, CSV или Excel. До первой декларации мы сообщаем о каждом пробеле в данных. Стоимость по запросу.
Звоните (908) 291-8001 или пишите на mail@alliedchb.com
Эта страница является переводом. Официальной версией этого сайта является английская версия. Наши онлайн-формы и документы составлены на английском языке. English