De Catalog API is een van de drie manieren om uw Verified Account-catalogus op te bouwen, en het is de optie voor verzenders met ontwikkelcapaciteit en een systeem dat hun productgegevens al bevat—een ERP, WMS, PIM of verzendplatform. Dat systeem blijft de bron van waarheid en schrijft producten rechtstreeks naar Zonos, in plaats van te synchroniseren via een kanaalintegratie of een CSV-bestand te uploaden. Verkoopt u via een ondersteund kanaal, of schrijft u liever geen code, dan bouwen die twee opties dezelfde catalogus op met minder werk.
Artikelen die via de API worden aangemaakt, worden precies zo behandeld als artikelen uit elke andere bron—zodra een artikel in uw catalogus staat, maakt het voor Zonos niet uit hoe het daar is gekomen. Elk artikel wordt voor de douane geclassificeerd als u geen HS-code hebt opgegeven, gescreend op Amerikaanse Partner Government Agency (PGA)-vereisten en gebruikt om invoerrechten en belastingen te berekenen voor de zendingen waarin het voorkomt.
Eén onderdeel daarvan valt buiten de API. Wanneer PGA-screening een artikel markeert als Needs attention, moet de compliancevragenlijst achter die markering in Dashboard worden ingevuld en bevestigd—daar is geen API voor, en Zonos vult vooraf in wat mogelijk is, zodat het meeste werk bestaat uit controleren en bevestigen. Degene die deze integratie bouwt, is meestal niet degene die die markeringen afhandelt, dus reken erop dat iemand in uw organisatie ze in Dashboard doorloopt nadat uw catalogus is geladen. Gemarkeerde artikelen worden niet geblokkeerd voor verzending, maar door ze af te handelen voordat u verzendt, voorkomt u dat een zending aan de Amerikaanse grens wordt vastgehouden.
Maak een catalogusartikel aan voor elk product dat u verzendt.
Zorg dat elk artikel een identifier heeft die uw postvervoerder doorgeeft.
Wanneer uw zendingsgegevens Zonos bereiken, wordt elke regel gekoppeld aan uw catalogusartikel en worden de productgegevens van dat artikel toegepast op de berekening.
Catalogusartikelen aanmaken
catalogItemCreate accepteert een lijst, zodat u veel producten in één request kunt versturen.
Als u een product verstuurt waarvan de SKU of product-ID al bestaat, werkt Zonos dat product bij in plaats van een tweede toe te voegen. Nieuwe pogingen en herhaalde runs zijn veilig.
De keerzijde is dat twee verschillende producten met dezelfde SKU of product-ID worden samengevoegd tot één. Controleer uw gegevens op duplicaten voordat u een bulkupload uitvoert.
Uw unieke identifier voor het product. *Elk product heeft een SKU of een product-ID nodig, of beide.
productId
Ja*
De identifier van uw platform voor het product. *Elk product heeft een SKU of een product-ID nodig, of beide.
manufacturerProductId
Alleen EU
De Non-Standardised Manufacturer Product Identifier (NS-PID). Verplicht bij B2C-zendingen naar de EU met een waarde van 150 EUR of minder.
gtin
Alleen EU
De Standardised Manufacturer Product Identifier (S-PID), alleen cijfers. Verplicht bij B2C-zendingen naar de EU met een waarde van 150 EUR of minder, als het product een barcode heeft.
name
Ja
De productnaam.
customsDescription
Aanbevolen
Wat het product is, in eenvoudige bewoordingen, voor de douaneaangifte. Gebruik „Katoenen T-shirt”, niet „Summer Vibes Tee”.
countryOfOrigin
Aanbevolen
De 2-letterige ISO-code van het land waar het product is vervaardigd. Nodig om invoerrechten nauwkeurig te berekenen.
measurements
Aanbevolen
Gewicht en afmetingen, gebruikt voor tariefberekening en douaneaangifte.
hsCode
Nee
De universele 6-cijferige HS-code. Als u deze weglaat, classificeert Zonos het product op basis van de naam en beschrijving.
amount
Nee
De productprijs als getal.
currencyCode
Nee
De 3-letterige ISO-code van de valuta van de prijs. Verplicht wanneer u amount opgeeft.
itemType
Nee
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE of PARTIAL_ITEM. Voorkomt dat niet-fysieke artikelen als handelswaar worden aangegeven.
provinceOfOrigin
Nee
De staat of provincie waar het product vandaan komt. Vereist door sommige bestemmingslanden.
productComposition
Nee
Een lijst van {material, percentage}. Zonder deze gegevens kunnen textielproducten niet verder dan 6 cijfers worden geclassificeerd.
catalogItemUrl
Nee
Een link naar de productpagina op uw site. Verbetert de nauwkeurigheid van de classificatie.
imageUrl
Nee
Een openbaar toegankelijke URL voor de productafbeelding. Verbetert de nauwkeurigheid van de classificatie.
EU-productidentificatoren (PID's) toevoegen
Als u met uw Verified Account naar de EU verzendt, vereist de EU vanaf 1 november 2026 productidentificatoren (PID's) op business-to-consumerzendingen (B2C) met een waarde van 150 EUR of minder. Sla ze op bij uw catalogusartikelen. Bij de meeste Verified Accounts stuurt uw postbedrijf de zendingsgegevens naar Zonos, en koppelt Zonos elk artikel in de zending aan uw catalogus en past het de identificatoren toe die u hebt opgeslagen. U hoeft bij het verzenden dus niets extra's te versturen.
Verstuur de identificatoren met catalogItemCreate voor nieuwe producten. Voor producten die al in uw catalogus staan, verstuurt u ze met catalogItemUpdate, dat dezelfde velden accepteert. Laat de sku van elk artikel overeenkomen met de SKU die u overal elders gebruikt, zodat Zonos de twee aan elkaar kan koppelen.
Verstuur de gtin alleen als cijfers, zonder streepjes of spaties. UPC-, EAN-, JAN- en 13-cijferige ISBN-waarden gaan allemaal in dit ene veld. Hebt u een 10-cijferig ISBN, verstuur dan in plaats daarvan de 13-cijferige versie.
Als een product geen barcode heeft, laat gtin dan weg in plaats van een lege string te versturen, uw SKU te hergebruiken of het veld te vullen met plaatsvervangende tekst zoals N/A.
Als u de Landed Cost API zelf aanroept, kunt u deze identificatoren ook opnemen in uw landed cost-request. De meeste Verified Accounts doen dat niet, omdat het postbedrijf degene is die de zendingsgegevens naar Zonos stuurt.
Zonos koppelt elke zendingsregel aan een catalogusartikel met behulp van uw identifiers, in deze volgorde: product-ID, dan SKU, dan naam. Zorg dat de identifiers die u gebruikt accuraat en consistent zijn tussen uw catalogus en de gegevens die u naar uw vervoerder stuurt.
Voor postzendingen geldt een extra beperking. Zonos ontvangt een beperkte set velden van postvervoerders, en op veel routes is de douanebeschrijving het enige veld dat iets productspecifieks bevat. Een beschrijving die in uw hele catalogus identiek is, kan op zichzelf niets identificeren.
Hoe u de identifier opmaakt in de zendingsgegevens die u naar uw vervoerder stuurt, hangt af van uw postbedrijf, omdat elk postbedrijf zendingen op een andere manier aan uw catalogus koppelt. Ga naar alle postbedrijven en selecteer uw postbedrijf. Op die pagina ziet u hoe het koppelen voor dat postbedrijf werkt en wat u precies moet versturen.
Het is niet verplicht om de customsDescription van het artikel gelijk te stellen aan de tekst die u naar uw vervoerder stuurt, maar het maakt beide kanten direct vergelijkbaar wanneer een regel niet overeenkomt en u moet uitzoeken waarom.
Koppelen mislukt vaak wanneer:
De identifier waarop uw postbedrijf koppelt ontbreekt in de zendingsgegevens.
De identifier niet exact overeenkomt met iets in uw catalogus.
De identifier wordt afgekapt door de tekenlimiet van de vervoerder.
De opmaak verschilt tussen zendingen.
Dit gedrag wordt nog uitgewerkt en kan wijzigen vóór de lancering.
Catalogusartikelen bijwerken
catalogItemUpdate gebruikt hetzelfde invoertype als create. Verstuur alleen de velden die u wilt wijzigen.
Opmerking: Weggelaten velden blijven ongewijzigd, waardoor gedeeltelijke updates veilig zijn. Het versturen van null wist geen waarde; het wordt genegeerd. U kunt een waarde overschrijven met een andere, maar u kunt deze niet leegmaken via de API. Neem contact op met uw Zonos-vertegenwoordiger als een veld moet worden gewist.
Uw artikelen teruglezen
De catalogItem-query accepteert id, productId of sku. Gebruik deze om te controleren welke gegevens Zonos voor een product heeft.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Catalogusartikelen verwijderen
catalogItemDelete accepteert Zonos-catalogusartikel-ID's, niet uw SKU's of product-ID's. Zoek het ID eerst op met de catalogItem-query.
Catalog API
Catalog API
Bouw uw Verified Account-catalogus programmatisch op, rechtstreeks vanuit uw eigen systeem.
De Catalog API is een van de drie manieren om uw Verified Account-catalogus op te bouwen, en het is de optie voor verzenders met ontwikkelcapaciteit en een systeem dat hun productgegevens al bevat—een ERP, WMS, PIM of verzendplatform. Dat systeem blijft de bron van waarheid en schrijft producten rechtstreeks naar Zonos, in plaats van te synchroniseren via een kanaalintegratie of een CSV-bestand te uploaden. Verkoopt u via een ondersteund kanaal, of schrijft u liever geen code, dan bouwen die twee opties dezelfde catalogus op met minder werk.
Artikelen die via de API worden aangemaakt, worden precies zo behandeld als artikelen uit elke andere bron—zodra een artikel in uw catalogus staat, maakt het voor Zonos niet uit hoe het daar is gekomen. Elk artikel wordt voor de douane geclassificeerd als u geen HS-code hebt opgegeven, gescreend op Amerikaanse Partner Government Agency (PGA)-vereisten en gebruikt om invoerrechten en belastingen te berekenen voor de zendingen waarin het voorkomt.
Eén onderdeel daarvan valt buiten de API. Wanneer PGA-screening een artikel markeert als Needs attention, moet de compliancevragenlijst achter die markering in Dashboard worden ingevuld en bevestigd—daar is geen API voor, en Zonos vult vooraf in wat mogelijk is, zodat het meeste werk bestaat uit controleren en bevestigen. Degene die deze integratie bouwt, is meestal niet degene die die markeringen afhandelt, dus reken erop dat iemand in uw organisatie ze in Dashboard doorloopt nadat uw catalogus is geladen. Gemarkeerde artikelen worden niet geblokkeerd voor verzending, maar door ze af te handelen voordat u verzendt, voorkomt u dat een zending aan de Amerikaanse grens wordt vastgehouden.
Hoe het werkt
Maak een catalogusartikel aan voor elk product dat u verzendt.
Zorg dat elk artikel een identifier heeft die uw postvervoerder doorgeeft.
Wanneer uw zendingsgegevens Zonos bereiken, wordt elke regel gekoppeld aan uw catalogusartikel en worden de productgegevens van dat artikel toegepast op de berekening.
Catalogusartikelen aanmaken
catalogItemCreateaccepteert een lijst, zodat u veel producten in één request kunt versturen.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Hetzelfde product twee keer versturen
Als u een product verstuurt waarvan de SKU of product-ID al bestaat, werkt Zonos dat product bij in plaats van een tweede toe te voegen. Nieuwe pogingen en herhaalde runs zijn veilig.
De keerzijde is dat twee verschillende producten met dezelfde SKU of product-ID worden samengevoegd tot één. Controleer uw gegevens op duplicaten voordat u een bulkupload uitvoert.
Velden
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamountopgeeft.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEofPARTIAL_ITEM. Voorkomt dat niet-fysieke artikelen als handelswaar worden aangegeven.provinceOfOriginproductComposition{material, percentage}. Zonder deze gegevens kunnen textielproducten niet verder dan 6 cijfers worden geclassificeerd.catalogItemUrlimageUrlEU-productidentificatoren (PID's) toevoegen
Als u met uw Verified Account naar de EU verzendt, vereist de EU vanaf 1 november 2026 productidentificatoren (PID's) op business-to-consumerzendingen (B2C) met een waarde van 150 EUR of minder. Sla ze op bij uw catalogusartikelen. Bij de meeste Verified Accounts stuurt uw postbedrijf de zendingsgegevens naar Zonos, en koppelt Zonos elk artikel in de zending aan uw catalogus en past het de identificatoren toe die u hebt opgeslagen. U hoeft bij het verzenden dus niets extra's te versturen.
skumanufacturerProductIdgtinVerstuur de identificatoren met
catalogItemCreatevoor nieuwe producten. Voor producten die al in uw catalogus staan, verstuurt u ze metcatalogItemUpdate, dat dezelfde velden accepteert. Laat deskuvan elk artikel overeenkomen met de SKU die u overal elders gebruikt, zodat Zonos de twee aan elkaar kan koppelen.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}Verstuur de
gtinalleen als cijfers, zonder streepjes of spaties. UPC-, EAN-, JAN- en 13-cijferige ISBN-waarden gaan allemaal in dit ene veld. Hebt u een 10-cijferig ISBN, verstuur dan in plaats daarvan de 13-cijferige versie.Als een product geen barcode heeft, laat
gtindan weg in plaats van een lege string te versturen, uw SKU te hergebruiken of het veld te vullen met plaatsvervangende tekst zoalsN/A.Als u de Landed Cost API zelf aanroept, kunt u deze identificatoren ook opnemen in uw landed cost-request. De meeste Verified Accounts doen dat niet, omdat het postbedrijf degene is die de zendingsgegevens naar Zonos stuurt.
Zie de handleiding EU-productidentificatoren voor wat de regelgeving vereist.
Maak uw artikelen koppelbaar
Zonos koppelt elke zendingsregel aan een catalogusartikel met behulp van uw identifiers, in deze volgorde: product-ID, dan SKU, dan naam. Zorg dat de identifiers die u gebruikt accuraat en consistent zijn tussen uw catalogus en de gegevens die u naar uw vervoerder stuurt.
Voor postzendingen geldt een extra beperking. Zonos ontvangt een beperkte set velden van postvervoerders, en op veel routes is de douanebeschrijving het enige veld dat iets productspecifieks bevat. Een beschrijving die in uw hele catalogus identiek is, kan op zichzelf niets identificeren.
Hoe u de identifier opmaakt in de zendingsgegevens die u naar uw vervoerder stuurt, hangt af van uw postbedrijf, omdat elk postbedrijf zendingen op een andere manier aan uw catalogus koppelt. Ga naar alle postbedrijven en selecteer uw postbedrijf. Op die pagina ziet u hoe het koppelen voor dat postbedrijf werkt en wat u precies moet versturen.
Het is niet verplicht om de
customsDescriptionvan het artikel gelijk te stellen aan de tekst die u naar uw vervoerder stuurt, maar het maakt beide kanten direct vergelijkbaar wanneer een regel niet overeenkomt en u moet uitzoeken waarom.Koppelen mislukt vaak wanneer:
Catalogusartikelen bijwerken
catalogItemUpdategebruikt hetzelfde invoertype als create. Verstuur alleen de velden die u wilt wijzigen.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Uw artikelen teruglezen
De
catalogItem-query accepteertid,productIdofsku. Gebruik deze om te controleren welke gegevens Zonos voor een product heeft.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Catalogusartikelen verwijderen
catalogItemDeleteaccepteert Zonos-catalogusartikel-ID's, niet uw SKU's of product-ID's. Zoek het ID eerst op met decatalogItem-query.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Gerelateerd
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Was deze pagina nuttig?