Introductie

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

Nieuw? Snel aan de slag

Als je een nieuwe applicatie ontwikkelaar bent kunt je direct aan de slag in onderstaande 4 stappen.

Doelgroep en scope

De API stellen we beschikbaar voor ontwikkelaars van externe applicaties, ERP's en applicaties in de Floriday app-store die zich richten op kwekers, verkooporganisaties en importagenten ter ondersteuning van de verkoop van sierteelt gerelateerde producten.

De verkoop is gericht aan klanten op de bij Floriday aangesloten kanalen, die ondersteund wordt door aangesloten logistieke en financiele dienstverleners. Kwekers kunnen zelf ook (betaalde) logistieke diensten aanbieden zoals stickeren.

Floriday zal zich met haar modules vooral richten op verkoop, verkoopplanning, voorraadbeheer, orderverwerking (inclusief logistiek) en transport en niet op typische ERP/commodity functionaliteit zoals arbeidsregistratie/HR, teeltplanning, boekhouding, productie, etc.

We geven kwekers de keus om gebruik te maken van Floriday modules of (externe) applicaties.

Instellingen zoals acceptatie van voorwaarden, dienstregistratie/keuzes en levertijdensets en Netwerk features zoals chat, social zullen alleen mogelijk zijn in het Floriday platform.

Floriday ontwikkelprincipes

Bij het ontwikkelen van de API worden door Floriday de volgende principes gehanteerd:

Roadmap 2019

Onderstaand is de meest actuele versie van de ERP API Roadmap 2019.

Huidige scenarios

De volgende scenario's worden ondersteund in de huidige API versie.

Onderstaand zijn de basis artikel- en voorraad scenario's

Onderstaand zijn de directe verkoop aanbod scenario's.

Onderstaand zijn de directe verkoop sales order scenario's.

Toekomstige scenarios

Concept warehouses en locaties met verplaatsing van partijen van kwekerlocatie naar externe voorraad locatie (eigen DC of instore) en klok of klant locaties.

Onderstaand zijn Leveren uit voorraad scenario's voor levering van kweker locatie naar Instore/eigen DC.

Onderstaand zijn Leveren uit voorraad scenario's voor levering van Instore/eigen DC naar klant locatie.

Onderstaand zijn Leveren uit voorraad scenario's voor levering van kweker locatie naar klok locatie.

Onderstaand zijn Klokverkoop scenario's voor aanbod en levering van kweker locatie naar klok locatie.

Onderstaand zijn Klokverkoop scenario's voor sales orders.

Onderstaand zijn de directe verkoop scenario's voor levering, betaling en facturatie.

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.

Er zullen geen breaking changes plaatsvinden in de endpoints binnen de huidige versie nadat de versie 'stabiel' (stable) is. Mochten er wel breaking changes nodig zijn, dan zal dit worden meegenomen in de eerstvolgende versie die in ontwikkeling is (in development).

Gedurende de Beta fase zullen we tegelijkertijd 2 versies ondersteunen, de meest recente en de vorige versie.

Wijzigingen in de API’s zullen gecommuniceerd worden aan de uitgevers van de applicaties die binnen Floriday staan geregistreerd. Dit gebeurt via de email of via het Slack-kanaal #floriday-erp-live en #erp-support.

Laatste API versie

Voor de laatste versie van de API v0.2 kun je benaderen via deze link.

Voor de vorige versie van de API v0.1 verwijzen we naar deze link.

Van staging naar live

Floriday kent nu twee verschillende omgevingen, ‘Staging’ en ‘Live’. De staging omgeving kan gebruikt worden om koppelingen te testen met eigen accounts, let op deze omgeving wordt ook gebruikt door Floriday om te testen. In de live omgeving vindt de uiteindelijke koppeling plaats in productie. Deze twee omgevingen zijn volledig gescheiden en hebben andere URL’s en ook andere credentials.

