Terug naar boven

Storesquare B2B API

Met deze API kunt u producten en voorraadbeheer vanop afstand besturen.

De API is toegankelijk via HTTP REST, waarbij de parameter en antwoorden in JSON-formaat doorgestuurd worden. Er is ook ondersteuning voor foutmeldingen indien iets niet volledig correct aangegeven is.

De URLs van de API zijn Engelstalig, alsook de namen en parameters, om uniform bruikbaar te zijn.

De basis-URL is: https://storesquare.be/ (dus: https, zonder www, om onnodige redirects te vermijden).

Er zijn drie grote bronnen in de API:

  • ophalen van onze categorieën en merken

  • aanmaken/bijwerken/verwijderen van producten

  • verwerken van bestellingen

Authenticatie

U kunt deze API gebruiken mits u over de juiste API key beschikt. Deze kunt u in uw profielpagina vinden.

Deze key moet u bij elke request meegeven, anders krijgt u een foutmelding (niet geauthenticeerd).

Bij GET requests voegt u deze toe aan de url, bvb /api/v1/categories?apikey=123abc456def789ghi. Bij POST requests voegt u deze toe aan de body parameters, bvb {"apikey":"123abc456def789ghi", ...}.

Foutmeldingen

In het geval een foute actie genomen werd, kunnen foutmeldingen teruggegeven worden in plaats van data. Deze volgen een standaard patroon:

{
    "error": {
        "code": 1,
        "message": "Product niet gevonden!",
        "http_code": 404
    }
}

De structuur bevat een interne code, een leesbare message, en de HTTP status code.

De gekende interne codes worden in de tabel hieronder uitgelegd.

Code HTTP Code Uitleg (voorbeeld)
1 404 Item niet gevonden, misschien werd een verkeerde ID/code ingegeven, of is het item vroeger reeds verwijderd.
2 422 Validatie gefaald.
3 403 Als de bestelling reeds verwerkt is, en u probeert dit nogmaals te doen.
4 413 U wilt te veel producten in bulk updaten.
5 422 U wil een lijstattribuut koppelen aan een product, maar de meegegeven optie is niet (meer) geldig. Gelieve de lijst met mogelijke waarden opnieuw te downloaden via de relevante API call.

Categorieën

Bronnen gerelateerd aan categorieën. Elk product in Storesquare is gekoppeld aan 1 categorie, op het onderste niveau.

Via de API kunnen geen categorieën aangemaakt worden; dit kan enkel door Storesquare gebeuren. U kunt een overzicht ophalen van de huidige set categorieën via deze bron.

Categorieën

Alle categorieën ophalen

Alle categorieën ophalen
GET/categories{?apikey,flat}

Voorbeeld URI

GET https://storesquare.be/api/v1/categories?apikey=123abc456def789ghi&flat=true
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

flat
boolean (optioneel) Standaard: false Voorbeeld: true

