Розробникам · Поштовий 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