Homologa API

Eine REST-API, um die Bestellung von Übereinstimmungsbescheinigungen in Ihr System einzubinden: FIN-Prüfung, Bestellanlage, Verfolgung und Webhooks. Schlüssel gibt es nur für Geschäftskonten.

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

Authentifizierung

Jeder Aufruf trägt Ihren Schlüssel im Header Authorization: Bearer ecoc_live_…. Schlüssel mit ecoc_test_ sind Sandbox-Schlüssel: Damit erstellte Bestellungen sind entsprechend markiert und werden nicht berechnet.

Ein Schlüssel gehört zu einer Firma und einem Satz Berechtigungen. Er wird gehasht gespeichert: Notieren Sie ihn bei der Erstellung, wir können ihn nicht erneut anzeigen.

Berechtigungen

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

Limits

120 Anfragen pro Minute und Schlüssel. Darüber antwortet die API mit 429 und einem Retry-After-Header.

Endpunkte

Methode	Pfad	Beschreibung
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

Beispiel: eine FIN prüfen

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

Fehler

Fehler folgen application/problem+json (RFC 9457): ein stabiler code, ein lesbares detail und bei Validierungsfehlern die Liste der betroffenen Felder.

Code	Status	Beschreibung
`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

Hinterlegen Sie im Geschäftskundenbereich eine HTTPS-URL, um Statusänderungen zu erhalten. Jede Zustellung ist signiert (HMAC SHA-256) und wird bei Fehlern mit wachsendem Abstand wiederholt.

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

OpenAPI

Das OpenAPI-Dokument ist öffentlich und versioniert: Generieren Sie Ihren Client daraus, statt die Aufrufe von Hand zu schreiben.

openapi.json herunterladen