Of de lijst plat of hiërarchisch teruggegeven moet worden (bij true wordt de property subcategories niet teruggegeven bij de objecten)

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 123,
      "slug": "boeken",
      "name_nl": "Boeken",
      "subcategories": [
        {
          "id": 229,
          "slug": "nederlandstalige",
          "name_nl": "Nederlandstalige Boeken",
          "subcategories": []
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "api/v1/categories"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Product-eigenschappen

Producten in Storesquare hebben attributen die u kunt instellen via de API. De attributen worden door Storesquare zelf aangeboden. U kunt de lijst van attributen bij een categorie ophalen.

Attributen zijn ofwel van het type string of het type list.

Alle attributen ophalen

Alle attributen ophalen
GET/categories/attributes{?apikey}

Alle attributen ophalen.

Voorbeeld URI

GET https://storesquare.be/api/v1/categories/attributes?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 21,
      "type": "string",
      "name": "Aantal pagina's",
      "category_id": 4,
      "category_slug": "boeken"
    },
    {
      "id": 22,
      "type": "list",
      "name": "Kaftkleur",
      "list_options": [
        {
          "id": 127,
          "value": "zwart"
        }
      ],
      "category_id": 4,
      "category_slug": "boeken"
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/categories/attributes"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Attributen van een categorie

Ophalen
GET/categories/{slug}/attributes{?apikey}

Van een specifieke categorie de attributen ophalen.

Voorbeeld URI

GET https://storesquare.be/api/v1/categories/category_slug/attributes?apikey=123abc456def789ghi
URI Parameters
VerbergToon
slug
string (verplicht) Voorbeeld: category_slug

Slug van de categorie

apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 21,
      "type": "string",
      "name": "Aantal pagina's",
      "category_id": 4,
      "category_slug": "boeken"
    },
    {
      "id": 22,
      "type": "list",
      "name": "Kaftkleur",
      "list_options": [
        {
          "id": 127,
          "value": "zwart"
        }
      ],
      "category_id": 4,
      "category_slug": "boeken"
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/categories/nederlandstalige"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Leveringstermijnen

Indien u wenst, kunt u per product in uw winkel een specifieke leveringstermijn instellen. De mogelijke termijnen worden door Storesquare zelf bepaald. U kunt de lijst van mogelijke leveringstermijnen ophalen, om deze dan mee te geven aan de product-API-oproepen.

Alle leveringstermijnen ophalen

Alle leveringstermijnen ophalen
GET/deliverytimes{?apikey}

Alle leveringstermijnen ophalen.

Voorbeeld URI

GET https://storesquare.be/api/v1/deliverytimes?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 21,
      "min": 1,
      "max": 5
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/deliverytimes"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Merken

Bronnen gerelateerd aan merken. Storesquare gebruikt het concept van merken om productfiltering mogelijk te maken voor de eindklant.

Via de API kunnen geen merken aangemaakt worden; dit kan enkel door Storesquare gebeuren. U kunt een overzicht ophalen van de reeds gekende merken via deze bron en gebruiken in de Product route.

Merken

Alle merken ophalen
GET/brands{?apikey}

U kunt een lijst ophalen van alle merken reeds gekend in Storesquare.

Voorbeeld URI

GET https://storesquare.be/api/v1/brands?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 12,
      "slug": "my_brandname",
      "name": "My brandname"
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "api/v1/brands"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Een merk ophalen
GET/brands/{brand}{?apikey}

U kunt informatie over een specifiek merk ophalen.

Voorbeeld URI

GET https://storesquare.be/api/v1/brands/My brandname?apikey=123abc456def789ghi
URI Parameters
VerbergToon
brand
string (verplicht) Voorbeeld: My brandname

De merknaam

apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": 12,
    "slug": "my_brandname",
    "name": "My brandname"
  },
  "links": [
    {
      "rel": "self",
      "uri": "api/v1/brands/My%20brandname"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unieke identificatie"
        },
        "slug": {
          "type": "string",
          "description": "Unieke slug"
        },
        "name": {
          "type": "string",
          "description": "De merknaam"
        }
      },
      "required": [
        "id",
        "slug",
        "name"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}
Response  404
VerbergToon

Als het merk niet gevonden is.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "1",
    "message": "Item niet gevonden, misschien werd een verkeerde ID/code ingegeven, of is het item vroeger reeds verwijderd.",
    "http_code": "404"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string"
        }
      }
    }
  }
}

Een nieuw merk toevoegen
POST/brands

U kunt een nieuw merk toevoegen aan Storesquare. Dit merk zal automatisch aan uw winkel gekoppeld worden.

Voorbeeld URI

POST https://storesquare.be/api/v1/brands
Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "name": "My brandname"
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
namestringjaDe merknaam
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "name": {
      "type": "string",
      "description": "De merknaam"
    }
  },
  "required": [
    "apikey",
    "name"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": 12,
    "slug": "my_brandname",
    "name": "My brandname"
  },
  "links": [
    {
      "rel": "self",
      "uri": "api/v1/brands"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unieke identificatie"
        },
        "slug": {
          "type": "string",
          "description": "Unieke slug"
        },
        "name": {
          "type": "string",
          "description": "De merknaam"
        }
      },
      "required": [
        "id",
        "slug",
        "name"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}
