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:

En contentsType, los dos valores más comunes para el tráfico de Verified Account son ECOMMERCE_GOODS (vendido a un consumidor, BtoC) y COMMERCIAL_GOODS (vendido entre empresas, BtoB). Estos establecen el pkgType que Zonos envía en la llamada a la Japan Post Label API, por lo que la elección cambia lo que se imprime en la declaración aduanera — no es solo una etiqueta.

Subentrada nonDelivery

Indica a Japan Post qué hacer con el paquete si no se puede entregar — rechazado por el consignatario, rechazado en la frontera o no se puede entregar según la dirección indicada.

option acepta exactamente estos cuatro valores. No existe el valor RETURN — use RETURN_AFTER_RETENTION o RETURN_IMMEDIATELY para elegir cuándo regresa el paquete.

La API expone ambas variantes de devolución por separado; la opción Return del Dashboard cubre ambas.

transportMethod acepta AIR o MOST_ECONOMICAL, y determina cómo viaja de vuelta un paquete devuelto. Solo se aplica a las dos opciones RETURN_* — el Dashboard muestra el campo Return method correspondiente solo cuando se selecciona Return.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

El selector If undeliverable del diálogo Create label del Dashboard escribe este mismo campo, por lo que una etiqueta creada en el Dashboard y una etiqueta creada a través de la API se comportan de forma idéntica.

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.

Niveles de servicio de Japan Post 

Pase uno de estos códigos como serviceLevelCode en shipmentRatingCreateWorkflow.

Los códigos de nivel de servicio usan puntos, no guiones bajos. Es posible que vea la forma con guion bajo (japan_post_air_parcel) en mensajes de error y referencias internas, pero no es una entrada válida.

Servicios aéreos

Servicios de superficie

Elegir entre servicios similares

Small packet frente a International Air Packet. Ambos están limitados a 2 kg. japan_post.air.packet es el servicio de paquete pequeño con seguimiento de Japan Post. japan_post.air.small_packet es el equivalente sin seguimiento. Si necesita seguimiento para un paquete ligero, use japan_post.air.packet.

Variantes certificadas. Para cartas e impresos, el seguimiento se añade con la versión certificada (書留) del servicio. japan_post.air.printed_matter y japan_post.air.letter no lo incluyen por sí solos.

Códigos obsoletos

japan_post.air.epacket_light era International e-Packet Light. Japan Post renombró el servicio a International Air Packet el 1 de junio de 2026 y lo amplió a todos los países y regiones. El servicio en sí no ha cambiado.

El código anterior todavía se resuelve, por lo que las integraciones existentes siguen funcionando, pero use japan_post.air.packet para trabajos nuevos.

Códigos de modo de transporte

japan_post.air, japan_post.surface, japan_post.economy_air y japan_post.custom también se resuelven, pero identifican un modo de transporte o un valor de reserva, en lugar de un producto de correo específico. Use uno de los códigos de servicio anteriores para envíos normales.

Valide el código que envía

Un serviceLevelCode no reconocido no genera un error. La solicitud devuelve HTTP 200 sin matriz errors, serviceLevel regresa como null, y el envío se excluye del total de Landed Cost — por lo que la respuesta parece correcta mientras los importes son incorrectos.

Verifique siempre que shipmentRatingCreateWorkflow.serviceLevel no sea null antes de confiar en los totales.

Para obtener la lista actual en cualquier momento:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Esta consulta toma el ID del transportista. Pasar el código de transportista japan_post devuelve una lista vacía sin error.

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.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Este error nombra toda la variable, no el campo que realmente está mal. Casi siempre significa que un valor de enumeración dentro de esa variable no es miembro de su enum — con mayor frecuencia nonDelivery.option, contentsType o serviceLevel.

No es un problema de tipado JSON. Poner o quitar comillas en sus booleanos y números no cambiará esto, porque la carga útil nunca llega tan lejos — el enum se rechaza primero.

Para encontrar el campo incorrecto, verifique cada campo con valor de enumeración de la variable contra sus valores aceptados:

Los miembros completos de la enumeración para cualquier input aparecen en su página de tipo en la Referencia de la API.

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.