Crear un envío individual

CreateDeclarationShipment encadena seis mutaciones *Workflow en una única solicitud GraphQL. Cada paso se basa en los datos que proporcionaron los pasos anteriores, y todos se envían juntos para que se pueda crear un envío completo en una sola solicitud:

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

Las mutaciones Workflow están diseñadas para encadenarse: no necesita pasar IDs de un paso al siguiente, ni enviar una solicitud separada por paso. Envíe el documento completo y reciba el Shipment final.

Cuando el serviceLevel del paso final es un nivel de servicio de Japan Post (japan_post.*), Zonos llama a la Japan Post Label API (código 52) en su nombre usando los Later Pay Numbers de su Verified Account, genera la etiqueta y el número de seguimiento, crea el Declaration ID y los vincula — todo dentro de ese paso final shipmentCreateWorkflow.

¿Por qué una sola mutación? Cada paso depende del anterior (Landed Cost necesita los artículos y las partes; la etiqueta necesita todo). Agruparlos en un único documento GraphQL mantiene los datos consistentes y evita cinco solicitudes adicionales.

Endpoint y autenticación 

Las solicitudes de esta cadena utilizan el mismo endpoint. Lo que pase en los encabezados depende de su configuración — elija su pestaña.

URL:

https://api.zonos.com/graphql

Encabezados:

credentialToken: {{YOUR_API_TOKEN}}

Ejemplo de solicitud 

Una solicitud completa de CreateDeclarationShipment que puede copiar y adaptar — la mutación, sus variables y la respuesta — para un paquete individual de Japan Post enviado DDP a EE. UU. Cada entrada se detalla en la sección paso a paso a continuación.

Paso a paso 

La columna Estado de cada tabla a continuación utiliza estos términos:

• Obligatorio — la solicitud falla sin este campo.
• Obligatorio para la etiqueta — opcional en el esquema GraphQL, pero necesario para producir una etiqueta válida de Japan Post con destino a EE. UU.
• Condicional — obligatorio según otro campo (se indica en línea).
• Recomendado — opcional, pero determina aranceles e impuestos precisos.
• Opcional — no es necesario.

1. partyCreateWorkflow

Crea las partes involucradas en el envío — como mínimo un ORIGIN (desde dónde se envía) y un DESTINATION (el comprador / consignatario).

Ejemplo de carga útil:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

La respuesta devuelve los IDs de Party creados y los campos de dirección resueltos.

2. itemCreateWorkflow

Crea los artículos de línea que componen el envío. Son los SKU que aparecerán en la factura comercial y que determinan el cálculo de Landed Cost.

El código HS, el país de origen y el importe son los tres campos que más influyen en el resultado de aranceles/impuestos en el paso 5.

3. cartonsCreateWorkflow

Crea los paquetes físicos — las cajas, bolsas de polietileno o sobres que contendrán los artículos.

Cada cartón se convierte en un paquete en la etiqueta del transportista en el paso 6. Varios cartones → envío multipieza con un número de seguimiento por cartón.

4. shipmentRatingCreateWorkflow

Registra la cotización de tarifa que el comerciante cobra al comprador por el envío.

Esta es la tarifa que se cotizó al comprador en Checkout. Se incorpora al cálculo de Landed Cost como subtotal de "shipping" para que los aranceles e impuestos se calculen contra el valor CIF correcto.

5. landedCostCalculateWorkflow

Ejecuta el cálculo de aranceles, impuestos y tasas para el país de destino. Utiliza los artículos, las partes y el costo de envío de los pasos anteriores.

La respuesta incluye amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — son las cifras que muestra al comprador en Checkout y que se imprimen en la factura comercial.

6. shipmentCreateWorkflow

El paso final — crea la entidad Shipment, genera la etiqueta del transportista y (opcionalmente) la factura comercial / packing slip.

Para Japan Post Verified Accounts, aquí es donde Zonos llama a la Japan Post Label API (código 52) en su nombre, inserta sus Later Pay Numbers, crea el Declaration ID y vincula el Declaration ID al número de seguimiento devuelto por Japan Post.

Campos clave:

Subentrada references

Estos campos se imprimen en la etiqueta del transportista y/o en la factura comercial. Úselos para mostrar números de PO, números de licencia y observaciones de texto libre que el consignatario o la autoridad aduanera necesiten ver.

Respuesta

Los campos relevantes del Shipment devuelto son:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number es el número de seguimiento de Japan Post.

El objeto label puede devolver la etiqueta de dos formas — solicite la que se adapte a su flujo de trabajo (o ambas):

Seleccione solo los campos que necesite. Solicitar url mantiene la respuesta pequeña; solicitar labelImage devuelve la etiqueta completa en línea para que no necesite una segunda solicitud para obtenerla. El ejemplo anterior solicita url.

Manejo de errores 

• Errores de validación (campos obligatorios faltantes, códigos de país no válidos, etc.) se devuelven en la matriz estándar de errores GraphQL errors y detienen el resto de la cadena.
• Errores de Japan Post (fallo en la generación de la etiqueta, dirección no válida, etc.) aparecen como errores GraphQL en shipmentCreateWorkflow. Si se necesita un reintento, contacte con soporte — la ruta recomendada es volver a enviar la mutación completa con la entrada corregida.

Permisos 

Cada paso está protegido de forma independiente. Su clave de API debe tener el alcance de escritura para cada entidad de la cadena (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). El rol estándar de comerciante en una Verified Account otorga todos estos permisos.

Próximos pasos 

• Despacho por lotes (consolidación) — agrupe los paquetes del día en un comprobante de despacho de Japan Post con pago diferido.