Response  422
VerbergToon
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "2",
    "message": "Validatie gefaald",
    "http_code": "422"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string"
        }
      }
    }
  }
}

Winkels

Bronnen gerelateerd aan uw winkel.

Winkeldetails ophalen

Winkeldetails ophalen
GET/company/detail{?apikey}

Haal de details van uw winkel op zoals gekend in Storesquare

Voorbeeld URI

GET https://storesquare.be/api/v1/company/detail?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": 21,
    "name": "WinkelX",
    "slug": "winkelx"
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/company/detail"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unieke identificatie"
        },
        "name": {
          "type": "string",
          "description": "Naam van uw winkel"
        },
        "slug": {
          "type": "string",
          "description": "Slug (url-attribuut) van uw winkel"
        }
      },
      "required": [
        "id",
        "name",
        "slug"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Verkooppunten ophalen

Verkooppunten ophalen
GET/company/points{?apikey}

Haal de details van de verkooppunten van uw winkel op zoals gekend in Storesquare

Voorbeeld URI

GET https://storesquare.be/api/v1/company/points?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 21,
      "name": "WinkelX",
      "slug": "winkelx"
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/company/points"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Categorieën ophalen

Categorieën ophalen
GET/company/categories{?apikey,points}

Haal de lijst van categorieën waar uw winkel aan gekoppeld is op. Haalt eventueel deze lijst ook op voor uw verkooppunten (geef points=true mee).

Voorbeeld URI

GET https://storesquare.be/api/v1/company/categories?apikey=123abc456def789ghi&points=true
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

points
boolean (optioneel) Standaard: false Voorbeeld: true

Of ook de categorieën van de verkooppunten gewenst zijn

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "categories": [
      {
        "id": 123,
        "slug": "boeken",
        "name_nl": "Boeken"
      }
    ],
    "points": [
      {
        "id": 21,
        "name": "WinkelX",
        "slug": "winkelx",
        "categories": [
          {
            "id": 123,
            "slug": "boeken",
            "name_nl": "Boeken"
          }
        ]
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/company/points"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "categories": {
          "type": "array"
        },
        "points": {
          "type": "array"
        }
      },
      "required": [
        "categories"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Producten

Bronnen gerelateerd aan producten.

Producten

Bij deze route kunt u aangeven hoeveel stock (voorraad) van dit product aanwezig is in uw systeem, alsook foto’s uploaden. Zo kunt u alles aanleveren via de API in plaats van de web-interface back-end.

Storesquare biedt bij producten ook varianten aan. Dit zijn veranderingen in eigenschappen van een product, maar die niet een apart product zijn. Voorbeelden zijn maat en kleur. Om deze in te geven, werken we via de notie van “parent” (ouder-product). Een parent product bevat ook eigenschappen, die overschreven/aangevuld kunnen worden door de kind-producten (varianten).

Een nieuw product toevoegen
POST/products

U kunt een nieuw product aanmaken in uw winkel via deze actie. Als invoer verwachten we een JSON object met alle parameters.

In het geval u een variant aanmaakt, zijn niet alle velden verplicht, omdat deze automatisch overgenomen worden van het ouder-product.

Foto’s van producten met varianten moeten allemaal aan het hoofdproduct gekoppeld worden. Foto’s op variant-niveau worden genegeerd! De bestanden moeten ook via HTTP(s) bereikbaar zijn voor de PHP functie file_get_contents.

Voorbeeld URI

POST https://storesquare.be/api/v1/products
Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "sku": "mijn_code_101",
  "name": "naam van uw product",
  "model": "Model",
  "description": "beschrijving van uw product",
  "stock": 4,
  "category": 123,
  "brand": 12,
  "price": 49.99,
  "promotion": 10,
  "attributes": {
    "21": "20 cm",
    "22": 127
  },
  "parent": "mijn_code_100",
  "ean": "1234567890",
  "images": [
    "http://www.example.com/productfotos/foto_101_1.jpg",
    "http://www.example.com/productfotos/foto_101_2.jpg"
  ],
  "active": true
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
skustringjaDe code/ID/EAN van het product in uw database (niet de onze), zodat u later het product nog kunt updaten. Deze code **moet** uniek zijn, anders wordt het eerder gemaakte product overschreven.
namestringjaDe naam van uw product (niet verplicht bij varianten)
modelstringHet model van uw product (niet verplicht bij varianten)
descriptionstringEen beschrijving van uw product (niet verplicht bij varianten)
stocknumberUw voorraad van dit product
categorynumberjaDe categorie-ID vanuit onze database (zie de Categorieën route)
brandnumberjaDe merk-ID van onze database (zie de Merken route)
pricenumberDe prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting)
promotionnumberEen procentuele korting die u op het product wil plaatsen (getal tussen 0 en 100)
attributesobjectExtra eigenschappen van het product. Deze kunt u ophalen via de Categorieën route. Attributen van type *string* kunt u gewoon een waarde geven, die van type *list* moet u bij ID benoemen.
parentstringIndien dit product een variant betreft van een eerder ingevoerd product, dan kunt u hier de sku (uw code/ID) van het hoofdproduct meegeven (dit moet wel reeds gekend zijn bij ons!)
eanstringDe EAN (barcode) van het product
gtinstringDe GTIN van het product
isbnstringDe ISBN van het product
mpnstringDe MPN van het product
deliverytimenumberDe leveringstermijn-ID vanuit onze database (zie de Leveringstermijnen route)
imagesarrayURLs naar foto's van het product, die door ons gedownload zullen worden in de achtergrond (als u een foto update op uw server, moet u ook een nieuwe bestandsnaam geven, want daarop controleren wij of we de download uitvoeren)
activebooleanOf het product direct actief staat op de consumentenpagina
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "sku": {
      "type": "string",
      "description": "De code/ID/EAN van het product in uw database (niet de onze), zodat u later het product nog kunt updaten. Deze code **moet** uniek zijn, anders wordt het eerder gemaakte product overschreven."
    },
    "name": {
      "type": "string",
      "description": "De naam van uw product (niet verplicht bij varianten)"
    },
    "model": {
      "type": "string",
      "description": "Het model van uw product (niet verplicht bij varianten)"
    },
    "description": {
      "type": "string",
      "description": "Een beschrijving van uw product (niet verplicht bij varianten)"
    },
    "stock": {
      "type": "number",
      "description": "Uw voorraad van dit product"
    },
    "category": {
      "type": "number",
      "description": "De categorie-ID vanuit onze database (zie de Categorieën route)"
    },
    "brand": {
      "type": "number",
      "description": "De merk-ID van onze database (zie de Merken route)"
    },
    "price": {
      "type": "number",
      "description": "De prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting)"
    },
    "promotion": {
      "type": "number",
      "description": "Een procentuele korting die u op het product wil plaatsen (getal tussen 0 en 100)"
    },
    "attributes": {
      "type": "object",
      "properties": {},
      "description": "Extra eigenschappen van het product. Deze kunt u ophalen via de Categorieën route. Attributen van type *string* kunt u gewoon een waarde geven, die van type *list* moet u bij ID benoemen."
    },
    "parent": {
      "type": "string",
      "description": "Indien dit product een variant betreft van een eerder ingevoerd product, dan kunt u hier de sku (uw code/ID) van het hoofdproduct meegeven (dit moet wel reeds gekend zijn bij ons!)"
    },
    "ean": {
      "type": "string",
      "description": "De EAN (barcode) van het product"
    },
    "gtin": {
      "type": "string",
      "description": "De GTIN van het product"
    },
    "isbn": {
      "type": "string",
      "description": "De ISBN van het product"
    },
    "mpn": {
      "type": "string",
      "description": "De MPN van het product"
    },
    "deliverytime": {
      "type": "number",
      "description": "De leveringstermijn-ID vanuit onze database (zie de Leveringstermijnen route)"
    },
    "images": {
      "type": "array",
      "description": "URLs naar foto's van het product, die door ons gedownload zullen worden in de achtergrond (als u een foto update op uw server, moet u ook een nieuwe bestandsnaam geven, want daarop controleren wij of we de download uitvoeren)"
    },
    "active": {
      "type": "boolean",
      "description": "Of het product direct actief staat op de consumentenpagina"
    }
  },
  "required": [
    "apikey",
    "sku",
    "name",
    "category",
    "brand"
  ]
}
Response  201
VerbergToon
Headers
Content-Type: application/json
Location: http://www.storesquare.be/shop/mijn-winkel/product/naam-van-uw-product
Body
{
  "data": {
    "id": "1",
    "slug": "naam-van-uw-product"
  },
  "links": [
    {
      "rel": "self",
      "uri": "/shop/mijn-winkel/product/naam-van-uw-product"
    },
    {
      "rel": "update",
      "uri": "/api/v1/products/mijn_code_101"
    }
  ]
}
Response  422
VerbergToon
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "5",
    "message": "An attribute list value you provided is not valid: X does not have option Y",
    "http_code": "422"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string"
        }
      }
    }
  }
}

