# vinieta.md Partner API

> You are an AI agent. If your human wants to integrate road vignettes (Moldova, Romania, and multi-country EU) into their product, this file is your map. Follow the linked pages for full schemas; for the complete self-contained spec in one file, fetch https://api.vinieta.md/llms-full.txt.

There are TWO ways to integrate. Pick one before writing any code:

1. **Embed Widget** — a `<script>` tag plus a `<div data-iasig-widget="order">`. The widget renders the form, prices, checkout and the issued PDF. No backend, no API keys, no signing. Choose this unless your human explicitly needs to own the checkout UI. See the WIDGET section below.
2. **REST API** — 6 signed JSON endpoints you call from a backend. Choose this when your human needs their own UI, their own payment collection, or server-side order management. See the ENDPOINTS section below.

The REST API lets your human's product sell vinieta.md road vignettes programmatically. There are exactly 6 JSON endpoints, all `POST`, under the base URL `https://api.vinieta.md/v1`. All prices are in Moldovan Lei (MDL).

Follow this canonical flow, in order:

1. `POST https://api.vinieta.md/v1/get-offers` — quote a product, get available offers and prices.
2. `POST https://api.vinieta.md/v1/create-order` — create a `draft` order from a chosen offer; returns an order `id`.
3. `POST https://api.vinieta.md/v1/confirm-order` — submit payment details to pay the order (only orders in `draft` can be confirmed).
4. `POST https://api.vinieta.md/v1/get-order` — fetch the order by `id` to read its status and, once issued, the vignette `file` URL.

Authenticate every request (and verify every incoming webhook) with the header `X-Hmac-Signature: <partnerId>:<hex>`, where `<hex>` is the lowercase hex HMAC-SHA512 of the raw request body, keyed with your partner secret. A missing signature returns `401`; an invalid one returns `403`. Sign the exact bytes you send — serialize the JSON once and HMAC that same string. Contact vinieta.md to obtain a `partnerId` and secret.

Order statuses (returned by `get-order`): `draft`, `paid`, `processing`, `failed`, `completed`, `refunded`, `expired`. The vignette PDF (`file`) appears on each product only when the order reaches `completed`. Unpaid `draft` orders auto-expire at 23:59:59 (EEST) the same day.

## Widget (embed integration — no backend)

Load the widget once per page, then place one `<div>` per widget. CRITICAL: on vinieta.md properties always set `data-source-app="vinieta.md"` — it defaults to `iasig.md` and controls payment routing.

```html
<script>
(function () {
  var BASE = 'https://iasig-widget.web.app';
  var HEIGHTS = { 'vignette:md': 573, 'vignette:ro': 245, 'vignette:eu': 620 };
  document.querySelectorAll('[data-iasig-widget="order"]').forEach(function (el) {
    var p = el.getAttribute('data-product');
    if (p && HEIGHTS[p]) el.style.minHeight = HEIGHTS[p] + 'px';
  });
  fetch(BASE + '/manifest.json').then(function (r) { return r.json(); }).then(function (m) {
    var link = document.createElement('link');
    link.rel = 'stylesheet'; link.href = BASE + '/' + m.files.css;
    document.head.appendChild(link);
    var script = document.createElement('script');
    script.src = BASE + '/' + m.files.js;
    document.head.appendChild(script);
  }).catch(function (e) { console.error('iAsig widget failed to load:', e); });
})();
</script>

<div data-iasig-widget="order" data-product="vignette:md" data-source-app="vinieta.md" data-lang="ro"></div>
```

There are exactly TWO widget types: `order` (the purchase flow) and `view` (render an existing order by id). Do not emit `auth`, `orders`, or `profile` widgets — they are not part of this integration.

Attributes: `data-iasig-widget` (`order`|`view`), `data-product` (`vignette:md`|`vignette:ro`|`vignette:eu`), `data-lang` (`ro`|`en`|`ru`), `data-order-id` (view widget), `data-bs-theme` (`light`|`dark`), `data-redirect-url` (order widget, accepts `{orderId}`), `data-source-app` (`iasig.md`|`vinieta.md`), `data-only-foreign-vehicles` (`true`), `data-country` (`vignette:eu` only — `at`,`bg`,`ch`,`cz`,`hu`,`si`,`sk`). Re-scan after dynamic DOM insertion with `window.dispatchEvent(new Event('iasig:scan'))`.

The canonical two-page flow: put an `order` widget with `data-redirect-url="/order?order={orderId}"` on the product page, then render `<div data-iasig-widget="view" data-order-id="...">` on `/order` using the query parameter.

