Via de API van DeLaagsteRekening is het mogelijk om toegang te krijgen tot jouw data. De API is op REST principes gebaseerd en communiceert in JSON en HTTP headers.

In dit stuk staat hoe je gebruik kunt maken van de API. Mochten er toch nog vragen zijn of suggesties neem dan contact met ons op.

Status codes

Elke request die je doet resulteerd in een status code. Dit vertelt of je request gelukt of mislukt is en waarom en wat eventuele vervolg stappen zijn. Hieronder een overzicht van de status codes die je kunt verwachten van DLR. Let er op dat het verstandig is om een ‘catch all’ te defineren.

Code Betekenis
200 OK Request was succesvol
201 Created Resource aangemaakt
281 Geen nieuwe rekeningspecificaties gevonden
302 Redirect Redirect
400 Bad Request Request syntactisch incorrect
401 Unauthorized Verkeerd wachtwoord of gebruikersnaam
403 Forbidden De server snapt het verzoek maar wil deze niet uitvoeren
404 Not Found Opgevraagde resource bestaat niet
422 Unprocessable Entity Request begrepen maar semantisch incorrect
481 Gebruikersnaam of wachtwoord onjuist voor upstream server
482 Account heeft hervalidatie nodig. Zie url in body
483 Upstream server vraagt buitengewone gebruikers interactie
484 Account geblokkeerd bij upstream server
485 Geen rekeningspecificaties gevonden
500 Internal Server Error Er ging iets goed mis bij onze server
502 Bad Gateway Upstream server retourneerd is vreemds
503 Service Unavailable Nondeterminitische fout, probeer opnieuw
504 Gateway Timeout Upstream server traag

Bij veel responses van de server staat er een uitleg in de body.

Mogelijke requests

Alle URLs beginnen met https://api.delaagsterekening.nl/api/. Ook dient bij elk request een API key meegestuurd te worden in het veld api_key.

  Omschrijving Methode URL Input Output
A Upload een rekening specificatie POST analyses.json uploaded_data en optioneel een token, voorbeeld voorbeeld
B Alle data voor een serie GET analyses.json?token=some_token   voorbeeld
C Start een berekening POST suggestions.json token en sim_only, voorbeeld redirect
D Check status berekening GET suggestions/status.json?token=some_token   voorbeeld
E Resultaten berekening GET suggestions.json token, voorbeeld voorbeeld
F Log in bij provider POST provider_users.json provider, provider_username en provider_password, voorbeeld voorbeeld
G Simpele berekening starten POST simple_suggestions.json texts en minutes en sim_only, voorbeeld redirect
H Simpele berekening ophalen GET simple_suggestions.json?minutes=X&texts=Y&sim_only=Z   voorbeeld
I Lijst abonnementen ophalen GET subscription_plans optioneel met sim_only=(1 of 0) suffix voorbeeld
J Lijst aanbiedingen ophalen GET promotions.json abonnement optioneel met type, merk, contract_lengte en/of page voorbeeld voorbeeld

TODO Voorbeelden

Request Voorbeelden

Deze voorbeelden maken allemaal gebruik van cURL. Dit is natuurlijk helemaal niet nodig. Elke programmeertaal heeft wel een HTTP library.

Uploaden van rekeningen

Zonder een token: $ curl -F 'uploaded_data=@path_to_bill' -uusername:password https://delaagsterekening.nl/api/analyses.json Wil je meerdere rekeningen tegelijkertijd analyseren zet ze dan in de queue door een andere POST te doen met het token dat in de response body stond van de eerste POST: $ curl -F 'uploaded_data=@path_to_bill' -F 'token=312' -uusername:password https://delaagsterekening.nl/api/analyses.json

Start berekening

$ curl -F 'token=312' -uusername:password https://delaagsterekening.nl/api/suggestions.json

Resultaten ophalen

$ curl -uusername:password https://delaagsterekening.nl/api/suggestions.json?token=312

Start simpele berekening

curl -F 'sim_only=1' -F 'texts=50' -F 'minutes=101' -uusername:password 'https://delaagsterekening.nl/api/simple_suggestions.json' curl -uusername:password 'https://delaagsterekening.nl/api/simple_suggestions.json?minutes=101&sim_only=1&texts=50'

