Introductie

Deze pagina beschrijft de manier waarop een software leverancier kan aansluiten op de infrastructuur van Floriday. Deze koppeling kan gebruikt worden voor zowel het aansluiten van externe softwarepaketten als het bouwen van een App binnen het Floriday platform.  In beide situaties is er toegang nodig tot de data van eindgebruikers op Floriday.

Verschillende omgevingen
Floriday kent twee verschillende omgevingen, ‘Staging’ en ‘Live’. De staging omgeving kan gebruikt worden om koppelingen te testen. In de live omgeving vindt de uiteindelijke koppeling plaats.  Deze twee omgevingen zijn volledig gescheiden en hebben andere URL’s en ook andere credentials.

Authenticatie

Om toegang te krijgen tot de functionaliteiten van Floriday en de data van de eindgebruikers moet de applicatie bekend zijn binnen Floriday en daarnaast zal de eindgebruiker toegang moeten geven aan de applicatie om zijn gegevens te mogen benaderen. Hiervoor wordt een authenticatiemodel gebruikt volgens de OAuth2 standaard, aangevuld met een API-key.

Een applicatie moet bekend zijn binnen Floriday, hiervoor is een speciaal aanvraagformulier. De gegevens worden bij Floriday gevalideerd waarna de applicatie wordt aangemaakt en de benodigde gegevens worden verstrekt.

Momenteel ondersteunen we twee verschillende OAuth flows:

  1. Client Credentials (+Api-Key)
  2. Authorization Code with pkce (+Api-Key)

Client Credentials

Client Credentials is de meest directe vorm van authenticatie. Er wordt gewerkt met Client Credentials die vertrouwelijk dienen te worden behandeld, en niet aan derden moeten worden verstrekt. De client credentials bestaan uit twee velden:

Client ID: XXXXXXXXXXXX
Client Secret: XXXXXXXXXXXXXXXXXXXXXXXXX

Deze credentials zijn in te wisselen voor een JWT (JSON web token), die vervolgens gebruikt kan worden voor de communicatie met de API’s. Dit verloopt via de OAuth2 client credentials flow. Dit is onder andere te lezen in de documentatie van Okta: https://developer.okta.com/authentication-guide/implementing-authentication/client-creds#3-using-the-client-credentials-flow

De URL waarmee credentials zijn in te wisselen voor een JWT staan beschreven in de configuratiebestanden van de authenticatieserver:

Staging: https://dev-268051.oktapreview.com/oauth2/default/.well-known/oauth-authorization-server

Live: https://floriday.okta-emea.com/oauth2/default/.well-known/oauth-authorization-server

De verkregen JWT dient bij iedere API call te worden meegegeven in de Authorization HTTP-header, voorafgegaan door ‘Bearer ‘.

Deze JWT is overigens een versleuteld JSON bericht. Op www.jwt.io is meer te lezen over deze token en kan je de inhoud ook makkelijk inspecteren.

Authorization Code with PKCE

Als de aanroepende client de credentials niet geheim kan houden is de 'Authorization Code with PKCE' de juiste flow. Deze flow gaat ook in combinatie met de Api-Key.

In deze flow krijgt de app een code nadat de gebruiker zijn inlog-gegevens heeft ingegeven . Deze code is vervolgens op een veilige manier in te wisselen voor een token met een beperkte geldigheidsduur. Deze token gaat gepaard met een refreshtoken die vervolgens gebruikt kan worden om een weer nieuwe token te verkrijgen.

API-key

Naast client credentials heeft de applicatie ook toestemming nodig van de gebruiker om namens hem de data te mogen bevragen en de functionaliteiten te gebruiken. Deze toestemming vindt plaats door de overdracht van de API key. De gebruiker gaat hiervoor naar de instellingen van Floriday. Hier kan hij toestemming geven aan een applicatie waarna een API key wordt gegenereerd. Deze key moet overgedragen worden aan de applicatie. Vaak gebeurt dit door deze te kopiëren en plakken in de applicatie.

De gebruiker heeft op een later tijdstip de mogelijkheid om de toegang voor een applicatie weer te ontzeggen. Hiermee wordt de API key ongeldig. De gebruiker heeft niet de mogelijkheid om een API key nogmaals op te vragen. Is de key kwijt, dan zal er door de gebruiker een nieuwe key gegenereerd moeten worden.

Met de API-key en de JWT samen zijn de API’s te gebruiken op Floriday.

Versiebeheer

Momenteel bevinden API’s zich nog in een bètafase en zijn ze nog volop in ontwikkeling. Er worden steeds meer endpoints uitgerold en er kunnen ook nog aanpassingen plaatsvinden. De verwachting is dat begin 2019 de eerste echte release wordt uitgebracht van de API’s. Dit houdt in dat we vanaf dat moment geen breaking changes meer door willen voeren in deze API’s. Mochten er wel breaking changes nodig zijn, dan zullen we dit doen met een versie aanduiding.

Huidige versie staat op :

