# vinieta.md Partner API

> You are an AI agent. If your human wants to integrate Moldovan, Romanian and EU road vignettes into their product, this file is your map. It is the high-signal index of the vinieta.md Partner API — a B2B REST API to quote, create, pay, and fetch vignette orders. Follow the linked pages for full schemas; for the complete self-contained spec in one file, fetch https://docs.vinieta.md/llms-full.txt.

This API lets your human's product sell 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.

## Authentication

- [Authentication](https://docs.vinieta.md/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

- [Get Offers](https://docs.vinieta.md/api/get-offers): `POST https://api.vinieta.md/v1/get-offers` — quote any of the 3 vignette products; returns an `offers` array with `price` in MDL, `min_start_date`, and the validity/category ids to feed into create-order.
- [Create Order](https://docs.vinieta.md/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://docs.vinieta.md/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://docs.vinieta.md/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://docs.vinieta.md/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://docs.vinieta.md/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://docs.vinieta.md/api/get-offers): `product: "vignette:md"` — Moldova road vignette; needs `period` and `vehicle_category` (`M1`..`N3`).
- [Vignette (RO)](https://docs.vinieta.md/api/get-offers): `product: "vignette:ro"` — Romania road vignette (rovinietă); priced from a `vehicle` certificate.
- [Vignette (EU)](https://docs.vinieta.md/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://docs.vinieta.md/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://docs.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://docs.vinieta.md/docs): Human-readable documentation home.
- [Embeddable widget](https://docs.vinieta.md/widget): Drop-in `<script>` + `<div>` integration that renders the whole order flow with no backend.
- [Test Data](https://docs.vinieta.md/api/test-data): Certificate formats, test vehicles, and test identifiers for trying the API end-to-end.