Dla programistów · API pocztowe
API pocztowe, specyfikacja v1
HTTPS i JSON. Nazwy pól w snake_case, daty w formacie YYYY-MM-DD, kwoty jako ciąg znaków z liczbą dziesiętną. Sprawdzamy każdą przesyłkę w tym samym żądaniu, więc odpowiedź jest wynikiem.
Specyfikacja v1PlanowanePunkty końcowe są planowane. Przed uruchomieniem produkcyjnym otwieramy dla każdego klienta środowisko testowe (sandbox).
Podstawy
| Element | Wartość |
|---|---|
| Środowisko produkcyjne | https://api.alliedchb.com/v1 |
| Środowisko testowe | https://api-test.alliedchb.com/v1 |
| Uwierzytelnianie | Nagłówki X-Client-Id i X-Client-Secret, jedna para dla każdego środowiska. Klucz tajny przesyłamy bezpiecznym kanałem. |
| Śledzenie żądań | Opcjonalny nagłówek X-Request-Id. |
| Idempotentność | Według item_id: ponowny POST tego samego numeru S10 zwraca DUPLICATE. |
| Rozmiar partii | Od 1 do 5,000 przesyłek w każdym żądaniu. |
| Schemat | postal-items.v1.json (JSON Schema 2020-12). |
Punkty końcowe
- POST/v1/itemsWysłanie partii przesyłek. Każda przesyłka otrzymuje własny wynik.
- GET/v1/items/{item_id}Historia statusów jednej przesyłki: numer zgłoszenia, zdarzenia CBP i FDA oraz cło.
- GET/v1/healthSprawdzenie działania usługi. Bez uwierzytelniania.
Wysłanie partii
To samo żądanie w trzech językach. Treść żądania to partia
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.jsonOdpowiedź: jeden wynik dla każdej przesyłki
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": [] } ]}Błędy
Żądanie, które w całości kończy się błędem, otrzymuje odpowiedź w tej kopercie. Problem z jedną przesyłką wraca w wyniku tej przesyłki.
| HTTP | Błąd | Kiedy |
|---|---|---|
| 400 | INVALID_JSON | Treść żądania nie jest poprawnym JSON. |
| 401 | UNAUTHORIZED | Brak identyfikatora klienta lub klucza tajnego albo są one nieprawidłowe. |
| 422 | VALIDATION_ERROR | Partia nie jest zgodna ze schematem. field_errors podaje każdy problem. |
| 429 | RATE_LIMITED | Zbyt wiele żądań. Należy odczekać, a następnie wysłać ponownie. |
| 500 | SERVER_ERROR | Błąd po naszej stronie. Należy ponownie wysłać tę samą partię: powtórzona przesyłka zwraca 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" } ]}Kody walidacji
Sprawdzamy każdą przesyłkę według tych reguł.
| Kod | Reguła | Wynik |
|---|---|---|
| SCHEMA | Przesyłka jest zgodna z postal-items.v1.json. | Odrzucenie |
| S10_FORMAT | 2 litery, 8 cyfr, 1 cyfra kontrolna i 2-literowy kod kraju. | Odrzucenie |
| S10_CHECK_DIGIT | Wagi 8 6 4 2 3 5 9 7. Wynik 10 zmienia się na 0, a wynik 11 na 5. | Odrzucenie |
| ZIP_UNKNOWN | Kod ZIP adresata jest prawidłowym amerykańskim kodem ZIP. | Odrzucenie |
| S10_US_ISSUED | Numer kończy się na US, więc wydał go USPS. Zgłoszenie typu 13 wymaga numeru od zagranicznego operatora pocztowego. | Ostrzeżenie |
| OVER_2500 | Wartość przesyłki przekracza $2,500 według kursu wymiany CBP. | Zgłoszenie formalne |
| DUPLICATE | Mamy już ten numer S10. | Duplikat |
Lista statusów
Status przesyłki w
GET /v1/items/{item_id}.| Status | Znaczenie |
|---|---|
| RECEIVED | Mamy dane przesyłki. |
| VALIDATED | Przesyłka przeszła kontrole. |
| FILED | Wysłaliśmy zgłoszenie do CBP. Numer zgłoszenia jest w odpowiedzi. |
| CBP_RELEASED | CBP zwolnił przesyłkę. |
| CBP_HOLD | CBP zatrzymuje przesyłkę. |
| FDA_HOLD | FDA zatrzymuje przesyłkę do weryfikacji. |
| FDA_MAY_PROCEED | FDA zwolniła przesyłkę. |
| REJECTED | Przesyłka nie przeszła kontroli. Odpowiedź podaje każdy problem. |
Zacznijmy od testu danych
Prosimy przesłać przykładową ekspedycję w formacie JSON, CSV lub Excel. Przed pierwszym zgłoszeniem informujemy o każdej luce w danych. Wycena na zapytanie.
Prosimy dzwonić pod (908) 291-8001 lub pisać na mail@alliedchb.com
Ta strona jest tłumaczeniem. Oficjalną wersją tej witryny jest wersja angielska. Nasze formularze online i dokumenty są w języku angielskim. English