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.
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.
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. |
|
