نقاط الوصول

You are helping me integrate the AuctionsAPI Vehicle History Report (VHR) API.
Write production code that follows this contract exactly. Ask before you guess.
 
## 1. Basics
- Base URL: https://auctionsapi.com/api/vhr
- Every request sends the header x-api-key: <key>. Read the key from an environment
  variable (VHR_API_KEY); never hard-code it, log it or send it to a browser.
- Bodies are JSON (Content-Type: application/json); every answer is JSON.
- A VIN has 17 characters: letters and digits without I, O or Q. Uppercase it.
 
## 2. Flow
1. GET /sources: the report types (sources) this key may order, each with id, name,
   available_formats and available_languages, plus free sample VINs.
2. POST /checks {"vin"} (free): asks every source, or only "source_ids": [1, 2],
   whether it has records. Each source in "sources" has id, name, available_formats,
   available_languages, price_usd (the price for this key) and a preview object.
   A source WITHOUT a "status" field and with non-empty available_formats can be
   ordered. Other values: status "pending" (still answering), "not_found" (no record),
   "error" (could not answer now; NOT the same as no data), "not_checked" (not asked;
   NOT proof that no data exists). If availability_confirmed is false, show
   availability_notice to the user before ordering.
3. POST /reports {"vin", "source_id", "formats", "language"}: orders ONE source.
   formats: any of "json", "html", "pdf" (default ["json"]); one price covers all of
   them. language: one code the source offers, for example "en" or "ru" (default
   "en"; arrays are rejected). Optional "expected_price_usd": the price_usd from the
   check; the API answers 422 if the price changed, before any charge.
4. The answer has request_id, report_id (may be null while preparing), vin,
   source_id, status, currency, files and status_url. files is {} until the report
   is ready, then {"json": url, "html": url, "pdf": url} for the chosen formats.
5. Download the files from those links. They are bearer links: anyone with a link
   can open it, so store them like secrets. No API key is needed for the files.
 
## 3. Waiting
- A call waits up to about 10 seconds. HTTP 202 means the work goes on.
- Poll GET status_url (or GET /requests/{id}) every 1 to 2 seconds until the status
  is final, even when the poll answers HTTP 200. Give up after a few minutes and
  poll again later; stopping the wait does not cancel the work on the server.
- Never send the same purchase again while one is pending: the API answers 409.
- Check statuses: running, completed, partial (some sources failed), failed.
- Report statuses: running, preparing, rendering, completed, not_found, failed.
  Final: completed, partial, failed, not_found.
 
## 4. Money rules
- Checks, statuses, history and retries are free.
- A report is charged once, only when every selected file is ready. not_found and
  failed are never charged. The sample VINs below are always free.
 
## 5. Other endpoints
- GET /reports?page=N: your purchased reports, newest first, 30 per page (Laravel
  pagination: data, current_page, last_page, next_page_url). Samples are not kept.
- GET /reports/{id}: one report, same shape as the POST /reports answer.
- POST /reports/{id}/retry: only after a report whose files failed. Reuses the
  saved source data: no new source call and no second charge.
 
## 6. Errors (JSON with error_code and message; nothing is charged)
- 401 missing or invalid key  - 402 not enough report balance
- 403 report type not enabled for this key  - 409 same report already pending
- 422 invalid body or changed price  - 429 too many requests (back off)
- 503 reports paused for a moment (retry later)
 
## 7. Webhooks (real VINs only)
- Add "webhook_url" (public HTTPS) and "webhook_secret" (16 to 256 characters) to a
  check or a report. The API answers 202 at once and POSTs the same JSON when ready.
- Verify X-VHR-Signature: "sha256=" + hex HMAC-SHA256 of
  X-VHR-Timestamp + "." + raw body, keyed with webhook_secret. Compare in constant
  time, refuse timestamps older than 5 minutes, de-duplicate X-VHR-Event-Id.
 
## 8. Sample VINs (free, answer at once, no webhooks)
- 7FARW2H56JE022576  2018 Honda CR-V EX AWD  (reports: 1, 2, 3, 4, 5, 6, 7, 8, 9)
- 1C4RJGAG3PC525071  2023 Jeep Grand Cherokee Laredo  (reports: 1, 3)
- KMUHCESB1SU250832  2025 Genesis GV80  (reports: 2)
- 5YFB4MDE0TP377402  2026 Toyota Corolla  (reports: 1, 6)
- KNAKR814DNA244958  2022 Kia Carnival  (reports: 3)
- KMTG341ABMU089876  2021 Genesis G70  (reports: 4)
- KMHB3518BNW003977  2022 Hyundai Casper 1.0  (reports: 5)
- JTDKB20U203000002  2008 Toyota Prius  (reports: 7, 8, 9)
- WVWZZZ3C4KE000001  2019 Volkswagen Passat  (reports: 7, 8, 9)
- VF1RFB00355000004  Renault  (reports: 9)
- WBA8E31070K000003  2016 BMW 3 Series  (reports: 7, 8, 9)
- SCBCN13S2TC024887  2026 Bentley Continental GT  (reports: 7)
- XTA219040P0906805  2023 LADA Granta  (reports: 7)
- JMZKE5W7A00623042  2017 Mazda CX-5  (reports: 10)
- WDC2539191F753149  2019 Mercedes-Benz GLC 300 d 4MATIC  (reports: 10)
- KNAF241BEMA915413  2021 Kia K3  (reports: 11)
- KMHGE41ABBU141129  2011 Hyundai Genesis  (reports: 11)
- KMHD641EELU077852  2020 Hyundai Avante  (reports: 11)
 
## 9. What to build first
- A small client with check(vin), order(vin, sourceId, formats, language) and
  waitFor(statusUrl) that polls with backoff and returns the final answer.
- Show the user which sources have records before ordering; never order a source
  that has a status field or no available_formats.