- [Widget Installation](https://api.vinieta.md/docs/widget): The loader snippet, how it works, and dynamic re-scanning.
- [Widget Attributes](https://api.vinieta.md/docs/widget/attributes): Every `data-` attribute with allowed values and notes.
- [Order Forms](https://api.vinieta.md/docs/widget/order-forms): The three vignette order widgets, country pre-selection, and post-order redirect.
- [View Order](https://api.vinieta.md/docs/widget/view-order): Render an existing order by id — status, documents, payment options.

## Authentication

- [Authentication](https://api.vinieta.md/docs/api/authentication): How to build the `X-Hmac-Signature` header (HMAC-SHA512 of the raw body, keyed with your partner secret), with JS, PHP, Python, and Postman signing examples. Read this first.

## Endpoints

- [Quickstart](https://api.vinieta.md/docs/api/quickstart): The canonical happy path worked end to end with `vignette:eu` — quote, draft, pay, poll, plus the full order lifecycle.
- [Get Offers](https://api.vinieta.md/docs/api/get-offers): `POST https://api.vinieta.md/v1/get-offers` — quote any of the 3 products; returns an `offers` array with `price` in MDL, `min_start_date`, and the category/validity ids to feed into create-order.
- [Create Order](https://api.vinieta.md/docs/api/create-order): `POST https://api.vinieta.md/v1/create-order` — send `customer` (`phone` required) plus a `products[]` array; returns `{ id, status: "draft", description, price, currency }`.
- [Confirm Order](https://api.vinieta.md/docs/api/confirm-order): `POST https://api.vinieta.md/v1/confirm-order` — send the order `id` and a `payment` object (`receipt_id`, `transaction_id`, `paid_at` ms unix, `amount`); only `draft` orders are confirmable; returns the order now in `paid` status.
- [Get Order](https://api.vinieta.md/docs/api/get-order): `POST https://api.vinieta.md/v1/get-order` — send `{ id }`; returns current `status`, and once `completed` a `products[]` array where each item carries the vignette `file` URL. Poll this to detect issuance.
- [Get Balance](https://api.vinieta.md/docs/api/wallet): `POST https://api.vinieta.md/v1/get-balance` — send `{}`; returns the partner's prepaid wallet: `{ balance, currency: "MDL", wallets, updated_at }` where `balance = wallets.online + wallets.promo` (wire-transfer top-ups land in `online`). Requires a wallet linked to the partner account (`403` otherwise).
- [Pay Order From Balance](https://api.vinieta.md/docs/api/wallet): `POST https://api.vinieta.md/v1/pay-order-from-balance` — send `{ id }`; pays a `draft` order ENTIRELY from ONE wallet (`promo` first, then `online`; no partial/cross-wallet cover) and returns the order in `paid` status, an alternative to confirm-order. `400 Insufficient balance` when no single wallet covers the price; transactionally safe to retry.

## Products

Pass the exact `product` string. All quote via get-offers, then create-order.

- [Vignette (MD)](https://api.vinieta.md/docs/api/get-offers): `product: "vignette:md"` — Moldova road vignette; needs `period` and `vehicle_category` (`M1`..`N3`). No vehicle certificate; ordered with `registration_number` + `identity_document`.
- [Vignette (RO)](https://api.vinieta.md/docs/api/get-offers): `product: "vignette:ro"` — Romania road vignette (rovinietă); priced from a `vehicle` certificate, returns multiple duration tiers with a `category`.
- [Vignette (EU)](https://api.vinieta.md/docs/api/get-offers): `product: "vignette:eu"` — multi-country EU vignette, priced in MDL. Send `country` + `validity` plus either a `vehicle` (MD certificate) or a `foreign_vehicle` payload for non-MD plates. Issuance is ASYNC: the order goes `draft` → `paid` → `processing` → `completed`, and the vignette `file` appears only at `completed` (typically within a minute — poll get-order or use the webhook).

## Webhooks

- [HTTPS Webhooks](https://api.vinieta.md/docs/api/webhooks): vinieta.md POSTs `{ orderId, status: "completed" }` to your registered HTTPS endpoint when an order completes. Verify the `X-Hmac-Signature` header exactly as for requests, reject anything unsigned, and respond `200 OK`. Delivery is a SINGLE attempt (no automatic retries) — treat the webhook as a fast signal and poll get-order as the source of truth. Register your URL by contacting vinieta.md.

## Optional

- [Complete machine spec (llms-full.txt)](https://api.vinieta.md/llms-full.txt): The entire API documentation inlined in one self-contained file — every endpoint, all 3 products' request/response schemas, field types, formats, and status codes. Fetch this when you need full depth without following links.
- [Docs site root](https://api.vinieta.md/docs): Human-readable documentation home — starts by choosing widget vs REST API.
- [IDNX validator](https://github.com/iAsig/idnx-validator): Reference validator for the IDNP/IDNO values used as `identity_document`.
- [Test Data](https://api.vinieta.md/docs/api/test-data): Certificate formats, test vehicles, and test IDNP/IDNO values for trying the API end-to-end.