Desarrolladores · API postal
API postal, especificación v1
HTTPS y JSON. Nombres de campos en snake_case, fechas como YYYY-MM-DD, montos como cadena decimal. Validamos cada artículo en la misma solicitud, así que la respuesta es el resultado.
Especificación v1PrevistoLos endpoints están previstos. Abrimos un entorno de pruebas para cada cliente antes de producción.
Datos básicos
| Elemento | Valor |
|---|---|
| Producción | https://api.alliedchb.com/v1 |
| Entorno de pruebas | https://api-test.alliedchb.com/v1 |
| Autenticación | Encabezados X-Client-Id y X-Client-Secret, un par por cada entorno. Enviamos el secreto por un canal seguro. |
| Trazabilidad | Encabezado opcional X-Request-Id. |
| Idempotencia | Por item_id: un segundo POST con el mismo número S10 devuelve DUPLICATE. |
| Tamaño del lote | De 1 a 5,000 artículos en cada solicitud. |
| Esquema | postal-items.v1.json (JSON Schema 2020-12). |
Endpoints
- POST/v1/itemsEnvíe un lote de artículos. Cada artículo recibe su propio resultado.
- GET/v1/items/{item_id}El historial de estados de un artículo: el número de declaración, los eventos de CBP y de la FDA, y los aranceles.
- GET/v1/healthVerificación del servicio. Sin autenticación.
Enviar un lote
La misma solicitud en tres lenguajes. El cuerpo es un lote
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.jsonRespuesta: un resultado por cada artículo
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": [] } ]}Errores
Una solicitud que falla en su totalidad recibe esta estructura de error. Un problema con un solo artículo se devuelve en el resultado de ese artículo.
| HTTP | Error | Cuándo |
|---|---|---|
| 400 | INVALID_JSON | El cuerpo no es un JSON válido. |
| 401 | UNAUTHORIZED | Falta el ID de cliente o el secreto, o es incorrecto. |
| 422 | VALIDATION_ERROR | El lote no es válido según el esquema. field_errors indica cada problema. |
| 429 | RATE_LIMITED | Demasiadas solicitudes. Espere y después envíe de nuevo. |
| 500 | SERVER_ERROR | Error nuestro. Envíe de nuevo el mismo lote: un artículo repetido devuelve 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" } ]}Códigos de validación
Verificamos cada artículo con estas reglas.
| Código | Regla | Resultado |
|---|---|---|
| SCHEMA | El artículo es válido según postal-items.v1.json. | Rechazo |
| S10_FORMAT | 2 letras, 8 dígitos, 1 dígito de control y un código de país de 2 letras. | Rechazo |
| S10_CHECK_DIGIT | Pesos 8 6 4 2 3 5 9 7. Un resultado de 10 se convierte en 0, y 11 se convierte en 5. | Rechazo |
| ZIP_UNKNOWN | El código ZIP del destinatario es un código ZIP válido de EE. UU. | Rechazo |
| S10_US_ISSUED | El número termina en US, así que lo emitió USPS. La entrada tipo 13 necesita el número del operador postal extranjero. | Advertencia |
| OVER_2500 | El valor del artículo supera los $2,500 al tipo de cambio de CBP. | Declaración formal |
| DUPLICATE | Ya tenemos este número S10. | Duplicado |
Lista de estados
El estado de un artículo en
GET /v1/items/{item_id}.| Estado | Significado |
|---|---|
| RECEIVED | Tenemos los datos del artículo. |
| VALIDATED | El artículo pasó las verificaciones. |
| FILED | Enviamos la declaración a CBP. El número de declaración está en la respuesta. |
| CBP_RELEASED | CBP liberó el artículo. |
| CBP_HOLD | CBP retiene el artículo. |
| FDA_HOLD | La FDA retiene el artículo para revisarlo. |
| FDA_MAY_PROCEED | La FDA liberó el artículo. |
| REJECTED | El artículo no pasó una verificación. La respuesta indica cada problema. |
Empiece con una prueba de datos
Envíenos un despacho postal de muestra en JSON, CSV o Excel. Le informamos de cada carencia en los datos antes de la primera declaración. Cotización a solicitud.
Llame al (908) 291-8001 o escriba a mail@alliedchb.com
Esta página es una traducción. La versión en inglés de este sitio web es la versión oficial. Nuestros formularios en línea y nuestros documentos están en inglés. English