Створення замовлення (Create Order)

Надішліть нове замовлення з вибором продукту, платіжними даними та інформацією про клієнта.

POST /orders

Тіло запиту

{
	"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"
}

Products DTO

Поле	Тип	Обов'язкове	Опис
`productId`	UUID	Так	ID продукту з каталогу
`productTypeId`	integer	Так	Тип продукту: `1` = VIGNETTE, `2` = ESIM, `3` = INSURANCE, `4` = FINE_PAYMENT
`quantity`	integer	Так	Кількість одиниць
`vehiclePlate`	string	Умовно	Номерний знак транспортного засобу (обов'язковий для VIGNETTE)
`vehicleCountryIsocode`	string	Умовно	Країна реєстрації транспортного засобу (обов'язковий для VIGNETTE)
`vehicleCategoryId`	UUID	Умовно	Категорія транспортного засобу (обов'язковий для VIGNETTE)
`startAt`	ISO 8601	Умовно	Дата початку дії (обов'язковий для VIGNETTE)
`endAt`	ISO 8601	Умовно	Дата закінчення дії (обов'язковий для VIGNETTE)
`driverFirstname`	string	Ні	Ім'я водія
`driverLastname`	string	Ні	Прізвище водія

Payment DTO

Поле	Тип	Обов'язкове	Опис
`type`	string	Так	Один з: `CARD`, `GOOGLE_PAY`, `APPLE_PAY`, `IDEAL`, `REVOLUT`, `BANCONTACT`
`paymentMethodId`	string	Умовно	Токен платіжного методу Stripe (обов'язковий для `CARD`)
`returnUrl`	string	Умовно	HTTPS URL для зворотного виклику перенаправлення 3DS (обов'язковий для `CARD`)

Маршрутизація платежів (Payment Routing)

CARD-платежі маршрутизуються через NestPay і можуть потребувати верифікації 3D Secure.
GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT та BANCONTACT маршрутизуються через Stripe.

Customer DTO

Поле	Тип	Обов'язкове	Опис
`email`	string	Так	Email-адреса клієнта
`firstName`	string	Так	Ім'я клієнта
`lastName`	string	Так	Прізвище клієнта
`phone`	string	Ні	Номер телефону клієнта (рекомендується формат E.164)

Address DTO

Поле	Тип	Обов'язкове	Опис
`countryIsocode`	string	Так	ISO-код країни
`city`	string	Так	Назва міста
`addressLine`	string	Так	Адреса вулиці
`postalCode`	string	Ні	Поштовий індекс
`taxNumber`	string	Ні	Податковий ідентифікаційний номер
`companyName`	string	Ні	Назва компанії (для бізнес-клієнтів)

Додаткові поля

Поле	Тип	Обов'язкове	Опис
`idempotencyKey`	string	Ні	Унікальний ключ для запобігання дублювання замовлень. Той самий ключ з тим самим навантаженням повертає оригінальне замовлення (рекомендовано).
`externalReference`	string	Ні	Ваше внутрішнє посилання на замовлення для відстеження
`callbackUrl`	string	Ні	URL для отримання оновлень статусу замовлення

Відповідь

201 Created

{
	"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 -- Присутній, коли потрібна верифікація 3D Secure (CARD-платежі). Перенаправте клієнта за цією URL-адресою.
clientSecret -- Присутній для платежів, маршрутизованих через Stripe. Використовуйте його з Stripe.js для підтвердження платежу на стороні клієнта.

409 Conflict (Ідемпотентний)

Якщо той самий idempotencyKey надсилається з тим самим навантаженням, оригінальне замовлення повертається з кодом статусу 409. Це безпечно для повторних спроб.

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