Na succesvolle aanmelding krijgt de ontwikkelaar van de client applicatie toegang tot de 'staging' omgeving. Zodra de testen succevol zijn verlopen, wordt een afspraak met je gemaakt voor de implementatie voor een finale check, waarna toegang wordt verleend voor de 'live' omgeving.

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 het aanvraagformulier bedoeld onderaan deze pagina. 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 flow (+Api-Key)
  2. Authorization Code with pkce flow (+Api-Key)

In de praktijk gebruiken de meeste applicaties de Client Credentials flow. De belangrijkste voorwaarde hierbij is of de applicatie in staat is de 'Client Credentials' geheim te kunnen houden.

Client Credentials flow

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.

Hiervoor gelden in ieder geval de volgende richtlijnen:

  • De Client Credentials zijn niet toegankelijk of zichtbaar door de gebruiker.
  • De code staat niet gewoon (plain) in een publiek te downloaden binary.

De client credentials bestaan uit twee velden:

Client ID: XXXXXXXXXXXX
Client Secret: XXXXXXXXXXXXXXXXXXXXXXXXX

De Client Credentials worden per applicatie verstrekt via mail na aanmelding.

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.

De implementatie zal er dan als volgt uitzien:

PKCE flow

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.

Er wordt gewerkt met een Client ID:

Client ID: XXXXXXXXXXXX

De Client ID worden per applicatie verstrekt via mail na aanmelding.

In deze flow krijgt de app na het opsturen van de Client ID en challenge met een redirect URL 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 (1 uur). Deze token gaat gepaard met een refreshtoken die vervolgens gebruikt kan worden om een weer nieuwe token te verkrijgen, deze kent een langere geldigheidsduur (7 dagen)

De implementatie zal er dan als volgt uitzien:

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.

Het kopieren van de API-key in de applicatie kan door in te loggen op Floriday en via instellingen, apps en koppelingen de gewenste applicatie te selecteren. Daarna kan de gebruiker zijn applicatie toevoegen en de API kopieeren 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.

Autorisatie en permissies

Bij het vertrekken van het token worden ook de geldigheidsduur en de permissies verstrekt dmv. 'scopes'. De onderstaande scopes zijn van toepassing op de modules van Floriday. Deze dienen te worden gebruikt bij het aanroepen van de API.

Scopes Permissies
catalog:read Leesrechten voor de catalogus-module
catalog:write Schrijfrechten voor de catalogus-module
supply:read Leesrechten voor de stock-module en supply-odule
supply: write Schrijfrechten voor de stock-module supply-module
sales-order: read Leesrechten voor de order-module
sales-order:write Schrijfrechten voor de order-module.
organization:read Leesrechten voor de core-module: organisaties.
delivery-conditions:read Leesrechten voor de core-module: lever condities.
role:app Rechten horende bij de rol van 'applicatie'

 

Entiteitenmodel Floriday

Ter ondersteuning bij het ontwerp en de ontwikkeling stelt Floriday een entiteiten relatie model ter beschikking met een lijst van definities.

Leeswijzer:

  • Dit model bevat de voor de ontwikkeling relevante enteiteiten en relaties, niet alle mogelijke entiteiten en relaties zijn opgenomen daar dit onoverzichtelijk wordt.
  • Het model bevat alleen die entiteiten die worden ondersteund via de laatste versie van de API.
  • Floriday is continu in ontwikkeling en ook het entiteitenmodel, zodra er een nieuwe versie van de API wordt ondersteund, wordt het entiteitenmodel daarop uitgebreid.
  • Het entiteitenmodel impliceert dat er alleen vanuit base supply supply-lines aangemaakt kunnen worden, dat is niet het geval. Vanuit het stock domein (batch/continuous stock) kunnen ook supply-lines aangemaakt worden.

Definities

Base Supply

  • beschrijft de prijs en commerciële aantallen van een trade item voor een bepaalde periode.
  • wordt gebruikt als basis om koper-specifiek aanbod aan te maken met behulp van price groups.
  • als er een batch is aangemaakt, heeft het supply dezelfde packing configuration als de batch. Als er sprake is van continuous stock gelden alle packing configurations van het trade item.
  • Aantallen op Base Supply (Commercial Quantity):
    • indien gekoppeld aan een batch : het beschikbaar aantal is gelijk aan het aantal van de batch.
    • indien er sprake is van continuous stock: beschikbaar aantal wordt periodiek gezet bij het aanmaken van base supply.

