Integratie: Een product met prijs aanmaken via de API

In dit artikel lees je hoe je met de openbare API van Voluit Suite een product aanmaakt. Je ontdekt ook welke producttypen er zijn en hoe je die kunt gebruiken.

Producten

Producten zijn een van de belangrijkste onderdelen van Voluit Suite. Je kunt ze via verschillende verkoopkanalen aanbieden, zoals online shops, facturen en offertes.

Producttypen

In Voluit Suite zijn er twee hoofdtypen producten:

  • Producten met een prijs
  • Producten met varianten

Producten met een prijs

Dit zijn eenvoudige producten zonder varianten. Gebruik dit type als je product geen varianten heeft of maar één variantcategorie nodig heeft. Denk bijvoorbeeld aan een poster die in verschillende formaten verkrijgbaar is.

Producten met varianten

Dit type gebruik je voor producten met meerdere variaties. Een T-shirt kan bijvoorbeeld in verschillende kleuren en maten verkrijgbaar zijn.

Een product maken met de openbare API

Autorisatie

Je hebt een toegangstoken nodig om gegevens in Voluit Suite via de openbare API aan te maken, op te vragen, bij te werken of te verwijderen. In de documentatie over autorisatie lees je hoe je dit regelt.

Een product aanmaken

Voor het aanmaken van een product gebruik je deze openbare API's:

Volg de stappen in deze volgorde.

Een product aanmaken

Maak eerst een product aan met de API om een product aan te maken. Dit zijn de belangrijkste eigenschappen:

  • name : de naam van het product
  • locationId : de ID van het account waarvoor je het product aanmaakt
  • description : een korte productbeschrijving die je in verkoopkanalen kunt tonen
  • productType : geef hier bijvoorbeeld DIGITAL  op
  • image : de uitgelichte afbeelding die standaard aan klanten wordt getoond
  • availableInStore : bepaalt of het product beschikbaar is in online shops
  • medias : een lijst met mediaobjecten
    • id : unieke ID van het mediaobject
    • title : titel van het mediaobject
    • url : bron-URL van het mediaobject
    • type : op dit moment wordt alleen image  ondersteund
    • isFeatured : stel in op true  als je de afbeelding aan klanten wilt tonen
  • variants : alleen nodig als je een product met varianten aanmaakt
    • id : unieke ID van de variant
    • name : naam van de variant
    • options : lijst met variantopties
      • id : unieke ID van de optie. Je hebt deze ID nodig om een prijs aan te maken.
      • name : naam van de optie

Voorbeeld: product met een prijs

{
"name": "High Speed Memory Drive",
"description": "A high speed memory drive with latest safety features and breath taking design",
"locationId": "<account_ID>",
"availableInStore": true,
"productType": "PHYSICAL",
"image": "https://via.placeholder.com/150",
"medias": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "High Speed Memory Drive",
"url": "https://via.placeholder.com/150",
"type": "image",
"isFeatured": true
}
]
}

Voorbeeld: product met varianten

{
"name": "T-shirt",
"description": "Latest t-shirt with latest design and quality",
"locationId": "<account_ID>",
"availableInStore": true,
"productType": "PHYSICAL",
"image": "https://via.placeholder.com/150",
"medias": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "T-shirt",
"url": "https://via.placeholder.com/150",
"type": "image",
"isFeatured": true
}
],
"variants": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Color",
"options": [
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Red"
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Blue"
},
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"name": "Green"
}
]
},
{
"id": "550e8400-e29b-41d4-a716-446655440111",
"name": "Size",
"options": [
{
"id": "550e8400-e29b-41d4-a716-446655440112",
"name": "Small"
},
{
"id": "550e8400-e29b-41d4-a716-446655440113",
"name": "Medium"
},
{
"id": "550e8400-e29b-41d4-a716-446655440114",
"name": "Large"
}
]
}
]
}

Bewaar bij een product met varianten de ID's van de opties. Je hebt ze nodig om prijzen aan te maken.

Na het aanmaken van een product bevat de API-reactie de eigenschap _id . Dit is de ID van het aangemaakte product. Gebruik deze ID om een prijs voor het product aan te maken.

Een prijs voor een product aanmaken

Maak een prijs aan met de API om een prijs voor een product aan te maken. Dit zijn de belangrijkste eigenschappen:

  • product : de ID van het product waarvoor je de prijs aanmaakt
  • locationId : de ID van het account
  • name : de naam van de prijs
  • type : het type prijs. De beschikbare waarden zijn one_time  en recurring .
  • currency : de valuta van de prijs
  • amount : het bedrag in de opgegeven valuta
  • description : de beschrijving van de prijs
  • variantOptionIds : verplicht voor producten met varianten
    • Voor de combinatie Rood/Klein gebruik je bijvoorbeeld deze variantOptionIds :
