Entwickler · Post-API
Post-API, Spezifikation v1
HTTPS und JSON. Feldnamen in snake_case, Datumsangaben als YYYY-MM-DD, Geldbeträge als Dezimalzahl im Stringformat. Wir validieren jede Sendung in derselben Anfrage, daher ist die Antwort das Ergebnis.
Spezifikation v1GeplantDie Endpunkte sind geplant. Vor dem Produktivbetrieb richten wir für jeden Kunden eine Sandbox ein.
Grundlagen
| Merkmal | Wert |
|---|---|
| Produktion | https://api.alliedchb.com/v1 |
| Sandbox | https://api-test.alliedchb.com/v1 |
| Authentifizierung | Header X-Client-Id und X-Client-Secret, ein Paar für jede Umgebung. Wir senden das Secret über einen sicheren Kanal. |
| Nachverfolgung | Optionaler Header X-Request-Id. |
| Idempotenz | Über item_id: Ein zweiter POST derselben S10-Nummer gibt DUPLICATE zurück. |
| Batch-Größe | 1 bis 5,000 Sendungen in jeder Anfrage. |
| Schema | postal-items.v1.json (JSON Schema 2020-12). |
Endpunkte
- POST/v1/itemsEinen Batch von Sendungen senden. Jede Sendung erhält ihr eigenes Ergebnis.
- GET/v1/items/{item_id}Der Statusverlauf einer Sendung: die Anmeldenummer, die Ereignisse von CBP und FDA und der Zoll.
- GET/v1/healthStatusprüfung des Dienstes. Keine Authentifizierung.
Einen Batch senden
Dieselbe Anfrage in drei Sprachen. Der Body ist ein Batch nach
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.jsonAntwort: ein Ergebnis für jede Sendung
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": [] } ]}Fehler
Eine Anfrage, die als Ganzes fehlschlägt, erhält diese Fehlerstruktur. Ein Problem mit einer einzelnen Sendung kommt im Ergebnis dieser Sendung zurück.
| HTTP | Fehler | Wann |
|---|---|---|
| 400 | INVALID_JSON | Der Body ist kein gültiges JSON. |
| 401 | UNAUTHORIZED | Die Client-ID oder das Secret fehlt oder ist nicht korrekt. |
| 422 | VALIDATION_ERROR | Der Batch entspricht nicht dem Schema. field_errors nennt jedes Problem. |
| 429 | RATE_LIMITED | Zu viele Anfragen. Warten Sie und senden Sie dann erneut. |
| 500 | SERVER_ERROR | Unser Fehler. Senden Sie denselben Batch erneut: Eine wiederholte Sendung gibt DUPLICATE zurück. |
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" } ]}Validierungscodes
Wir prüfen jede Sendung nach diesen Regeln.
| Code | Regel | Ergebnis |
|---|---|---|
| SCHEMA | Die Sendung entspricht postal-items.v1.json. | Ablehnung |
| S10_FORMAT | 2 Buchstaben, 8 Ziffern, 1 Prüfziffer und ein Ländercode aus 2 Buchstaben. | Ablehnung |
| S10_CHECK_DIGIT | Gewichtung 8 6 4 2 3 5 9 7. Aus einem Ergebnis von 10 wird 0, aus 11 wird 5. | Ablehnung |
| ZIP_UNKNOWN | Die Postleitzahl des Empfängers ist eine gültige US-Postleitzahl. | Ablehnung |
| S10_US_ISSUED | Die Nummer endet auf US, also hat der USPS sie vergeben. Der Anmeldungstyp 13 braucht die Nummer des ausländischen Postbetreibers. | Warnung |
| OVER_2500 | Der Wert der Sendung liegt über $2,500 zum Wechselkurs der CBP. | Förmliche Anmeldung |
| DUPLICATE | Diese S10-Nummer liegt uns bereits vor. | Duplikat |
Statusliste
Der Status einer Sendung in
GET /v1/items/{item_id}.| Status | Bedeutung |
|---|---|
| RECEIVED | Die Sendungsdaten liegen uns vor. |
| VALIDATED | Die Sendung hat die Prüfungen bestanden. |
| FILED | Wir haben die Anmeldung an die CBP gesendet. Die Anmeldenummer steht in der Antwort. |
| CBP_RELEASED | Die CBP hat die Sendung freigegeben. |
| CBP_HOLD | Die CBP hält die Sendung zurück. |
| FDA_HOLD | Die FDA hält die Sendung zur Prüfung zurück. |
| FDA_MAY_PROCEED | Die FDA hat die Sendung freigegeben. |
| REJECTED | Die Sendung hat eine Prüfung nicht bestanden. Die Antwort nennt jedes Problem. |
Beginnen Sie mit einem Datentest
Senden Sie uns einen Beispielversand als JSON, CSV oder Excel. Wir melden jede Lücke in den Daten vor der ersten Anmeldung. Angebot auf Anfrage.
Rufen Sie (908) 291-8001 an oder schreiben Sie an mail@alliedchb.com
Diese Seite ist eine Übersetzung. Die englische Fassung dieser Website ist die offizielle Fassung. Unsere Online-Formulare und Dokumente sind auf Englisch. English