Beginpagina » Helpdesk » Finvia API » Algemeen » Finvia API
Helpdesk

Finvia API

Middels de API van Finvia kunt u afhankelijk van uw accounttype diverse gegevens beschikbaar stellen op uw eigen website of website van een derde. Hierbij stuurt uw websiteserver met behulp van uw scripts een verzoek direct aan het Finvia systeem. Na verwerking worden de resultaten aan uw script teruggegeven. De API stelt u in staat de resultaten in uw eigen opmaak en indeling te tonen op een andere website dan Finvia.nl

Momenteel zijn de volgende functionaliteiten beschikbaar:

Keten / Cluster Account:

  • Kantoren overzicht (getKantoren)
  • Adviseursoverzicht van een specifiek kantoor (getKantoorAdviseurs)

Kantoor Account:

  • Kantoor informatie (getKantoorInfo)
  • Adviseursoverzicht (getAdviseurs)

Werkwijze




De werkwijze van de Finvia API is als volgt. Uw website server genereert een verzoek (Request) in XML-formaat, bijvoorbeeld om al uw adviseursprofielen op te halen. Uw server stuurt dit verzoek direct naar Finvia door middel van de Finvia API Client. De Finvia API Server verwerkt het verzoek, raadpleegt de Finvia Database Servers en geeft het antwoord (Response) terug in de vorm van een tweede XML-document. Met dit antwoord kunt u afhankelijk van de aangeroepen functie de gegevens verder verwerken tot bijvoorbeeld een overzicht in de look-and-feel van uw eigen website.

Finvia is verantwoordelijk voor het verwerken van uw ‘Requests’ en het teruggeven van een ‘Response’. U bent zelf verantwoordelijk voor uw server-scripts en het genereren van correcte XML-verzoeken.

Als uw website geprogrammeerd is in PHP kunt u gebruik maken van onze PHP API Client. Is uw website geprogrammeerd in ASP.NET dan gebruikt u de ASP.NET API Client. De API Client gebruikt u binnen uw website om correcte XML verzoeken (‘Requests’) te genereren.

Gebruik van de Finvia API


Om een Finvia-account voor API-gebruik aan te melden logt u in op uw Keten / Cluster account of uw kantoor account en gaat u naar ‘Beheersinstellingen’ vervolgens ‘API-instellingen’ en voegt u de website waar binnen u gebruik wilt maken van de API toe door middel van de knop ‘Website toevoegen’. Er wordt dan een ‘Hash-code’ gegenereerd. Dit is een soort lang wachtwoord welke gebruikt wordt ter identificatie van uw website. Deze ‘Hash-code’ dient u te specificeren in het configuratie bestand van de API Client versie van uw keuze.

Downloaden Finvia API Client


Finvia biedt een kant-en-klare API Client aan voor eenvoudige communicatie met de Finvia API Server. De PHP versie vereist dat PHP is gecompileerd met CURL ondersteuning.

Finvia API Client PHP versie 1.0 Download Zip-bestand Download Tar.gz bestand
Finvia API Client ASP.NET versie 1.0 Binnenkort beschikbaar!


In bovenstaand archiefbestanden vindt u, naast API Client bestanden ook een voorbeeld / demo bestand. Voor de meest actuele functies en documentatie verwijzen we u altijd naar deze pagina.

Upload de API Client bestanden naar uw webserver en pas het configuratie bestand aan. Binnen het configuratiebestand dient u uw Finvia loginnaam te specificeren en de gegenereerde ‘Hash-code’.

Finvia verleent klanten het recht om de Finvia API Client scripts te gebruiken en aan te passen als hulpmiddel voor communicatie met de Finvia API Server. Voor verdere distributie is vooraf toestemming van Finvia vereist.

XSD's

De volgende XSD's zijn van toepassing op de Request en Response XML-formaten. Aangezien de Finvia API altijd doorontwikkeld wordt kunnen deze XSD's aan verandering onderhevig zijn, waarbij wij proberen om backward-compatibility te behouden. Met deze XSD's kunt u uw XML-bestanden valideren.

Keten / Cluster Account
Request XSD request.xsd
Response XSD response.xsd
Kantoor Account
Request XSD request.xsd
Response XSD response.xsd

 

Functionaliteiten

In dit onderdeel worden de beschikbare functionaliteiten die u middels de Finvia API Client kunt aanroepen besproken.

getKantoren

Functienaam getKantoren
Context Cluster-account
Functieomschrijving Het resultaat van deze functie is een lijst met kantoren met contactgegevens zoals deze zijn opgevoerd in het Cluster-account en eventueel aangepast binnen individuele Kantoor-accounts.
Voorbeeld toepassing Lijst met vestigingen van een keten of aangesloten kantoren van een cluster.
Parameters geen
Voorbeeld PHP Nog niet beschikbaar
Voorbeeld ASP.NET Nog niet beschikbaar
Status Nog niet actief

 