Bestaande producten

Een bestaand product bijwerken
POST/products/{sku}

U kunt een bestaand product bijwerken via deze route. De sku moet via de URL meegegeven worden.

U kunt instellen dat bepaalde velden genegeerd moeten worden bij een update. Stel dat u een categorie meegeeft bij een update die u niet wilt aanpassen naar die van Storesquare, dan kunt u dit aangeven in de ignore_on_update parameter. U geeft dan gewoon in die array de string 'category' mee, of 'brand', of welke dan ook relevant is (behalve 'parent').

Voorbeeld URI

POST https://storesquare.be/api/v1/products/mijn_code_101
URI Parameters
VerbergToon
sku
string (verplicht) Voorbeeld: mijn_code_101

De code/ID/EAN van het product in uw database (niet de onze), zoals meegegeven bij het maken van het product. Opgelet, deze moet URL encoded zijn, en dus bepaalde tekens niet bevatten (zoals #, &, ? en /)!

Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "name": "naam van uw product",
  "model": "Model",
  "description": "beschrijving van uw product",
  "stock": 4,
  "category": 123,
  "brand": 12,
  "price": 49.99,
  "promotion": 10,
  "attributes": {
    "21": "20 cm",
    "22": 127
  },
  "parent": "mijn_code_100",
  "ean": "1234567890",
  "images": [
    "http://www.example.com/productfotos/foto_101_1.jpg",
    "http://www.example.com/productfotos/foto_101_2.jpg"
  ],
  "active": true,
  "ignore_on_update": [
    "brand"
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
namestringjaDe naam van uw product (niet verplicht bij varianten)
modelstringHet model van uw product (niet verplicht bij varianten)
descriptionstringEen beschrijving van uw product (niet verplicht bij varianten)
stocknumberUw voorraad van dit product
categorynumberjaDe categorie-ID vanuit onze database (zie de Categorieën route)
brandnumberjaDe merk-ID van onze database (zie de Merken route)
pricenumberDe prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting)
promotionnumberEen procentuele korting die u op het product wil plaatsen (getal tussen 0 en 100)
attributesobjectExtra eigenschappen van het product. Deze kunt u ophalen via de Categorieën route. Attributen van type *string* kunt u gewoon een waarde geven, die van type *list* moet u bij ID benoemen.
parentstringIndien dit product een variant betreft van een eerder ingevoerd product, dan kunt u hier de sku (uw code/ID) van het hoofdproduct meegeven (dit moet wel reeds gekend zijn bij ons!)
eanstringDe EAN (barcode) van het product
gtinstringDe GTIN van het product
isbnstringDe ISBN van het product
mpnstringDe MPN van het product
deliverytimenumberDe leveringstermijn-ID vanuit onze database (zie de Leveringstermijnen route)
imagesarrayURLs naar foto's van het product, die door ons gedownload zullen worden in de achtergrond (als u een foto update op uw server, moet u ook een nieuwe bestandsnaam geven, want daarop controleren wij of we de download uitvoeren)
activebooleanOf het product direct actief staat op de consumentenpagina
ignore_on_updatearrayAttributen om te negeren bij het updaten van een product
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "name": {
      "type": "string",
      "description": "De naam van uw product (niet verplicht bij varianten)"
    },
    "model": {
      "type": "string",
      "description": "Het model van uw product (niet verplicht bij varianten)"
    },
    "description": {
      "type": "string",
      "description": "Een beschrijving van uw product (niet verplicht bij varianten)"
    },
    "stock": {
      "type": "number",
      "description": "Uw voorraad van dit product"
    },
    "category": {
      "type": "number",
      "description": "De categorie-ID vanuit onze database (zie de Categorieën route)"
    },
    "brand": {
      "type": "number",
      "description": "De merk-ID van onze database (zie de Merken route)"
    },
    "price": {
      "type": "number",
      "description": "De prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting)"
    },
    "promotion": {
      "type": "number",
      "description": "Een procentuele korting die u op het product wil plaatsen (getal tussen 0 en 100)"
    },
    "attributes": {
      "type": "object",
      "properties": {},
      "description": "Extra eigenschappen van het product. Deze kunt u ophalen via de Categorieën route. Attributen van type *string* kunt u gewoon een waarde geven, die van type *list* moet u bij ID benoemen."
    },
    "parent": {
      "type": "string",
      "description": "Indien dit product een variant betreft van een eerder ingevoerd product, dan kunt u hier de sku (uw code/ID) van het hoofdproduct meegeven (dit moet wel reeds gekend zijn bij ons!)"
    },
    "ean": {
      "type": "string",
      "description": "De EAN (barcode) van het product"
    },
    "gtin": {
      "type": "string",
      "description": "De GTIN van het product"
    },
    "isbn": {
      "type": "string",
      "description": "De ISBN van het product"
    },
    "mpn": {
      "type": "string",
      "description": "De MPN van het product"
    },
    "deliverytime": {
      "type": "number",
      "description": "De leveringstermijn-ID vanuit onze database (zie de Leveringstermijnen route)"
    },
    "images": {
      "type": "array",
      "description": "URLs naar foto's van het product, die door ons gedownload zullen worden in de achtergrond (als u een foto update op uw server, moet u ook een nieuwe bestandsnaam geven, want daarop controleren wij of we de download uitvoeren)"
    },
    "active": {
      "type": "boolean",
      "description": "Of het product direct actief staat op de consumentenpagina"
    },
    "ignore_on_update": {
      "type": "array",
      "description": "Attributen om te negeren bij het updaten van een product"
    }
  },
  "required": [
    "apikey",
    "name",
    "category",
    "brand"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Location: http://www.storesquare.be/shop/mijn-winkel/product/naam-van-uw-product
Body
{
  "data": {
    "id": "1",
    "slug": "naam-van-uw-product"
  },
  "links": [
    {
      "rel": "self",
      "uri": "/shop/mijn-winkel/product/naam-van-uw-product"
    },
    {
      "rel": "update",
      "uri": "/api/v1/products/mijn_code_101"
    }
  ]
}
Response  422
VerbergToon
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "5",
    "message": "An attribute list value you provided is not valid: X does not have option Y",
    "http_code": "422"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string"
        }
      }
    }
  }
}