Batch

  • een aantal eenheden (voorraad) van een trade item op een warehouse.
  • wordt gebruikt bij voorraad management (aftellend aanbod).
  • is verplaatsbaar naar een ander warehouse.
  • heeft 1 specifieke verpakking (packing configuration).

Continuous Stock

  • beschikbaarheid kan aan/uit gezet worden per trade item.
  • tegenhanger van aftellend aanbod (zie: Batch).

Delivery Condition

  • de aflevervoorwaarden die gelden voor de sales orders.
  • beschrijft aflevertijden en -plaatsen, minimale afname en afleverkosten.
  • heeft optioneel extra services met prijs specificatie.
  • geldt voor 1 of meerdere warehouses.

Organization

  • een bedrijfsregistratie.
  • heeft een type (bijvoorbeeld supplier, customer, service provider).
  • kan 1 of meer warehouses hebben.

Packing Configuration

  • beschrijft een wijze waarop het trade item verpakt en beladen kan worden.

Price Group

  • beschrijft een op- of afslag die een groep klanten ontvangt ten opzichte van de basis prijs.
  • is specifiek voor 1 of meer sales channels.
  • wordt gebruikt om koper-specifieke supply lines af te leiden van base supply.

Sales Channel

  • Platform waar kopers trade items kunnen kopen.

Sales Order

  • de overeenkomst tussen koper en kweker betreffende de verkoop van trade items.
  • wordt vastgelegd bij 1 supply line.
  • valt onder de aflevervoorwaarden van een delivery condition.
  • heeft een afleverlocatie en laatste aflevertijd die voldoen aan de voorwaarden van een delivery condition.
  • heeft 1 packing configuration; door de koper gekozen uit de opties van het supply.

Supply Line

  • het algemene of koper-specifieke aanbod dat verkocht wordt in sales channels (zoals FloraXchange, Floramondo, Klokverkoop).
    heeft een optionele lijst van in- en excluded kopers (In/Excluded CustomerOrganizations).

Trade Item

  • beschrijft het product
  • heeft 1 of meer belading opties (packing configurations)
  • beschikbaarheid kan 'getoggled' worden (continuous stock)

Warehouse

  • een voorraad-locatie.
  • betreft zowel kweker-eigen tuinen als externe locaties, bijvoorbeeld die van RFH.
  • heeft optioneel specifieke service verlening; bijvoorbeeld extern voorraadbeheer.

Support

Voor vragen gerelateerd aan de aanmelding: support@floriday.io

Voor hulp en functionele/technische vragen bij de ondersteuning van de ontwikkeling verwijzen we graag naar ons Slack kanaal #erp-support.

Voor implementatie vragen: Roel Voerman: roel@floriday.io

Aanvraagformulier Floriday client

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

Openbaar

Slack

Technisch aanspreekpunt

Authenticatie

Requested additions

The following list of requested additions are on our backlog (non exhaustive):

  • add batch 'characteristics'
  • add batch photos
  • better synchronization methods
  • changing trade-items
  • clock sales API
  • continuous batch on a given warehouse location
  • clarity on distribution of Floricode codelists
  • clarity on multi-purpose or single purpose API's: eg. specific fulfillment API for clock sales and direct sales or one fulfillment API.
  • clarity on regulation of channel characteristics
  • delivery and payment direct sales API
  • english version of all documentation
  • example scenarios based on uses cases of suppliers.
  • examples requests and responses
  • external stock API
  • get all organizations in one call
  • mockup testclient
  • multiple packing configurations on one batch
  • return photo URL with POST / media 
  • sales order corrections API
  • sandbox environment 
  • stock management with trade-item parts 
  • tag trade-items for 'termporary use', publish to external catalog, use for clock or direct, 'trade-item variant'
  • ...

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