Homologa API

A REST API to plug Certificate of Conformity ordering into your own tooling: VIN check, order creation, tracking and webhooks. Keys are reserved for business accounts.

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

Authentication

Every call carries your key in the Authorization: Bearer ecoc_live_… header. Keys starting with ecoc_test_ are sandbox keys: orders created with them are flagged as such and are not invoiced.

A key belongs to one company and one set of scopes. It is stored hashed: copy it when you create it, we cannot show it again.

Scopes

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

Limits

120 requests per minute per key. Beyond that the API answers 429 with a Retry-After header.

Endpoints

Method	Path	Description
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

Example: check a VIN

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

Errors

Errors follow application/problem+json (RFC 9457): a stable code, a readable detail and, for validation failures, the list of offending fields.

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

Declare an HTTPS URL in your business area to receive status changes. Every delivery is signed (HMAC SHA-256) and retried with a growing delay on failure.

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

OpenAPI

The OpenAPI document is public and versioned: generate your client from it rather than hand-writing the calls.

Download openapi.json