Despacho por lotes (consolidación)

Este documento describe el flujo de tres etapas para crear un lote de despacho de pago diferido de Japan Post mediante la API GraphQL de Zonos: abrir una consolidación, adjuntar n envíos y cerrarla para recibir el comprobante de despacho de Japan Post (documento manifiesto).

Cuándo usar este flujo 

El programa de pago diferido de Japan Post (後納) permite a un comerciante liquidar su factura diaria de envíos en una sola transacción al final del día, en lugar de pagar por paquete al momento de la entrega. El comerciante lleva todos los paquetes del día a la oficina de correos junto con un único comprobante de despacho (差出票) que cubre hasta 250 envíos. El franqueo se factura al Later Pay Number previamente registrado del comerciante.

Si envía etiquetas individuales de Japan Post y paga paquete por paquete en el mostrador, no necesita este flujo: llame directamente al flujo de envío individual sin una consolidación.

Descripción general 

1. shipmentConsolidationCreate            → open the batch (returns consolidation ID)
2. Attach shipments × n                   → create each shipment + label, attached to the batch
3. shipmentConsolidationUpdate(CLOSED)    → close the batch (returns the dispatch slip)

Hay dos formas de adjuntar envíos al lote: use la que mejor se adapte a su integración (o combínelas):

• Adjuntar al crear la etiqueta — pase el ID de consolidación del paso 1 en cada llamada a shipmentCreateWorkflow mediante el campo shipmentConsolidationId.
• Adjuntar envíos existentes por ID — pase shipmentIds en shipmentConsolidationCreate (para inicializar el lote) o en shipmentConsolidationUpdate (para agregar a un lote abierto). Cada envío ya debe tener su etiqueta de Japan Post.

En cualquier caso, cada etiqueta se crea con su Later Pay Number incorporado para que Japan Post la acepte en el comprobante de despacho cuando el paso 3 cierre el lote.

¿Por qué llamadas separadas en lugar de una sola mutación? Los pasos 2.1, 2.2, ..., 2.n ocurren a lo largo del día del comerciante: las etiquetas se imprimen y los paquetes se sellan a medida que llegan los pedidos. El lote no puede ser un único viaje de ida y vuelta como el flujo de envío individual: hay una brecha de varias horas entre abrir la consolidación y cerrarla.

Requisitos previos 

Antes de que este flujo funcione para una Verified Account determinada:

• Su cuenta debe tener un Later Pay Number de pago diferido de Japan Post (後納お客様番号) guardado, con un valor con guiones como 1111111111-222222-3333333333-444444. Páselo en shipmentConsolidationCreate mediante accountNumber (Paso 1).
• Su clave de API debe tener SHIPMENT_WRITE, además de los alcances estándar que requiere el flujo por envío.

Endpoint y autenticación 

Las tres operaciones siguientes son operaciones GraphQL enviadas al 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}}

Solicitud de ejemplo 

Un ejemplo para copiar y adaptar al abrir una consolidación: la mutación, sus variables y la respuesta. Esta es la llamada específica del lote que inicia el flujo; adjuntar envíos (Paso 2) reutiliza el ejemplo de envío individual, y cerrar el lote (Paso 3) devuelve el documento manifiesto. Cada campo se detalla en los pasos siguientes.

Paso 1: shipmentConsolidationCreate 

Abre la consolidación. El código de transportista fija el lote a Japan Post; todos los envíos miembros deben usar niveles de servicio de Japan Post. Si ya tiene envíos etiquetados listos, inicialice el lote con sus ID mediante shipmentIds; de lo contrario, créelo vacío y adjunte envíos en el paso 2.

Mutación:

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

Respuesta:

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

Conserve el id (p. ej., shco_01HJK...); lo usará en todo lo que sigue. El status es OPEN hasta el paso 3.

Paso 2: Adjuntar envíos 

Por cada paquete que deba enviar hoy, ejecute el flujo de envío individual encadenado completo para crear el envío y su etiqueta. Luego adjunte el envío al lote con cualquiera de los métodos siguientes.

Opción A: Adjuntar al crear la etiqueta

Pase el ID de consolidación en el paso final shipmentCreateWorkflow de la cadena. Todas las mutaciones anteriores de la cadena son idénticas al flujo de envío individual.

Los campos relevantes en shipmentCreateWorkflow:

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

Opción B: Adjuntar envíos existentes por ID

Si sus envíos ya están creados y etiquetados, agréguelos al lote abierto con shipmentIds en shipmentConsolidationUpdate:

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

Omita status en la entrada mientras siga agregando envíos; el lote permanece OPEN. Cada envío debe usar un nivel de servicio de Japan Post y tener su etiqueta (número de seguimiento) antes de cerrar el lote en el Paso 3.

Qué significa la adjunción para la etiqueta

Sea cual sea la opción que use, cuando un envío de Japan Post forma parte de una consolidación:

• El envío tiene un número de seguimiento, como de costumbre.
• El PDF de la etiqueta de envío no incluye las copias de recibo para el cliente/oficina de correos. Esos recibos se difieren al Paso 3, donde se agrupan en el documento del comprobante de despacho para todo el lote.
• El envío queda asociado a la consolidación; puede volver a consultarlo mediante shipmentConsolidation(id: ...) para ver sus miembros.

Repita este paso por cada paquete del lote del día. Hasta 250 envíos por consolidación; intentar cerrar un lote mayor falla con un error de validación claro antes de cualquier llamada a Japan Post.

También puede verificar el contenido del lote antes de cerrarlo:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

Cada envío debe mostrar un número de seguimiento aquí. Si alguno no lo tiene, su etiqueta nunca se creó; resuélvalo antes de cerrar. El status es OPEN hasta que la consolidación se cierre en el Paso 3.

Paso 3: shipmentConsolidationUpdate(status: CLOSED) 

Cierra el lote. Esta es la llamada que solicita a Japan Post generar el comprobante de despacho de pago diferido que cubre el número de seguimiento de cada miembro, y adjunta el PDF resultante a la consolidación.

Mutación:

mutation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

En una solicitud CLOSED:

1. Se valida la consolidación: ≤250 envíos, y cada miembro debe tener un número de seguimiento. Si un envío no tiene número de seguimiento (su etiqueta nunca se creó), la llamada se rechaza.
2. Se solicita a Japan Post generar un comprobante de despacho de pago diferido que cubra el número de seguimiento de cada miembro.
3. El estado pasa brevemente a MANIFEST_CREATED mientras se obtiene el PDF del comprobante, y luego a CLOSED una vez adjunto el documento.
4. El PDF del comprobante de despacho (un archivo con el comprobante más los recibos de cliente/oficina de correos de cada miembro) se adjunta a la consolidación como CustomsDocument con documentType: MANIFEST_DOCUMENT.

Respuesta:

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

Recuperar los documentos

El comprobante de despacho se adjunta directamente a la consolidación como CustomsDocument con documentType: MANIFEST_DOCUMENT; obtenga el fileUrl de la respuesta de cierre anterior, o consúltelo en cualquier momento posterior:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

Imprima el PDF en fileUrl. Contiene:

• Página 1: El comprobante de despacho de pago diferido — entréguelo en la oficina de correos.
• Páginas 2+: Los recibos de cliente/oficina de correos de cada paquete — uno grapado a cada paquete, el otro lo conserva la oficina de correos.

Una vez impreso, lleve los paquetes, el comprobante de despacho y los recibos a la oficina de correos en un solo viaje. Japan Post factura su Later Pay Number al final del período de facturación.

Cómo encaja todo 

Un día representativo para un comerciante que envía 50 paquetes de Japan Post se ve así:

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print PDF

¿Prefiere agrupar al final del día? Cree las etiquetas del día sin un ID de consolidación, luego abra la consolidación una vez con todos los valores de shipmentIds (o agréguelos por partes mediante shipmentConsolidationUpdate) y ciérrela en la misma llamada o en una posterior.

Si envía desde varias unidades de negocio o cuentas de facturación, ejecute una consolidación separada por cuenta: pase un accountNumber distinto en cada shipmentConsolidationCreate y dirija los envíos en consecuencia. ¿Envía más de 250 paquetes en un día? Abra una segunda consolidación.

Manejo de errores 

Errores de validación (detectados antes de cualquier llamada a Japan Post)

• accountNumber con formato incorrecto — rechazado en el Paso 1 (shipmentConsolidationCreate) antes de que se guarde la consolidación. El mensaje de error identifica el segmento problemático.
• >250 envíos — rechazado en el Paso 3, antes de la llamada a Japan Post.
• Envío miembro sin número de seguimiento — rechazado en el Paso 3. Significa que la creación de una etiqueta falló silenciosamente antes; investigue el envío afectado mediante shipment(id: ...) { trackingDetails }.
• Sin número de pago diferido establecido en la consolidación — rechazado en el Paso 3. Pase accountNumber en shipmentConsolidationCreate, o guarde un número de cuenta predeterminado en su cuenta de transportista de Japan Post.

Errores de la API de Japan Post

Si Japan Post rechaza la solicitud del comprobante de despacho, la mutación de cierre expone el código y el mensaje de error del transportista como error GraphQL. Los más comunes:

Reintentos

Si la llamada de cierre falla después de que Japan Post haya aceptado la solicitud del comprobante de despacho (es decir, durante la recuperación del PDF), reintentar shipmentConsolidationUpdate(status: CLOSED) es seguro: la plataforma omitirá la llamada al transportista y solo volverá a intentar obtener y adjuntar el documento.

Si el cierre falla antes de que Japan Post acepte la solicitud (error de validación, E0xx, tiempo de espera de red), no ha cambiado ningún estado; corrija la causa raíz y reintente.