API

API om de kracht van CODICI te ontsluiten

Een RESTful API is de standaard manier om computers met elkaar te integreren. Ook CODICI heeft ervoor gekozen om de API te gebruiken om de kracht van onze artificial intelligence aan te bieden. U gebruikt de API om een vraag te stellen waarbij u via parameters aangeeft wat u weet over uw product. Het antwoord van de API, in JSON formaat, kan vervolgens gebruikt worden om direct in uw systemen te plaatsen.

Een antwoord van onze API is een JSON formaat waarbij vijf resultaten worden weergegeven, gesorteerd op confidence score (een inschatting van onze artificial intelligence hoe relevant het antwoord is). Hoe hoger de confidence score, hoe beter het antwoord bij uw vraag past.

API call

Basis

De basis url voor API-calls is https://api.codi.ci/api/search. U authenticeert uzelf met een bearer token met de key die u reeds heeft ontvangen en ook terug kunt vinden in uw portaal

U kunt uw zoekparameters doorgeven in de URL door de "q" -parameter te gebruiken om uw query aan de API door te geven. Een voorbeeld van een verzoek zou er als volgt uit kunnen zien:
https://api.codi.ci/api/search/?q=your_description_hereVervang "your_description_here" door de omschrijving of vraag die u wilt stellen aan de API. Zorg ervoor dat u de benodigde authenticatie toevoegt aan uw verzoek, zoals het bearer token, zoals eerder vermeld.

Bearer token

Als u op de link heeft geklikt, heeft u gemerkt dat u naar een inlogpagina wordt verwezen. Dit komt doordat u zich moet authenticeren met een bearer token tijdens het aanvragen. We hebben echter enkele voorbeelden beschikbaar gesteld in onze GitHub om u te helpen met de integratie. Daarnaast kunt u uw code ook testen tegen onze testomgeving.

Parameters

Met parameters kunt u aangeven waarvoor u een HS code zoekt. Hieronder vindt u een overzicht van alle mogelijke parameters:

Antwoord

Het antwoord van de API wordt gegeven in het zogenaamde JSON formaat. Dit formaat is flexibel van opzet zodanig dat u niet aan uw kant bij elke nieuwe versie uw integratie moet aanpassen. Een voorbeeld van een antwoord (op een fictieve vraag) staat hieronder:

{
  "data": [
    {
      "confidenceScore": 93,
      "hs_code": "5803001000"
    },
    {
      "confidenceScore": 75,
      "hs_code": "6206300000"
    },
    {
      "confidenceScore": 68,
      "hs_code": "6302310000"
    },
    {
      "confidenceScore": 67
      "hs_code": "5304310000"
    },
    {
      "confidenceScore": 62,
      "hs_code": "5200210000"
    }
  ]
}

Als u nog niet bekend bent met het JSON-formaat, is het raadzaam om online meer te leren. JSON (JavaScript Object Notation) is een veelgebruikt gegevensuitwisselingsformaat dat de standaard is geworden voor het representeren van gestructureerde gegevens. De eenvoud, leesbaarheid en brede ondersteuning maken het een essentiële vaardigheid bij het werken met API's en het uitwisselen van gegevens tussen verschillende systemen.

Zoals u kunt zien bestaat het antwoord uit een array die data heet. Deze array bevat meerdere collections. In elke collection zitten twee variabelen. De variabele 'hs_code' bevat de 10 cijfers van de HS-code. In dezelfde collection zit de variable 'confidenceScore' die aangeeft hoe zeker de AI is van het antwoord. De eerste collectie in de array is degene met de hoogste 'confidenceScore' en daarmee ook degene waarvan de AI aangeeft dat die het beste advies is.

Testen

Om u te ondersteunen bij het implementeren van onze API hebben wij een test omgeving voor u beschikbaar. De antwoorden uit deze omgeving geven dezelfde JSON als de productieomgeving maar dan aangevuld met extra velden die u informatie geven over wat er nog niet juist is. U kunt onze test API vinden op https://test-api.codi.ci/api/search. Als u klaar bent met testen haalt u test- weg en bent u klaar voor productie.

U kunt op de link voor de test API klikken en dan krijgt u een antwoord vergelijkbaar met dit:

