Homologa API

Een REST-API om het bestellen van gelijkvormigheidsattesten in uw eigen systeem te integreren: VIN-controle, bestelling aanmaken, opvolging en webhooks. Sleutels zijn voorbehouden aan zakelijke accounts.

Basis-URL: https://homologa.eu/api/v1
Versie: 2026-09-01

Authenticatie

Elke oproep draagt uw sleutel in de header Authorization: Bearer ecoc_live_…. Sleutels die met ecoc_test_ beginnen zijn sandbox-sleutels: bestellingen daarmee worden als zodanig gemarkeerd en niet gefactureerd.

Een sleutel hoort bij één onderneming en één set rechten. Hij wordt gehasht bewaard: noteer hem bij het aanmaken, wij kunnen hem niet opnieuw tonen.

Rechten

vin:check
orders:read
orders:write
webhooks:manage

Limieten

120 aanvragen per minuut per sleutel. Daarboven antwoordt de API met 429 en een Retry-After-header.

Endpoints

Methode	Pad	Beschrijving
GET	`/brands`	List brands with your prices and announced delays
POST	`/vehicles/check`	Check a VIN and get a quote
GET	`/orders`	List your orders (paginated)
POST	`/orders`	Create a COC order
GET	`/orders/{id}`	Get an order by id or reference
POST	`/orders/bulk`	Create up to 200 orders from JSON or CSV
GET	`/openapi.json`	This specification

Voorbeeld: een VIN controleren

curl -X POST https://homologa.eu/api/v1/vehicles/check \
  -H "Authorization: Bearer ecoc_test_…" \
  -H "Content-Type: application/json" \
  -d '{"vin":"WVWZZZ1KZAW123456"}'

Fouten

Fouten volgen application/problem+json (RFC 9457): een stabiele code, een leesbare detail en, bij validatiefouten, de lijst van betrokken velden.

Code	Status	Beschrijving
`missing_api_key`	401	No `Authorization: Bearer` header.
`malformed_api_key`	401	The key does not match `ecoc_(live\|test)_` + 40 characters.
`invalid_api_key`	401	Unknown or revoked key.
`company_suspended`	403	The company account is suspended.
`company_pending`	403	Account under verification: only sandbox keys can create orders.
`insufficient_scope`	403	The key does not carry the required scope.
`company_required`	403	The key is not attached to a company.
`not_found`	404	Resource not found (or belongs to another company).
`on_quote`	409	The manufacturer is priced on request.
`unsupported_media_type`	415	Body must be JSON (or text/csv for bulk).
`invalid_json`	400	Malformed JSON body.
`validation_failed`	422	Field-level errors listed in `errors[]`.
`invalid_vin`	422	The VIN is not 17 valid characters.
`no_coc`	422	No European COC exists for this vehicle (non-EU market, defunct manufacturer).
`brand_required`	422	Manufacturer not identified from the VIN: pass `brand`.
`unknown_option`	422	Unknown service option code.
`payload_too_large`	413	Bulk request above 200 rows.
`rate_limited`	429	More than 120 requests per minute on one key.
`internal_error`	500	Unexpected error: retry, then contact support with the request id.

Webhooks

Geef in uw zakelijke zone een HTTPS-URL op om statuswijzigingen te ontvangen. Elke aflevering is ondertekend (HMAC SHA-256) en wordt bij mislukking met oplopende vertraging opnieuw geprobeerd.

order.created
order.status_changed
order.document_ready
order.shipped
order.delivered
order.cancelled
invoice.issued

OpenAPI

Het OpenAPI-document is openbaar en geversioneerd: genereer uw client daaruit in plaats van de oproepen met de hand te schrijven.

openapi.json downloaden