Begrippen

Status van een job, de sleutel, testmodus en de velden op een prijs.

Vaak KLIC-meldingen nodig? Bekijk de voordelige creditbundels

De koppeling werkt per job. Een job kan uit één of meer KLIC-meldingen bestaan. Elke melding heeft een order_id. De job heeft een job_id.

Status

Zo loopt een gewone job:

  1. quoted na POST /api/v1/jobs. Er is een prijs. Er is niets ingediend.
  2. payment_pending na checkout. Betaal via payment_url. Er is nog niets bij het Kadaster ingediend.
  3. submitted nadat de betaling rond is en de KLIC-melding naar het Kadaster gaat.
  4. partial als een deel van een gesplitst gebied al binnen is.
  5. ready als de levering klaar is. Dan komt webhook job.ready.

Andere statussen in het antwoord:

Status Betekenis
checkout De betaalpagina wordt net geopend. Kort.
paid Betaald met tegoed. De KLIC-melding gaat door.
accepted of submitting De KLICBOT API dient in via de factuurroute.
billing_required Direct indienen zonder betaalregeling. Alleen de KLICBOT API.
failed Lees error en error_code.
superseded Een nieuwere prijs in dezelfde quote_scope. De oude quote_hash geldt niet meer.

Sleutel

Je maakt de sleutel in het dashboard onder Instellingen, API & integraties. Alleen een beheerder. De sleutel zie je één keer. Klicbot bewaart de hash.

Recht PRO
read Prijs, lijst, status, levering
write Checkout en testbetaling
admin Alleen de KLICBOT API, voor POST /api/v1/keys

De header heet X-API-Key.

Een POST naar /api/v1 zonder die header krijgt HTTP 403 met de platte tekst CSRF token missing or invalid. De browsercontrole loopt eerder dan de sleutel. Stuur de header mee. Zonder waarde is het API Key required. Een onbekende sleutel is Invalid API Key.

Velden op een prijs

Veld Betekenis
quote_hash Vingerafdruk van deze prijs. Een oudere hash wordt geweigerd.
voorstel true als het gebied een voorstel is, bijvoorbeeld het perceel bij een adres.
address_hold true als er nog geen BAG-adres in het gebied ligt.
is_test true in testmodus.
force_new true maakt een nieuwe job, ook als client_ref al bestaat.
costs.customer_total_eur Het bedrag inclusief btw. Voor één vak €39,95.

Testmodus

Zet header X-Klicbot-Test: 1 of "is_test": true op de prijs. De job blijft een test.

  1. Checkout geeft payment_pending en een payment_url die eindigt op /test-pay. Dat is geen betaalpagina van Stripe.
  2. POST die URL met dezelfde sleutel. De job wordt ready.
  3. Haal GeoJSON, Shapefile of GeoPackage op. Dat is een nep-levering.
  4. Stond er een webhook_url op de job, dan komt job.ready.

Testmodus dient niets in bij het Kadaster en schrijft geen geld af. submit=true op een testjob geeft HTTP 403, code TEST_MODE.

Zodra de status ready is, bevat het antwoord dossier_url en dossier_label (Bekijk je KLIC-melding). Dezelfde velden zitten in de webhook job.ready. Dat is de aanbevolen levering aan je eindklant.

De url is /s/{order_id}/{token}. Het token is een lange willekeurige reeks en geldt alleen voor die order. Wie de link opent, ziet de viewer en de eis voorzorgsmaatregelen van die KLIC-melding. Er is geen GIS-download op die link. GeoJSON, Shapefile en GeoPackage blijven extra downloads met de API-sleutel.

Een verkeerd token of een token van een andere order komt niet binnen. Intrekken kan in het dashboard: die deellink, of alle deellinks van het bedrijf. Daarna opent de oude url niets meer. Voor KLICBOT PRO verloopt de link niet.

Vóór ready ontbreekt dossier_url.

Eigenaarschap

Een sleutel ziet alleen jobs van het eigen bedrijf. Een job van een ander bedrijf is HTTP 404. De levering van een nog niet betaalde job is HTTP 402, code NOT_PAID.