["550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440112"]
  • 550e8400-e29b-41d4-a716-446655440002  hoort bij Rood en 550e8400-e29b-41d4-a716-446655440112  hoort bij Klein.
  • Voor producten met varianten zijn variantOptionIds  nodig om de varianten goed weer te geven. Zonder deze eigenschap worden de combinaties mogelijk niet goed getoond.
  • trackInventory : stel in op true  als je de voorraad wilt bijhouden
  • availableQuantity : de beschikbare hoeveelheid; alleen van toepassing als trackInventory  is ingesteld op true
  • allowOutOfStockPurchases : bepaalt of klanten het product mogen kopen als het niet op voorraad is; alleen van toepassing als trackInventory  is ingesteld op true
  • sku : de SKU van de prijs of variant
  • isDigitalProduct : stel in op true  als het om een digitaal product gaat
  • shippingOptions : verzendgegevens voor fysieke producten, bijvoorbeeld voor verzendintegraties
    • weight : het gewicht
      • value : de waarde van het gewicht
      • unit : de eenheid. Ondersteunde waarden zijn kg , g , lb  en oz .
    • dimensions : de afmetingen van het fysieke product
      • height : de hoogte
      • width : de breedte
      • length : de lengte
      • unit : de eenheid. Ondersteunde waarden zijn cm , in  en m .

Voorbeeld: eenvoudige prijs zonder varianten

{
"product": "66b6021be68f7a98102ba272",
"locationId": "<account_ID>",
"name": "256 GB",
"type": "one_time",
"currency": "EUR",
"amount": 100,
"description": "256 GB of storage",
"sku": "PS-256GB",
"isDigitalProduct": false,
"shippingOptions": {
"weight": {
"value": 100,
"unit": "g"
},
"dimensions": {
"length": 10,
"width": 10,
"height": 10,
"unit": "cm"
}
}
}

Voorbeeld: prijs voor een product met varianten

{
"product": "66b6021be68f7a98102ba272",
"locationId": "<account_ID>",
"name": "Red / Small",
"type": "one_time",
"currency": "EUR",
"amount": 100,
"description": "Red / Small",
"sku": "PS-RED-SMALL",
"isDigitalProduct": false,
"variantOptionIds": ["550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440112"],
"shippingOptions": {
"weight": {
"value": 100,
"unit": "g"
},
"dimensions": {
"length": 10,
"width": 10,
"height": 10,
"unit": "cm"
}
}
}

De ID's van de variantopties zijn nodig om productvarianten goed weer te geven.

Een afbeelding aan een variant koppelen via de openbare API

Deze functie is alleen beschikbaar voor producten met varianten, niet voor producten met een vaste prijs. Nadat je een prijs voor een product hebt aangemaakt, bevat de API-reactie de interne ID van de prijs. Gebruik die ID om de afbeelding aan een specifieke variant te koppelen. Werk het product daarna bij met de volgende payload.

Voorbeeld: media van een product bijwerken met priceIds

In de productpayload bevat elk object in de lijst medias  een eigenschap priceIds . Dit is een lijst met prijs-ID's. Als je hier de juiste prijs-ID aan toevoegt, wordt de afbeelding automatisch aan de bijbehorende variant gekoppeld.

{
"name": "T-shirt",
"description": "Latest t-shirt with latest design and quality",
"locationId": "<account_ID>",
"availableInStore": true,
"productType": "PHYSICAL",
"image": "https://via.placeholder.com/150",
"medias": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "T-shirt",
"url": "https://via.placeholder.com/150",
"type": "image",
"priceIds": ["<created_price_Id>"],
"isFeatured": true
}
],
"variants": [
{"...existing variants data"}
]
}

Op dit moment kun je één afbeelding aan één priceId  koppelen. Als je meerdere priceIds  aan één afbeelding koppelt, kan dat problemen veroorzaken bij het weergeven van producten.

Openbare API's voor producten en e-commerce

De openbare API voor producten van Voluit Suite ondersteunt productbeheer en e-commerce-integraties. Je kunt onder andere API's gebruiken voor bulkupdates van producten, voorraadbeheer, zichtbaarheid in online shops, productcollecties en reviews.

De beschikbare mogelijkheden zijn onder andere:

  • Producten in bulk bijwerken: werk meerdere producten bij met één API-aanvraag.
  • Voorraad beheren: haal voorraadgegevens op en werk voorraadhoeveelheden bij.
  • Zichtbaarheid in online shops beheren: bekijk statistieken over productzichtbaarheid en neem producten op in of sluit ze uit van online shops.
  • Productcollecties beheren: haal collecties op en maak ze aan, werk ze bij of verwijder ze.

  • Productreviews beheren: haal reviews op, werk ze bij of verwijder ze. Je kunt ook aantallen reviews per moderatiestatus opvragen.

    Overzicht van openbare API's voor producten en e-commerce

Met deze API's kunnen ontwikkelaars productgerelateerde gegevens beheren via externe integraties.

Bekijk de documentatie voor de openbare API's van Voluit Suite voor de beschikbare eindpunten, autorisatievereisten, ondersteunde API-versies en voorbeelden van aanvragen.

Samenvatting

Met de API's hierboven kun je een fysiek product met een eenmalige prijs aanmaken, zowel zonder varianten als met varianten. Je kunt ook terugkerende producten aanmaken. Raadpleeg de documentatie van de prijs-API voor meer informatie en voor de eigenschappen die specifiek voor terugkerende producten beschikbaar zijn.

Heeft dit je vraag beantwoord? Bedankt voor de feedback! Er was een probleem bij het versturen van je feedback. Probeer later nog eens.

Gerelateerde artikelen