NL·EN
Contact

API

oneCORE Public API

oneCORE heeft een RESTful API voor een naadloze koppeling tussen oneCORE en externe systemen. We stappen op dit moment over op API Version 2, met een gestructureerder API-ontwerp. API Version 1 blijft beschikbaar, maar we raden aan Version 2 te gebruiken voor de beste prestaties en compatibiliteit op lange termijn.

Swagger

oneCORE heeft interactieve API-documentatie in Swagger, met alle beschikbare endpoints en hun specificaties. Je opent Swagger via shop-URL/api-swagger, bijvoorbeeld https://colengo.com/api-swagger.

Let op: zet om Swagger te gebruiken de functie “EnableSwagger” aan onder Shop features in Settings. Vraag daarna het Client success-team om het ook in de back-end aan te zetten.

Public API-machtigingen

Met Public API-machtigingen beheer je gestructureerd wat API-gebruikers mogen: je staat per groep gebruikers bepaalde acties toe of je blokkeert ze. Beheerders bepalen zo welke groepen API-gebruikers met welke endpoints mogen werken, zodat gevoelige handelingen beschermd blijven. Voordat je met de API aan de slag gaat, heb je een eigen API-gebruiker en de juiste machtigingen nodig. Volg daarvoor de handleiding Public API-machtigingen.

Omgevingsinstellingen

Het Content-Type is application/json.

Gebruik je het HTTP-formaat, stel je code dan zo in:

GET {endpoint} HTTP/1.1
Host: {shop URL}
Content-Type: application/json
Authorization: {PublicApiV2} {access token} (met PublicApi ervoor voor API V1, of PublicApiV2 voor API V2)

Voorbeeld

GET /api/v2/databaseusages HTTP/1.1
Host: https://colengo.com/api/v2/databaseusages
Content-Type: application/json
Authorization: PublicApiV2 {access token}

Gebruik je het cURL-formaat, stel je code dan zo in:

curl --location '{shop URL}{endpoint}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {PublicApiV2} {access token}' (met PublicApi ervoor voor API V1, of PublicApiV2 voor API V2)

Voorbeeld

curl --location 'https://colengo.com/api/v2/databaseusages' \
--header 'Content-Type: application/json' \
--header 'Authorization: PublicApiV2 {access token}'

Gebruik je Postman, stel dan deze variabelen in:

  • host: de shop-URL
  • access_token: het access token voor API Version 1 (met PublicApi ervoor)
  • access_token_v2: het access token voor API Version 2 (met PublicApiV2 ervoor)

Let op: er kan maar één API-versie tegelijk actief zijn.

Authenticatie

Je begint met een Refresh Token.

1. Ga naar “Shop App Tokens” onder het menu API.

2. Klik op “Add token”.

3. Geef het token een naam en kies de Public API User.

Na het opslaan maakt het systeem een Refresh Token aan.

Vraag daarna een Access Token aan met een POST-verzoek naar het endpoint Renew Token (/api/v1/tokens/renewtokens of /api/v2/tokens/renewtokens), met de Refresh Token. Gebruik het Access Token dat je terugkrijgt als waarde van je omgevingsvariabele. Vijf dagen nadat de huidige Refresh Token actief is, geeft het systeem je een nieuwe.

Responscodes

  • 400 Bad Request
  • 401 Unauthorized (Token expired or invalid\incorrect)
  • 403 Forbidden (Not enough permissions)

Naar de volgende of vorige pagina met resultaten

De GET List-endpoints van API Version 2 geven gegevens terug in pagina's. Zo ga je naar de volgende of vorige pagina met resultaten.

1. Stuur eerst een API-verzoek.

2. Je krijgt de response body en een metadata-object terug. Dat object bevat de gegevens om naar de volgende of vorige pagina te gaan:

  • "hasNext" geeft aan of er een volgende pagina is.
  • "hasPrevious" geeft aan of er een vorige pagina is.
  • "next" bevat de extra parameter 'after={value}' voor de volgende pagina.
  • Voor de volgende pagina zet je de parameter 'after={value}' achter de URL van het endpoint.
  • "previous" bevat de extra parameter 'before={value}' voor de vorige pagina.
  • Voor de vorige pagina zet je de parameter 'before={value}' achter de URL van het endpoint.

Notatie van datum en tijd

Alle datums en tijden volgen ISO 8601. Staat er in de request body geen tijdzone bij een datum en tijd, dan slaat het systeem ze op in UTC+0.

Hoofdlettergevoeligheid

URL's zijn niet hoofdlettergevoelig.