Api > Thing

API documentatie

Connectie

De API bevindt zich op https://schadeautos.nl/page/api/object.json (of eventueel https://schadeautos.nl/page/api/object.xml voor XML response). De API maakt deels gebruik van de standaard interface/validaties van het Schadeauto's framework. Een aantal parameters moet daarom in een widgets structuur worden doorgegeven. De beschrijving van deze widgets kan eventueel worden opgevraagd door een GET te doen (config > controller > widgets). Een request naar de API wordt altijd via een POST gemaakt. De POST kan als normale form data worden doorgegeven, of als JSON of XML. Voor die laatste twee moet dan de juiste Content-Type header worden gebruikt (respectievelijk application/json en application/xml).

Request

Een request bestaat altijd uit (minimaal) de volgende componenten:

action De gevraagde actie (functie) op de API.
widget Waarden voor gedefinieerde widgets:
- partner Naam/ID van de API partner (wordt door Schadeauto's toegekend).
- client Het ID van de klant waarvoor u een wijziging door wilt geven.
- time Het tijdstip van verzenden (Unix timestamp).
- hash De berekende hash voor dit bericht, afhankelijk van het secret voor deze klant.
params Overige parameters voor de actie (key=value paren, kan genest zijn).

De hash wordt gebruikt om het bericht te valideren. Voor deze hash wordt gebruik gemaakt van een secret dat niet in het bericht zelf wordt opgenomen. Het tijdstip van verzenden wordt in het bericht (en dus de hash) opgenomen om replay te voorkomen.

De hash wordt als volgt berekend (PHP notatie): sha1(flat_data($request_data) . $secret) (de waarde voor widget > hash is op dit moment nog leeg).

Het $secret wordt door Schadeauto's per klant (en per API partner) bepaald. De functie flat_data() sorteert de waarden eerst op de key, en plakt vervolgens alle waarden achter elkaar. Voor arrays gebeurt dit recursief.

Response

De response bestaat uit de volgende componenten:

data Met een timestamp time en een hash om het bericht eventueel mee te kunnen valideren.
result Het resultaat (formaat afhankelijk van de aangeroepen actie).
errors Eventuele foutmeldingen (optioneel).
messages Eventuele opmerkingen bij het resultaat (optioneel; key = opmerking, value = soort opmerking).

De hash wordt op dezelfde manier berekend als bij de request, alleen wordt hier in plaats van de parameters de response 'plat geslagen'.

Voorbeeld


<?php

function flat_data($data){
  if(!is_array($data)) return $data;
  ksort($data, SORT_STRING);
  return implode(array_map("flat_data", $data));
}

$url = "https://schadeautos.nl/page/api/object.json";
$secret = "S3cr3T";

$data = [
  "action" => "options", //lijst met beschikbare opties opvragen
  "widget" => [
    "partner" => "Demo",
    "client" => 123,
    "time" => time(),
    "name" => "make", //beschikbare merken
  ],
  "params" => [
    "typeId" => 25 //type "fiets"
  ]
];
$data["widget"]["hash"] = sha1(flat_data($data) . $secret);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$result = curl_exec($ch);
curl_close($ch);

print_r(json_decode($result, true));

?>

Dit geeft als resultaat:

Array ( [data] => Array ( [partner] => Demo [client] => 123 [time] => 1486717886 [hash] => 3a8e2238193aa9e40f2ad88f7d2f21b2d5ba26ab [name] => make [id] => [status] => [categoryId] => [typeId] => [limit] => [offset] => ) [result] => Array ( [528] => Aegis [529] => Allight [530] => Altena [533] => Basso [531] => Batavus //... [585] => Van Tuyl [587] => Victoria [588] => Vittorio [589] => Wilier ) )

Of bij een incorrecte hash:

Array ( [data] => Array ( //... ) [result] => [errors] => Array ( [hash] => hash: validFunc ) )

Functies

De volgende functies kunnen worden aangeroepen:

`options`

Voor alle xxxId velden is een lijst met mogelijke waarden beschikbaar. In de widgets moet de name worden meegegeven (het xxx deel in xxxId). Afhankelijk van het type opties moeten er eventueel nog aanvullende parameters worden meegegeven. Voor make (lijst met merken) moet bijvoorbeeld het typeId (type voertuig) worden meegegeven (zie het code voorbeeld hierboven). Als deze ontbreekt luidt de foutmelding No filter provided for 'typeId'.

`save`

Een object opslaan of bijwerken (als het id is meegegeven in de widgets).

Onderstaande velden kunnen worden meegegeven in de params. Als een veld als verplicht staat aangegeven is dit alleen bij een eerste save (insert) het geval. Bij elke volgende save (update) hoeven alleen de velden te worden doorgegeven die zijn gewijzigd. Als één waarde in een array wijzigt moeten altijd alle waarden uit de array opnieuw worden doorgegeven (met uitzondering van de prijzen, geef daar een 0 door om een prijs te wissen).

De validatie toont of een regular expresssion waar de waarde aan moet voldoen, of een verwijzing naar een set opties waar de waarde in moet liggen.

In onderstaande opsomming is de indeling gelijk als bij de normale invoer via het klanten-admin gedeelte van schadeautos.nl. Bij twijfel over de juiste invulling van het veld kan deze worden geraadpleegd.

Omschrijving	Veldnaam	Verplicht	Validatie	Opmerkingen
Identificatie
eigen identificatie	externalId		`/^.{0,50}$/`
status	status		options: `status`
categorie	categoryId	Ja	options: `category`
voertuigsoort	typeId	Ja	options: `type`
herkomst	originId		options: `origin`
kenteken	plate		`/^.{0,20}$/`
chassisnummer	vin		`/^.{0,50}$/`
motorcode	engine		`/^.{0,50}$/`
versnellingsbakcode	gearbox		`/^.{0,50}$/`
bouwjaar	year		`/^(0\|(19\|20)\d{2})$/`	0 = onbekend
bouwmaand	month		`/^(\d\|1[0-2])$/`	0 = onbekend
eerste registratie jaar	registerYear		`/^(0\|(19\|20)\d{2})$/`	0 = onbekend
eerste registratie maand	registerMonth		`/^(\d\|1[0-2])$/`	0 = onbekend
merk	makeId	Ja	options: `make`
model	baseModelId	Ja	options: `baseModel`
aanvulling type	modelType		`/^.{0,255}$/`
aldoc code	aldocCode		`/^.{0,15}$/`
Kenmerken & overige gegevens
kleur	colorId		options: `color`
	color		`/^.{0,100}$/`	Gebruik dit veld alleen als de kleur niet voorkomt in options: `color`
kleurcode	colorCode		`/^.{0,255}$/`
laksoort	varnish		options: `varnish`
carrosserie	bodyTypeId		options: `bodyType`
	bodyType		`/^.{0,100}$/`	Gebruik dit veld alleen als de carrosserie niet voorkomt in options: `bodyType`
aantal deuren	doorCount		`/^\d{1,2}$/`
brandstof	fuelId		options: `fuel`
	fuel		`/^.{0,100}$/`	Gebruik dit veld alleen als de brandstof niet voorkomt in options: `fuel`
transmissie	gearId		options: `gear`
	gear		`/^.{0,100}$/`	Gebruik dit veld alleen als de transmissie niet voorkomt in options: `gear`
BTW / marge	vatType	Ja	options: `vatType`
handelsprijzen	stock		`/^[jn]$/`	j = ja, n = nee
grijs kenteken	van		`/^[jn]$/`	j = ja, n = nee
tellerstand	odometer		`/^\d{1,10}$/`
tellerstand eenheid	odometerUnit		options: `odometerUnit`
vermogen	power		`/^\d{1,10}$/`
vermogen eenheid	powerUnit		options: `powerUnit`
motorinhoud	engineSize		`/^\d{1,10}$/`	[cc]
gewicht	weight		`/^$/`	[kg]
co2 uitstoot	emission		`/^\d{1,10}$/`	[gram/km]
aantal versnellingen	gearCount		`/^\d{1,2}$/`
aantal airbags	airbagCount		`/^\d{1,2}$/`
apk goedgekeurd tot en met	motDate		`/^(\d*\|(19\|20)\d{2}-(0[1-9]\|1[012])-([012]\d\|3[01]))$/`	Datum in `jjjj-mm-dd` formaat of Unix timestamp
Prijzen
prijzen	prices		array	Array van records met de volgende velden:
- soort	type	Ja	options: `price`
- prijs	price	Ja	`/^\d{1,10}$/`
- BTW	inclVat		incl / excl
- BPM	inclVehicleTax		incl / excl
Schades
schades	damages		array	Array van waarden
- soort			options: `damage`
overige schades	otherDamages
Opties
opties	options		array	Array van waarden
- soort			options: `option`
overige opties	otherOptions
Bijzonderheden
bijzonderheden	details		array	Array van waarden
- soort			options: `detail`
overige bijzonderheden	otherDetails
Foto's
foto's	pictures		array	Array van waarden
- foto			URL, afbeelding	Wij schalen de foto naar een breedte van 1280 pixels
video	video		`/^.{0,255}$/`	URL van de video (bijvoorbeeld YouTube)
feedback URL	feedbackUrl		`/^.{0,255}$/`	Feedback URL voor aanpassingen die de klant via schadeautos.nl zelf maakt. Aan de URL worden het ID van het voertuig toegevoegd, en de nieuwe status: reserved: voertuig is gereserveerd sold: voertuig is verkocht deleted: voertuig is verwijderd activated: voertuig is weer geactiveerd Voorbeeld: voor ID = 123456 wordt de feedbackUrl = `https://mijnsite.nl/feedback.php?key=123` meegegeven. In het geval van verkoop wordt de aangeroepen URL dan: `https://mijnsite.nl/feedback.php?key=123&id=123456&status=sold`

Het resultaat is altijd het (toegekende) id, tenzij er foutmeldingen zijn.

Voorbeeld

Bijwerken van een bestaande advertentie (id = 654321):


$data = [
  "action" => "save",
  "widget" => [
    "partner" => "Demo",
    "client" => 123,
    "time" => time(),
    "id" => 654321
  ],
  "params" => [
    "categoryId" => 1, //schade
    "typeId" => 1, //personenwagen
    "makeId" => 61, //opel
    "baseModelId" => 1130, //astra
    "vatType" => "m",
    "year" => 1990,
    "month" => 11,
    "power" => 123,
    "powerUnit" => "k",
    "engineSize" => 1600,
    "airbagCount" => 5,
    "damages" => [46, 47],
    "otherDamages" => "lekt olie",
    "options" => [39, 33, 40],
    "prices" => [
      ["type" => 4, "price" => 1230]
    ],
    "pictures" => [
      "http://website.nl/picture/foo/bar-1.jpg",
      "http://website.nl/picture/foo/bar-2.jpg",
      "http://website.nl/picture/foo/bar-3.jpg"
    ]
  ]
];

`details`

Alle details van een enkel object ophalen. Het id moet worden meegegeven in de widgets.

Merk op: Als een foto wijzigt, wijzigt ook de bestandsnaam. Als de bestandsnaam niet is gewijzigd is de foto dus ook niet gewijzigd.

`delete`

Een object markeren als verwijderd (wordt niet meer getoond en zo spoedig mogelijk gearchiveerd; zie status). Het id moet worden meegegeven in de widgets.

`overview`

Overzicht van alle objecten (voertuigen) voor deze klant. Deze kunnen eventueel worden gefilterd op (widgets):

status Alleen voertuigtype met deze status (options: status).
categoryId Alleen voertuigtype in deze categorie.
typeId Alleen dit voertuigtype.
limit Limiteer het aantal voertuigen tot dit aantal (integer).
offset Sla dit aantal (integer) voertuigen over.

De volgende parameters kunnen ook aan de request worden meegegeven (toevoegen aan de $data array in het voorbeeld):

make Alleen voertuigen van dit merk (options: make, met het gewenste typeId).
baseModelId Alleen voertuigen van dit model (options: baseModel, met het gewenste makeId).
externalId Alleen voertuigtype met dit eigen ID.
fuelId Alleen voertuigen met dit type brandstof (options: fuel).
gearId Alleen voertuigen met dit type transmissie (options: gear).
optionId Alleen voertuigen met deze optie (options: option).
damageId Alleen voertuigen met deze schade (options: damage).
order Sorteren op:
- created Datum invoeren.
- position Positionering door dealer (een dealer kan een voertuig dat eerder is aangemaakt weer "vooraan" plaatsen).
- make Sorteren op merk, en daarna op model (dus als je op een bepaald merk zoekt is het sorteren op model).
- price Sorteren op prijs.
- year Sorteren op bouwjaar, en daarna op maand.
Achter elke sorteermethode kan ook " desc" worden toegevoegd om in omgekeerde volgorde te sorteren.

status