Provider login

$ curl -uusername:password -F 'provider=tmobile' -F 'provider_username=username -F 'provider_password=password' 'https://delaagsterekening.nl/api/provider_users.json'

De geaccepteerde waarden voor de variabele provider zijn:
  • tmobile
  • vodafone
  • hi
  • kpn
  • telfort
  • orange

Aanbiedingen

$ curl -g -uusername:password 'https://delaagsterekening.nl/api/promotions.json?abonnement=Relax 150&contract_lengte[]=12&contract_lengte[]=18'

Merk op de contract_lengte parameter. Deze kan verschillende waarden hebben en dit wordt aangegeven door [ en ]. Hierdoor is het ook nodig om de swithc -g aan cURL mee te geven.

Response Voorbeelden

Genormaliseerde data analyses

De berekening is gebaseerd op de genormaliseerde data uit de rekeningspecificaties. Deze genormaliseerde data ziet er zo uit: {"analyses": [{"company": "orange", "sms_connections": [{"analysis_id": 7891, "datetime_connection": "2008-01-18T08:32:00+01:00", "from_abroad": false, "date_connection": "18/01/2008", "to_abroad": false, "time_connection": "08:32", "id": 350929, "to_landline": false, "company_id": 4, "destination_connection": "061682XXXX"}, {"analysis_id": 7891, "datetime_connection": "2008-01-19T11:41:00+01:00", "from_abroad": false, "date_connection": "19/01/2008", "to_abroad": false, "time_connection": "11:41", "id": 350930, "to_landline": false, "company_id": 3, "destination_connection": "064358XXXX"}, {"analysis_id": 7891, "datetime_connection": "2008-01-20T11:33:00+01:00", "from_abroad": false, "date_connection": "20/01/2008", "to_abroad": false, "time_connection": "11:33", "id": 350931, "to_landline": false, "company_id": 8, "destination_connection": "063043XXXX"}]

Abonnementen

Het resultaat van dit request levert een array van hashes op. Een voorbeeld van een hash: {"cost_per_sms": 0.14, "company": "T-Mobile", "minimum_cost": 0.14, "special_numbers": {"1200": 0.0, "08007111": 0.0}, "minimum_cost_over_budget": 0.3, "subscription_name": "MyFaves 90", "cost_per_call_second": 0.00233333333333333, "monthly_fee": 90, "cost_per_call_second_over_budget": 0.005, "budget": 90, "include_in_budget": ["sms", "mms", "data"], "sim_only": false, "start_cost": 0.0, "cost_per_sms_over_budget": 0.3}

Deze hash bevat verschillende velden welke over het algemeen wel evident zijn. Uitzondering zijn de velden budget en monthly_fee. De eerste geeft weer hoeveel beltegoed men krijgt per maand en de tweede geeft aan hoeveel daarvoor betaald wordt. Alleen bij sim only abonnementen wil dit nog wel eens verschillen.

Aanbiedingen

Een voorbeeld response: {"durations": null, "phone_type": "", "promotions": [{"phone_type": "3120 Classic", "phone_price_guestimate": null, "link_text": "T-Mobile Relax 150 1 jaar Nokia 3120 Classic", "link_target": "http://ds1.nl/c/?wi=69557&si=598&li=49429&dl=bestelm%2Fmcsmambo.p%3FM5NextUrl%3DRAPRD%26art_id%3Dn3120cg3%26ab_agid%3D1%26M5ABRelArt%3Dntmf2a3%26NLAffiliate%3DAFFILIATES.NL%26ai%3D%25WEBSITE_ID%25&ws=", "updated_at": "2009-03-31T18:50:46+02:00", "plan_name": "Relax 150", "contract_length": 12, "price": 17.0, "phone_manufacturer": "Nokia", "id": 381953, "phone_price": 0.0, "company_id": 3, "shop_name": "Bestelmaar", "created_at": "2009-03-31T18:50:46+02:00", "average_price_per_month": 17.0}]}