自社システムから直接、プログラムで検証済みアカウントのカタログを構築できます。
カタログAPIは、検証済みアカウントのカタログを構築する3つの方法のうちの1つで、開発リソースがあり、商品データをすでに保持しているシステム(ERP、WMS、PIM、または配送プラットフォーム)をお持ちの荷送人向けの選択肢です。そのシステムが信頼できる情報源として維持され、チャネル連携から同期したりCSVファイルをアップロードしたりする代わりに、商品を直接Zonosに書き込みます。対応チャネルで販売している場合や、コードを書きたくない場合は、これら2つの方法でより少ない手間で同じカタログを構築できます。
API経由で作成されたアイテムは、他のソースから追加されたアイテムとまったく同じように扱われます。カタログに登録されたアイテムは、どのように追加されたかに関係なく同じです。HSコードを指定しなかった場合は各アイテムが通関用に分類され、米国パートナー政府機関(PGA)の要件についてスクリーニングされ、そのアイテムを含む発送品の関税と税金の計算に使用されます。
ただし、その一部はAPIの対象外です。PGAスクリーニングでアイテムに対応が必要のフラグが付いた場合、そのフラグに関連するコンプライアンス質問票はDashboardで回答・確認する必要があります。これに対応するAPIはありませんが、Zonosが可能な範囲で事前入力するため、作業の大部分は確認と承認になります。この連携を構築する担当者と、フラグを解消する担当者は通常異なるため、カタログの読み込み後に組織内の誰かがDashboardでフラグに対応するよう計画してください。フラグが付いたアイテムの発送はブロックされませんが、発送前にフラグを解消しておくことで、発送品が米国の国境で保留されるのを防げます。
発送する商品ごとにカタログアイテムを作成します。
各アイテムに、郵便キャリアが引き継ぐ識別子が含まれていることを確認します。
発送データがZonosに届くと、各行がカタログアイテムと照合され、そのアイテムの商品データが計算に適用されます。
catalogItemCreateはリストを受け付けるため、1回のリクエストで多数の商品を送信できます。
catalogItemCreate
mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
catalogItemCreate(input: $input) {
id
itemKey
name
productId
sku
hsCode
customsDescription
countryOfOrigin
}
SKUまたは商品IDがすでに存在する商品を送信すると、Zonosは2つ目の商品を追加するのではなく、その商品を更新します。再試行や繰り返し実行しても問題ありません。
その反面、SKUまたは商品IDが同じ異なる2つの商品は1つに統合されます。一括読み込みの前に、データに重複がないか確認してください。
manufacturerProductId
gtin
measurements
amount
currencyCode
itemType
PHYSICAL_GOOD
DIGITAL_GOOD
SERVICE
SUBSCRIPTION
BUNDLE
PARTIAL_ITEM
provinceOfOrigin
productComposition
{material, percentage}
catalogItemUrl
imageUrl
検証済みアカウントでEUに発送する場合、2026年11月1日から、EUは150ユーロ以下の企業対消費者(B2C)出荷に商品識別子(PID)を求めます。識別子はカタログアイテムに保存してください。ほとんどの検証済みアカウントでは、郵便事業者がZonosに発送データを送信し、Zonosが発送品の各アイテムをカタログと照合して、保存された識別子を適用します。そのため、発送時に追加で何かを送信する必要はありません。
新しい商品の識別子はcatalogItemCreateで送信します。すでにカタログにある商品については、同じフィールドを受け付けるcatalogItemUpdateで送信してください。Zonosが両者を関連付けられるよう、各アイテムのskuは他の場所で使用しているSKUと一致させてください。
catalogItemUpdate
gtinは、ダッシュやスペースを含めず数字のみで送信してください。UPC、EAN、JAN、13桁のISBNの値はすべてこの1つのフィールドに入ります。10桁のISBNをお持ちの場合は、代わりに13桁のものを送信してください。
商品にバーコードがない場合は、空の文字列を送信したり、SKUを再利用したり、N/Aなどのプレースホルダーテキストを入力したりせず、gtinを省略してください。
N/A
Landed Cost APIをご自身で呼び出す場合は、landed costリクエストにこれらの識別子を含めることもできます。ただし、発送データをZonosに送信するのは郵便事業者であるため、ほとんどの検証済みアカウントではこれを行いません。
規制の要件については、EU商品識別子ガイドをご覧ください。
Zonosは、お客様の識別子を使用して、各発送行をカタログアイテムに関連付けます。照合の順序は、商品ID、次にSKU、最後に名前です。使用する識別子は、カタログとキャリアに送信するデータの間で正確かつ一貫した状態に保ってください。
郵便発送にはさらに制約があります。Zonosが郵便キャリアから受け取るフィールドは限られており、多くのレーンでは、商品固有の情報を含んで届くフィールドは税関申告用の説明のみです。カタログ全体で同一の説明では、それだけで何かを識別することはできません。
キャリアに送信する発送データで識別子をどのような書式にするかは、郵便事業者によって異なります。郵便事業者ごとに、発送品をカタログと照合する方法が異なるためです。すべての郵便事業者に移動し、ご利用の郵便事業者を選択してください。そのページで、その郵便事業者での照合の仕組みと、送信すべき内容を正確に確認できます。
アイテムのcustomsDescriptionをキャリアに送信する文字列と同じにすることは必須ではありませんが、同じにしておくと、行が一致せず原因を調べる必要がある場合に、両者を直接比較できます。
照合が失敗する主なケースは次のとおりです。
この動作はまだ最終決定されておらず、リリース前に変更される可能性があります。
catalogItemUpdateは、作成時と同じ入力型を受け取ります。変更したいフィールドのみを送信してください。
mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
catalogItemUpdate(input: $input) {
注: 省略したフィールドは変更されないため、部分的な更新を安全に行えます。nullを送信しても値はクリアされず、無視されます。値を別の値で上書きすることはできますが、APIで値を空にすることはできません。フィールドをクリアする必要がある場合は、Zonosの担当者にお問い合わせください。
null
catalogItemクエリは、id、productId、またはskuを受け付けます。Zonosが商品について保持している情報を確認する際に使用してください。
catalogItem
query CatalogItem($sku: String!) {
catalogItem(sku: $sku) {
catalogItemDeleteは、お客様のSKUや商品IDではなく、ZonosのカタログアイテムIDを受け取ります。まずcatalogItemクエリでIDを確認してください。
catalogItemDelete
mutation CatalogItemDelete($input: [ID!]!) {
catalogItemDelete(input: $input)
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
カタログAPI
カタログAPI
自社システムから直接、プログラムで検証済みアカウントのカタログを構築できます。
カタログAPIは、検証済みアカウントのカタログを構築する3つの方法のうちの1つで、開発リソースがあり、商品データをすでに保持しているシステム(ERP、WMS、PIM、または配送プラットフォーム)をお持ちの荷送人向けの選択肢です。そのシステムが信頼できる情報源として維持され、チャネル連携から同期したりCSVファイルをアップロードしたりする代わりに、商品を直接Zonosに書き込みます。対応チャネルで販売している場合や、コードを書きたくない場合は、これら2つの方法でより少ない手間で同じカタログを構築できます。
API経由で作成されたアイテムは、他のソースから追加されたアイテムとまったく同じように扱われます。カタログに登録されたアイテムは、どのように追加されたかに関係なく同じです。HSコードを指定しなかった場合は各アイテムが通関用に分類され、米国パートナー政府機関(PGA)の要件についてスクリーニングされ、そのアイテムを含む発送品の関税と税金の計算に使用されます。
ただし、その一部はAPIの対象外です。PGAスクリーニングでアイテムに対応が必要のフラグが付いた場合、そのフラグに関連するコンプライアンス質問票はDashboardで回答・確認する必要があります。これに対応するAPIはありませんが、Zonosが可能な範囲で事前入力するため、作業の大部分は確認と承認になります。この連携を構築する担当者と、フラグを解消する担当者は通常異なるため、カタログの読み込み後に組織内の誰かがDashboardでフラグに対応するよう計画してください。フラグが付いたアイテムの発送はブロックされませんが、発送前にフラグを解消しておくことで、発送品が米国の国境で保留されるのを防げます。
仕組み
発送する商品ごとにカタログアイテムを作成します。
各アイテムに、郵便キャリアが引き継ぐ識別子が含まれていることを確認します。
発送データがZonosに届くと、各行がカタログアイテムと照合され、そのアイテムの商品データが計算に適用されます。
カタログアイテムを作成する
catalogItemCreateはリストを受け付けるため、1回のリクエストで多数の商品を送信できます。mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}同じ商品を2回送信する場合
SKUまたは商品IDがすでに存在する商品を送信すると、Zonosは2つ目の商品を追加するのではなく、その商品を更新します。再試行や繰り返し実行しても問題ありません。
その反面、SKUまたは商品IDが同じ異なる2つの商品は1つに統合されます。一括読み込みの前に、データに重複がないか確認してください。
フィールド
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamountを指定する場合は必須です。itemTypePHYSICAL_GOOD、DIGITAL_GOOD、SERVICE、SUBSCRIPTION、BUNDLE、またはPARTIAL_ITEMです。物理的でないアイテムが商品として申告されるのを防ぎます。provinceOfOriginproductComposition{material, percentage}のリストです。これがないと、繊維製品は6桁を超えて分類できません。catalogItemUrlimageUrlEU商品識別子(PID)を追加する
検証済みアカウントでEUに発送する場合、2026年11月1日から、EUは150ユーロ以下の企業対消費者(B2C)出荷に商品識別子(PID)を求めます。識別子はカタログアイテムに保存してください。ほとんどの検証済みアカウントでは、郵便事業者がZonosに発送データを送信し、Zonosが発送品の各アイテムをカタログと照合して、保存された識別子を適用します。そのため、発送時に追加で何かを送信する必要はありません。
skumanufacturerProductIdgtin新しい商品の識別子は
catalogItemCreateで送信します。すでにカタログにある商品については、同じフィールドを受け付けるcatalogItemUpdateで送信してください。Zonosが両者を関連付けられるよう、各アイテムのskuは他の場所で使用しているSKUと一致させてください。mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}gtinは、ダッシュやスペースを含めず数字のみで送信してください。UPC、EAN、JAN、13桁のISBNの値はすべてこの1つのフィールドに入ります。10桁のISBNをお持ちの場合は、代わりに13桁のものを送信してください。商品にバーコードがない場合は、空の文字列を送信したり、SKUを再利用したり、
N/Aなどのプレースホルダーテキストを入力したりせず、gtinを省略してください。Landed Cost APIをご自身で呼び出す場合は、landed costリクエストにこれらの識別子を含めることもできます。ただし、発送データをZonosに送信するのは郵便事業者であるため、ほとんどの検証済みアカウントではこれを行いません。
規制の要件については、EU商品識別子ガイドをご覧ください。
アイテムを照合可能にする
Zonosは、お客様の識別子を使用して、各発送行をカタログアイテムに関連付けます。照合の順序は、商品ID、次にSKU、最後に名前です。使用する識別子は、カタログとキャリアに送信するデータの間で正確かつ一貫した状態に保ってください。
郵便発送にはさらに制約があります。Zonosが郵便キャリアから受け取るフィールドは限られており、多くのレーンでは、商品固有の情報を含んで届くフィールドは税関申告用の説明のみです。カタログ全体で同一の説明では、それだけで何かを識別することはできません。
キャリアに送信する発送データで識別子をどのような書式にするかは、郵便事業者によって異なります。郵便事業者ごとに、発送品をカタログと照合する方法が異なるためです。すべての郵便事業者に移動し、ご利用の郵便事業者を選択してください。そのページで、その郵便事業者での照合の仕組みと、送信すべき内容を正確に確認できます。
アイテムの
customsDescriptionをキャリアに送信する文字列と同じにすることは必須ではありませんが、同じにしておくと、行が一致せず原因を調べる必要がある場合に、両者を直接比較できます。照合が失敗する主なケースは次のとおりです。
カタログアイテムを更新する
catalogItemUpdateは、作成時と同じ入力型を受け取ります。変更したいフィールドのみを送信してください。mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}アイテムを読み取る
catalogItemクエリは、id、productId、またはskuを受け付けます。Zonosが商品について保持している情報を確認する際に使用してください。query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}カタログアイテムを削除する
catalogItemDeleteは、お客様のSKUや商品IDではなく、ZonosのカタログアイテムIDを受け取ります。まずcatalogItemクエリでIDを確認してください。mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}関連情報
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
このページは役に立ちましたか?