{
  "data": [
    {
      "confidenceScore": 77,
      "hs_code": "0003001000"
    },
    {
      "confidenceScore": 74,
      "hs_code": "0000210000"
    },
    {
      "confidenceScore": 73,
      "hs_code": "0006300000"
    },
    {
      "confidenceScore": 70
      "hs_code": "0002334500"
    },
    {
      "confidenceScore": 62,
      "hs_code": "0002310000"
    }
  ],
  "messagecode": "1,2",
  "message": "No search query was given. | No bearer token found."
}

Zoals u kunt zien lijkt het antwoord qua format op die van de echte API maar er staan twee extra velden bij; messagecode en message. Het veld messagecode bevat een lijst van foutcodes gescheiden door kommas die u hieronder kunt opzoeken. Het veld message bevat een korte omschrijving van dezelfde foutcodes, gescheiden door het  |  teken. Let wel op, de antwoorden slaan qua inhoud nergens op en ze zullen iedere keer anders zijn omdat dit enkel gebruikt wordt om te testen. Om die reden beginnen de HS-codes in de antwoorden met een 00. Dit hoofdstuk bestaat namelijk niet.

Als u nog niet veel ervaring heeft met het integreren van APIs dan kunnen wij Postman aanraden. U kunt hiermee uitgebreid testen. Postman ondersteunt ook bearer tokens (via de tab Authorization en dan Type: Bearer Token). Verder hebben wij op onze GitHub omgeving voorbeeld code klaar staan in een aantal talen die u kunt gebruiken als start. Mocht u na het lezen van deze documentatie er toch nog niet uitkomen, dan kunt u contact opnemen met onze support afdeling via support@codi.ci.

Foutcode overzicht

Hieronder vindt u kort overzicht van de verschillende foutcodes die onder de tabel stuk voor stuk uitgelegd worden:

Error codes

1 - No search query was given

Er zijn twee zaken verplicht bij het aanroepen van de API; de bearer token (zie errorcode 2) en de zoektekst. U krijgt deze errorcode als u geen zoektekst heeft doorgegeven. U doet dit door de parameter q te gebruiken. De aanroep van de API ziet er dan bijvoorbeeld zo uit: https://test-api.codi.ci/api/search?q=flowered%20cotton%20dress. Let op dat u de zoektekst converteert om aanroepen goed te laten aankomen. Dit wordt wel url-encoding genoemd. Het past tekens die niet in de aanroep thuis horen aan zodat dit door de API wel gebruikt kan worden. Een voorbeeld is bijvoorbeeld de spatie (%20) of een vraagteken (%3F).

2 - No bearer token found.

De bearer token wordt gebruikt om uzelf te authenticeren. U kunt de token (een reeks van cijfers en letters) in uw portaal vinden. Om de bearer token door te geven aan de API moet deze in de header van het bericht worden opgenomen. De header moet dan zijn:
Authorization: Bearer 1234567890
waarbij 1234567890 uw eigen bearer token is. U kunt voor een paar programmeertalen voorbeelden vinden op onze GitHub.

3 - Unknown parameters found.

U heeft in de aanroep van de API parameters gebruikt die niet herkent worden (en dus niet in het lijstje voorkomen in het overzicht onder het kopje API Call). Wellicht heeft u een typfout gemaakt en wilde u iets anders doorgeven. De extra parameters zouden geen probleem moeten opleveren bij het gebruik van de API maar het is beter om ze niet in de aanroep mee te nemen.

4 - Client might not accept JSON.

De computer die via de API een aanvraag doet kan aangeven welke type antwoorden hij begrijpt. De antwoorden van onze API worden gegeven in het type application/json. Een computer die het verzoek indient kan aangeven welk antwoord hij kan verwerken met de header Accept. Dit doe je dan door in de headers het volgende mee te geven:
Accept: application/json
U kunt ook aangeven dat allerlei antwoorden begrepen gaan worden:
Accept: */*
Op dit moment geeft de API altijd antwoord in het JSON formaat maar om fouten in de toekomst bij aanpassingen van de API te voorkomen is het verstandig om dit wel op te nemen.

Uitgebreid testen

WanneerOnce you have finished the initial integration, it is possible (for the test API only) to force specific situations to allow you to test for those as well. This is done by using the parameter cmd. There are a few possible commands that you can use:

You can combine commands by seperating them with a comma. So the command cmd=c,3 will give you 3 results with real HS-codes. Some combinations might not make sense, like cmd=u,3 which will just give you an unauthenticated error or could be vague: cmd=c,3,4 which will actually give you 4 real HS-codes because the last numeric occurence is used.