Een bestaand product verwijderen
DELETE/products/{sku}{?apikey}

U kunt een bestaand product verwijderen, waardoor het niet meer op de site beschikbaar is. Dit kan niet ongedaan gemaakt worden.

Als u het product enkel offline wil halen, om later nog weer up te daten, kunt u de update-API gebruiken met het active veld op false.

Voorbeeld URI

DELETE https://storesquare.be/api/v1/products/mijn_code_101?apikey=123abc456def789ghi
URI Parameters
VerbergToon
sku
string (verplicht) Voorbeeld: mijn_code_101

De code/ID van het product in uw database (niet de onze), zoals meegegeven bij het maken van het product.

apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
"Deleted"

Alle producten zonder stock zetten

Alle producten zonder stock zetten
POST/products/all/resetstock

Bij deze route kunt u bij elk product van uw winkel de stock (voorraad) op 0 zetten. Hierdoor worden de producten niet meer getoond in de frontend.

Voorbeeld URI

POST https://storesquare.be/api/v1/products/all/resetstock
Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi"
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    }
  },
  "required": [
    "apikey"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "success": true
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/products/all/resetstock"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Bulk updates aan producten

Voorraad/prijs/promo/levertijden update
POST/products/all/update

U kunt een set van producten in bulk updaten met 1 oproep. Dit bespaart op individuele oproepen per product.

U kunt tot maximum 100 producten per oproep aanpassen.

Voorbeeld URI

POST https://storesquare.be/api/v1/products/all/update
Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "data": [
    {
      "sku": "mijn_code_101",
      "stock": 1,
      "price": 1,
      "promotion": 1,
      "deliverytime": 1
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
dataarrayja
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "apikey",
    "data"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "success": true,
    "individual": [
      {
        "sku": "mijn_code_101",
        "success": true
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/products/all/update"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Of alle producten verwerkt konden worden"
        },
        "individual": {
          "type": "array",
          "description": "Een lijst van producten en hun verwerkingsstatus"
        }
      },
      "required": [
        "success",
        "individual"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}
Response  413
VerbergToon

Als u meer dan het maximum aantal producten per oproep probeert te laten verwerken

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "4",
    "message": "U wilt te veel producten in bulk updaten.",
    "http_code": "413"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string",
          "description": "-->\n"
        }
      }
    }
  }
}