getKantoorAdviseurs

Functienaam getKantoorAdviseurs
Context Cluster-account
Functieomschrijving Het resultaat van deze functie is een lijst met adviseurs met basisgegevens van een kantoor aangemaakt binnen het Cluster-account geidentificeerd met de parameter 'kantoor_id'.
Voorbeeld toepassing Lijst met adviseurs van een bepaalde vestiging van een keten of aangesloten kantoor van een cluster.
Parameters
Parameternaam id
Parameteromschrijving Kantoor identifier welke te vinden is via de URL van een kantoorprofiel.
Parameterwaarden numerieke waarde bijvoorbeeld 1234
Voorbeeld PHP Nog niet beschikbaar
Voorbeeld ASP.NET Nog niet beschikbaar
Status Nog niet actief

 

getAdviseurs

Functienaam getAdviseurs
Context Kantoor-account
Functieomschrijving Het resultaat van deze functie is een lijst met adviseurs met basisgegevens van het eigen kantoor aangemaakt binnen het Kantoor-account.
Voorbeeld toepassing Lijst met adviseurs van het kantoor.
Parameters
Parameternaam sort
Parameteromschrijving Sorteer de resultaten op parameter-waarde
Parameterwaarden achternaam, voornaam, geslacht_id, adviseur_id
Parameternaam sort_type
Parameteromschrijving Wijze waarop er gesorteerd moet worden; oplopend (asc) of aflopend (desc)
Parameterwaarden asc, desc
Voorbeeld PHP $aAdvisors = finvia_call_api_function('getAdviseurs',false,array('sort' => 'achternaam','sort_type' => 'asc'));
Voorbeeld ASP.NET Nog niet beschikbaar
Status Actief

 

Response-codes


Een overzicht van mogelijke response codes en beschrijvingen is in dit onderdeel uiteengezet. In het algemeen kunt u aannemen dat een response code tussen de 100 en 199 een foutcoditie ('ERROR') betreft en een response code van 200 of hoger een positief ('OK') resultaat is.

Response-code Response-type Omschrijving
100 Error Er is geen geldige HTTP-POST data gevonden binnen uw request. Controleer of er daadwerkelijk een HTTP-POST variabele is genaamd 'xml'.
101 Error Er is geen Finvia API Client versie meegezonden met het request.
102 Error Er is geen geldige Finvia API Client versie informatie meegezonden. U kunt alleen verbinden met een geldige versie van de Finvia API Client.
103 Error Er is geen geldige Hash-code meegezonden met het request. Controleer of u de Hash-code volledig hebt gekopieerd. Een Hash-code is altijd 32 karakters lang.
104 Error Er is geen geldige 'Mode' meegestuurd met uw request. Deze instelling kunt u niet wijzigen in uw configuratie bestand.
105 Error Er is geen Kantoor-account gevonden op basis van de meegezonden Hash-code. Controleer of u daadwerkelijk een Hash-code hebt aangemaakt voor dit kantoor.
106 Error Er is geen request-type meegezonden met dit request. Deze foutmelding zal zich voordoen als er geen functienaam gespecificeerd is in de aanroep functie van de API Client. Controleer of u op de juiste manier de aanroep functie gebruikt.
107 Error Er is geen geldig request-type meegezonden met dit request. Deze foutmelding zal zich voordoen als de functienaam verkeerd is ingevoerd of als de functie naam niet beschikbaar is binnen de ingestele 'Mode'.
108 Error Er zijn niet voldoende of teveel parameters meegegeven met de functie die wordt aangeroepen.
109 Error Er is een fout opgetreden met de authorisatie van de website waarop de Finvia Client API actief is. Deze melding kan zich voordoen op het moment dat de Hash-code gebruikt wordt voor een andere website dan is opgegeven in de API-instellingen binnen uw account of als er sinds het aanmaken van de Hash-code een IP-adres wijziging heefgt plaatsgevonden op uw website server.
110 Error Er is geen geldige gebruikersnaam opgegeven. Deze gebruikersnaam komt overeen met uw Cluster-account gebruikersnaam of Kantoor-account gebruikersnaam waar mee u inlogd op uw Finvia account.
200 Ok Succesvolle en geldige request. In de response treft u de opgevraagde gegevens aan.

 

Updates


In het onderstaande overzicht worden eventuele updates aan de Finvia API of deze documentatie bijgehouden.

Datum Wijziging
01-04-2009 Eerste versie Finvia API Client en documentatie beschikbaar.