Creare comandă (Create Order)

Trimiteți o comandă nouă cu selecția produsului, detaliile de plată și informațiile clientului.

text

POST /orders

Corpul cererii

json

{
	"products": [
		{
			"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"productTypeId": 1,
			"quantity": 1,
			"vehiclePlate": "AB123CD",
			"vehicleCountryIsocode": "AT",
			"vehicleCategoryId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
			"startAt": "2026-04-01T00:00:00.000Z",
			"endAt": "2026-04-10T23:59:59.000Z",
			"driverFirstname": "John",
			"driverLastname": "Doe"
		}
	],
	"payment": {
		"type": "CARD",
		"paymentMethodId": "pm_1234567890abcdef",
		"returnUrl": "https://yourapp.com/payment/callback"
	},
	"customer": {
		"email": "john.doe@example.com",
		"firstName": "John",
		"lastName": "Doe",
		"phone": "+43123456789"
	},
	"address": {
		"countryIsocode": "AT",
		"city": "Vienna",
		"addressLine": "Mariahilfer Strasse 1",
		"postalCode": "1060",
		"taxNumber": "ATU12345678",
		"companyName": "Doe GmbH"
	},
	"idempotencyKey": "unique-order-key-12345",
	"externalReference": "YOUR-ORDER-REF-001",
	"callbackUrl": "https://yourapp.com/webhooks/vignetim"
}

DTO Produse

Câmp	Tip	Obligatoriu	Descriere
`productId`	UUID	Da	ID-ul produsului din catalog
`productTypeId`	integer	Da	Tipul produsului: `1` = VIGNETTE, `2` = ESIM, `3` = INSURANCE, `4` = FINE_PAYMENT
`quantity`	integer	Da	Numărul de unități
`vehiclePlate`	string	Condiționat	Numărul de înmatriculare al vehiculului (obligatoriu pentru VIGNETTE)
`vehicleCountryIsocode`	string	Condiționat	Țara de înmatriculare a vehiculului (obligatoriu pentru VIGNETTE)
`vehicleCategoryId`	UUID	Condiționat	Categoria vehiculului (obligatoriu pentru VIGNETTE)
`startAt`	ISO 8601	Condiționat	Data de început a valabilității (obligatoriu pentru VIGNETTE)
`endAt`	ISO 8601	Condiționat	Data de sfârșit a valabilității (obligatoriu pentru VIGNETTE)
`driverFirstname`	string	Nu	Prenumele șoferului
`driverLastname`	string	Nu	Numele de familie al șoferului

DTO Plată

Câmp	Tip	Obligatoriu	Descriere
`type`	string	Da	Unul din: `CARD`, `GOOGLE_PAY`, `APPLE_PAY`, `IDEAL`, `REVOLUT`, `BANCONTACT`
`paymentMethodId`	string	Condiționat	Token-ul metodei de plată Stripe (obligatoriu pentru `CARD`)
`returnUrl`	string	Condiționat	URL HTTPS pentru callback-ul de redirecționare 3DS (obligatoriu pentru `CARD`)

Rutarea plăților

Plățile CARD sunt rutate prin NestPay și pot necesita verificare 3D Secure.
GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT și BANCONTACT sunt rutate prin Stripe.

DTO Client

Câmp	Tip	Obligatoriu	Descriere
`email`	string	Da	Adresa de e-mail a clientului
`firstName`	string	Da	Prenumele clientului
`lastName`	string	Da	Numele de familie al clientului
`phone`	string	Nu	Numărul de telefon al clientului (se recomandă formatul E.164)

DTO Adresă

Câmp	Tip	Obligatoriu	Descriere
`countryIsocode`	string	Da	Codul ISO al țării
`city`	string	Da	Numele orașului
`addressLine`	string	Da	Adresa străzii
`postalCode`	string	Nu	Codul poștal
`taxNumber`	string	Nu	Numărul de identificare fiscală
`companyName`	string	Nu	Numele companiei (pentru clienți persoane juridice)

Câmpuri suplimentare

Câmp	Tip	Obligatoriu	Descriere
`idempotencyKey`	string	Nu	Cheie unică pentru prevenirea comenzilor duplicate. Aceeași cheie cu același payload returnează comanda originală (recomandat).
`externalReference`	string	Nu	Referința internă a comenzii dumneavoastră pentru urmărire
`callbackUrl`	string	Nu	URL pentru primirea actualizărilor de stare ale comenzii

Răspuns

201 Created

json

{
	"id": "ord-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"status": "PENDING",
	"redirectUrl": "https://pay.vignetim.com/3ds/verify/abc123",
	"clientSecret": "pi_1234567890_secret_abcdef",
	"products": [
		{
			"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"productTypeId": 1,
			"quantity": 1,
			"status": "PENDING"
		}
	],
	"total": {
		"amount": 11.5,
		"currency": "EUR"
	},
	"externalReference": "YOUR-ORDER-REF-001",
	"createdAt": "2026-03-20T14:30:00.000Z"
}

redirectUrl -- Prezent când este necesară verificarea 3D Secure (plăți CARD). Redirecționați clientul către acest URL.
clientSecret -- Prezent pentru plățile rutate prin Stripe. Utilizați-l cu Stripe.js pentru a confirma plata pe partea de client.

409 Conflict (Idempotent)

Dacă aceeași idempotencyKey este trimisă cu același payload, comanda originală este returnată cu codul de stare 409. Este sigur să reîncercați.

json

{
	"statusCode": 409,
	"message": "Order already exists for this idempotency key",
	"error": "Conflict"
}