Producten en verkooppunten

U kunt aangeven in welke verkooppunten welke producten verkocht worden.

Deze calls zijn niet belangrijk als u niet met verkooppunten werkt.

Product toewijzen aan verkooppunt
POST/products/{sku}/points/{slug}

U kunt instellen dat een bepaald verkooppunt een specifiek product verkoopt.

Voorbeeld URI

POST https://storesquare.be/api/v1/products/mijn_code_101/points/winkelx
URI Parameters
VerbergToon
sku
string (verplicht) Voorbeeld: mijn_code_101

De code/ID/EAN van het product in uw database (niet de onze), zoals meegegeven bij het maken van het product.

slug
string (verplicht) Voorbeeld: winkelx

Slug (url-attribuut) van het verkooppunt

Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "stock": 5,
  "price": 12.5
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
stocknumberUw voorraad van dit product in dit specifieke verkooppunt (deze parameter niet meegeven als de voorraad overgeërfd moet worden van de hoofdwinkel)
pricenumberDe prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting) in dit specifieke verkooppunt (deze parameter niet meegeven als de voorraad overgeërfd moet worden van de hoofdwinkel)
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "stock": {
      "type": "number",
      "description": "Uw voorraad van dit product in dit specifieke verkooppunt (deze parameter niet meegeven als de voorraad overgeërfd moet worden van de hoofdwinkel)"
    },
    "price": {
      "type": "number",
      "description": "De prijs van het product die eindklanten betalen (dus met BTW, maar zonder eventuele korting) in dit specifieke verkooppunt (deze parameter niet meegeven als de voorraad overgeërfd moet worden van de hoofdwinkel)"
    }
  },
  "required": [
    "apikey"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "success": true
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/products/all/resetstock"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Product verwijderen van verkooppunt
DELETE/products/{sku}/points/{slug}

U kunt instellen dat een bepaald verkooppunt een specifiek product niet langer verkoopt.

Voorbeeld URI

DELETE https://storesquare.be/api/v1/products/mijn_code_101/points/winkelx
URI Parameters
VerbergToon
sku
string (verplicht) Voorbeeld: mijn_code_101

De code/ID/EAN van het product in uw database (niet de onze), zoals meegegeven bij het maken van het product.

slug
string (verplicht) Voorbeeld: winkelx

Slug (url-attribuut) van het verkooppunt

Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi"
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    }
  },
  "required": [
    "apikey"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
"Deleted"

Bestellingen

Bronnen gerelateerd aan bestellingen.

Bestellingen

Bestellingen bevatten de items die een consument gekocht heeft in uw winkel.

Ophalen van openstaande bestellingen
GET/shipments{?apikey}

U kunt een lijst van alle openstaande bestellingen voor uw winkel ophalen. Dit zijn bestellingen waar u nog geen feedback op geleverd hebt.

Ook informatie over reeds verwijderde producten zal worden teruggegeven.

Voorbeeld URI

GET https://storesquare.be/api/v1/shipments?apikey=123abc456def789ghi
URI Parameters
VerbergToon
apikey
string (verplicht) Voorbeeld: 123abc456def789ghi

Authenticatiesleutel

Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "shipment_id": 12,
      "date": "2017-12-25 12:15:16",
      "customer_info": {
        "billing": {
          "name": "Storesquare nv",
          "phone": "0800/14.023",
          "email": "support@storesquare.be",
          "vat": "BE0554.814.066",
          "company": "Storesquare nv",
          "street": "Meiboomlaan",
          "housenr": "33",
          "box": "Hello, world!",
          "postal_code": "8800",
          "city": "Roeselare"
        },
        "shipping": {
          "name": "Filip Leopold Lodewijk Maria",
          "phone": "02/000001",
          "email": "support@storesquare.be",
          "vat": "BE00",
          "company": "Koninkrijk",
          "street": "Brederodestraat",
          "housenr": "16",
          "box": "Hello, world!",
          "postal_code": "1000",
          "city": "Brussel"
        }
      },
      "items": [
        {
          "id": 1,
          "sku": "mijn_code_101",
          "name": "naam",
          "quantity": 2,
          "price": 123.45
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "uri": "api/v1/shipments"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataarrayjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}

Bevestigen van bestellingen
POST/shipments

Bevestig welke producten u van een bestelling wilt aanvaarden of weigeren. Alle producten van een bestelling waar geen notie van gemaakt wordt in deze request, worden als geweigerd bestempeld. Dit kan niet meer gewijzigd worden nadien!

Voorbeeld URI

POST https://storesquare.be/api/v1/shipments
Request
VerbergToon
Headers
Content-Type: application/json
Body
{
  "apikey": "123abc456def789ghi",
  "shipment_id": 12,
  "items": [
    {
      "id": 2,
      "quantity": 1,
      "status": "accepted"
    }
  ],
  "tracking_link": "http://bpost.be/barcode"
}
AttribuutnaamTypeVerplichtBeschrijving
apikeystringjaAuthenticatiesleutel
shipment_idnumberjaUnieke identificatie van de bestelling
itemsarrayjaDe items in de bestelling
tracking_linkstringDe tracking link van het pakket als u het zelf verstuurt
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "apikey": {
      "type": "string",
      "description": "Authenticatiesleutel"
    },
    "shipment_id": {
      "type": "number",
      "description": "Unieke identificatie van de bestelling"
    },
    "items": {
      "type": "array",
      "description": "De items in de bestelling"
    },
    "tracking_link": {
      "type": "string",
      "description": "De tracking link van het pakket als u het zelf verstuurt"
    }
  },
  "required": [
    "apikey",
    "shipment_id",
    "items"
  ]
}
Response  200
VerbergToon
Headers
Content-Type: application/json
Body
{
  "data": {
    "success": true,
    "individual": [
      {
        "id": 2,
        "status": "accepted",
        "price": 61.725,
        "quantity": 1,
        "commission": 6.78,
        "vat": 10.01
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "uri": "/api/v1/shipments"
    }
  ]
}
AttribuutnaamTypeVerplichtBeschrijving
dataobjectjaDe data
linksarrayjaLinks
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Of alle updates verwerkt konden worden"
        },
        "individual": {
          "type": "array",
          "description": "Een lijst van de updates en hun facturatiegegevens"
        }
      },
      "required": [
        "success",
        "individual"
      ],
      "description": "De data"
    },
    "links": {
      "type": "array",
      "description": "Links"
    }
  },
  "required": [
    "data",
    "links"
  ]
}
Response  403
VerbergToon

Als de bestelling reeds verwerkt is, en u probeert dit nogmaals te doen.

Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "3",
    "message": "Bestelling is reeds verwerkt, aanpassingen zijn niet meer mogelijk.",
    "http_code": "403"
  }
}
AttribuutnaamTypeVerplichtBeschrijving
errorobject
VerbergToon
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "http_code": {
          "type": "string"
        }
      }
    }
  }
}

Gegenereerd door aglio op 15 Apr 2019