https://api.staging.floriday.io/apps/api-spec

(Tip: Met editor.swagger.io is de specificatie eenvoudig te vertalen naar diverse clients!)

Wijzigingen in de API’s zullen gecommuniceerd worden aan de uitgevers van de applicaties die binnen Floriday staan geregistreerd. Dit gebeurt op regelmatige basis via de email of via het Slack-kanaal.

Entiteitenmodel Floriday

Het model binnen Floriday is zo van opzet dat logistiek, commercieel en financieel onafhankelijk van elkaar kunnen opereren.

Organizations  
Organization geeft toegang tot de relaties die bekend zijn binnen Floriday.

Trade items
Met trade items kunnen de artikelen opgevraagd en beheerd worden die de catalogus van de kweker vormen. Naast het toevoegen, verwijderen en opvragen van de catalogus kan de beschikbaarheid hier worden ingesteld en ook de weekgebaseerde catalogusprijzen worden beheerd.  

Delivery conditions
Delivery conditions vertellen aan de kanalen onder welke voorwaarden een kweker zaken kan doen met klanten. De levercondities geven informatie over aflevertijden maar ook over extra kosten die de kweker in rekening kan brengen voor bepaalde dienstverlening. Momenteel worden de delivery conditions uitsluitend beheerd binnen Floriday en kunnen deze bevraagd worden middels de API.

Warehouses
De voorraad van de kweker (batches/partijen) staan geregistreerd op een specifieke voorraadlocatie. Dit wordt een warehouse genoemd. Warehouses zijn er in verschillende types waardoor er andere dienstverlening per warehouse mogelijk is. De warehouses die onder het eigen beheer van een kweker zijn, zijn de teeltlocaties. Doorgaans worden warehouses gevuld doordat er een levering wordt gedaan richting zo’n warehouse. Een uitzondering hierop is het warehouse van het type ‘teeltocatie’, hier kan direct een nieuwe partij worden aangemaakt.

Batches & supply
Een partij (batch) geeft een hoeveelheid van een bepaald artikel op een specifiek warehouse  weer. De aanwezigheid van een partij geeft niet automatisch aan dat deze partij ook wordt aangeboden. Pas als er een supply line wordt toegevoegd aan een batch kan deze partij kunnen worden verkocht.

Het creëren van supply kan op twee manieren:

  1. Door het toevoegen van prijsinformatie aan een partij: Bij deze variant is het supply gebaseerd op aftellende aantallen die gekoppeld zijn aan een partij.
  2. Door het toevoegen van prijsinformatie aan een artikel: Bij deze variant is het supply gebaseerd op ‘beschikbaarheid’ die via de API aan en uitgezet kan worden. Een artikel kan op ieder moment aan en uitgezet worden, de status wordt gebruikt bij de validatie van een order.

In beide gevallen kan er gebruikt worden van twee niveaus van prijsinformatie

  1. Een basisprijs: hiermee wordt de basisprijs (meestal de aftuinprijs) ingestuurd door de kweker en zal Floriday de uiteindelijke prijzen berekenen die in de markt worden gezet,
  2. De eindprijs: hiermee worden de eindprijzen in Floriday geplaatst die direct gebruikt worden voor de distributie naar de ingestelde kanalen.

De kanalen waar Floriday het aanbod naartoe verspreidt, kunnen door de kweker beheerd worden in Floriday.

Sales orders
Een sales order is een commerciële overeenkomst tussen een koper en een kweker. De sales order is altijd ‘regelgebaseerd’ en hierbinnen wordt altijd verwezen naar een supply line.

Er zijn verschillende types sales orders, zo wordt er een onderscheid gemaakt in sales orders die ontstaan zijn bij de klok, als onderdeel van een contract of bijvoorbeeld in onderling direct overleg.

Bij de totstandkoming van een sales order kan er een fulfillment request gegenereerd worden.

Fulfillment requests
Een leveropdracht die bedoeld is voor de verplaatsing van goederen van bron-warehouse naar destination-warehouse.  

Fullfillment orders
De daadwerkelijke invulling van een aantal FulfillmentRequests verdeeld over de karren. 

Support

Voor hulp en vragen verwijzen we graag naar ons Slack kanaal. Ook kunnen vragen gesteld worden bij de ondersteuning voor ontwikkelaars.

Voor technische vragen:
support@floriday.io

Voor inhoudelijke vragen:
Raymond van Sassen & Roel Voerman 

Aanvraagformulier Floriday client

Via dit formulier kan een applicatie aangemeld worden bij Floriday om zodoende client credentials te kunnen ontvangen.

Openbaar

Technisch aanspreekpunt

Veelgestelde vragen

Floriday maakt gebruik van analytische cookies om uw ervaring op onze website te verbeteren, om uw voorkeuren te onthouden en om informatie te kunnen geven waardoor de website kan worden verbeterd.


Door op akkoord te klikken, geeft u toestemming om Cookies te gebruiken.

 Klik hier 

voor meer informatie.

Ja, ik ga akkoord