API Homologa

Une API REST pour intégrer la commande de certificats de conformité à votre outil de gestion : vérification de VIN, création de commande, suivi et webhooks. Les clés sont réservées aux comptes professionnels.

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

Authentification

Chaque appel porte votre clé dans l’en-tête Authorization: Bearer ecoc_live_…. Les clés commençant par ecoc_test_ sont des clés sandbox : les commandes créées sont marquées comme telles et ne sont pas facturées.

Une clé est liée à une société et à un jeu de portées. Elle est stockée hachée : notez-la à la création, nous ne pouvons pas vous la réafficher.

Portées

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

Limites

120 requêtes par minute et par clé. Au-delà, l’API répond 429 avec un en-tête Retry-After.

Points d’entrée

Méthode	Chemin	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

Exemple : vérifier un VIN

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

Erreurs

Les erreurs suivent le format application/problem+json (RFC 9457) : un code stable, un detail lisible et, pour les validations, la liste des champs en cause.

Code	Statut	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

Déclarez une URL HTTPS dans votre espace professionnel pour recevoir les changements d’état. Chaque envoi est signé (HMAC SHA-256) et rejoué avec un délai croissant en cas d’échec.

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

OpenAPI

Le document OpenAPI est public et versionné : générez votre client à partir de lui plutôt que d’écrire les appels à la main.

Télécharger openapi.json