Como funciona o modelo de API Zonos + Japan Post
Comerciantes com Japan Post Verified Account chamam a Zonos diretamente. A Zonos usa suas próprias credenciais com a Japan Post e inclui seu Later Pay Number em toda etiqueta para que o frete postal seja cobrado na sua conta.
Em uma única solicitação GraphQL, a Zonos:
- Valida sua Verified Account e Later Pay Numbers.
- Chama a Japan Post Label API (código 52) em seu nome para gerar a etiqueta e o número de rastreamento.
- Cria um Declaration ID para o pré-pagamento de tarifas dos EUA.
- Vincula o Declaration ID ao número de rastreamento via
declarationShipmentCreate. - Retorna a etiqueta, o número de rastreamento e o registro do envio para você.
Você não precisa das suas próprias credenciais da Japan Post API (CTID / senha CT). Você precisa dos seus Japan Post Later Pay Numbers (後納お客様番号) conectados à sua Zonos Verified Account.
Qual é a sua configuração?
Todos chamam a Zonos para criar tanto a etiqueta quanto o manifest, então você nunca fornece as próprias credenciais da Japan Post (CTID / senha CT). O que muda por configuração são os headers da Zonos API que você envia — encontre sua linha abaixo e use a aba correspondente na seção Endpoint e autenticação de cada fluxo.
| ↕ | Comerciante de e-commerce↕ | Plataforma de envio (BYOA)↕ | 3PL / parceiro logístico / revendedor↕ |
|---|---|---|---|
| Quem você é | Uma marca enviando seus próprios pedidos | Uma plataforma por meio da qual muitos comerciantes criam etiquetas | Um parceiro que envia em nome de vários clientes comerciantes |
| Verified Account que você configura | Uma Verified Account (sua) | Cada comerciante configura a própria; você envia em nome dele | Uma Verified Account usada para todos os seus remetentes |
| Headers da Zonos API a enviar | apenas credentialToken (seu) | credentialToken (seu) + accountKey (de cada comerciante) | apenas credentialToken (seu) |
| Later Pay Number cobrado no frete postal | O seu | O de cada comerciante | O seu |
| Quem a Zonos fatura pelas tarifas | Você | Cada comerciante | Você |
BYOA (Bring Your Own Account): cada comerciante mantém a própria Japan Post Verified Account, e a plataforma cria etiquetas em nome desse comerciante passando a account key do comerciante, em vez de enviar sob a conta da própria plataforma.
Dois fluxos de API
Há dois padrões de integração, conforme a forma de despachar as encomendas.
Criar um envio único
A cadeia fundamental. Uma solicitação GraphQL leva um envio das entradas brutas (partes, itens, embalagem) até uma etiqueta imprimível da Japan Post. Use isso se você envia encomendas individualmente conforme os pedidos chegam.
Despacho em lote (consolidação)
O fluxo de lote com pagamento diferido. Abra uma consolidação pela manhã, anexe envios a ela ao longo do dia usando a cadeia de envio único e feche a consolidação no fim do dia para obter um dispatch slip da Japan Post cobrindo o lote inteiro. Use isso se você liquida o frete postal da Japan Post em uma única transação no fim do dia, em vez de encomenda por encomenda.
Já usa a Japan Post My Page API?
Se você atualmente cria etiquetas com a Japan Post My Page API (ctCode=52), pode manter essa integração e adicionar a Zonos para etiquetas com destino aos EUA e tarifas pré-pagas. Consulte Usar a Zonos com a My Page API para um mapeamento campo a campo e uma checklist de verificação.
Criar etiquetas via API
Integre seu sistema de fulfillment com a Zonos GraphQL API para criar etiquetas da Japan Post com tarifas pré-pagas.
Esta seção é para equipes de engenharia que estão construindo um fluxo programático de etiquetas da Japan Post com Verified Accounts. Se você é um remetente pequeno ou médio sem recursos de desenvolvimento, consulte Criar etiquetas no Dashboard.