Bestelling aanmaken (Create Order)

Dien een nieuwe bestelling in met productselectie, betalingsgegevens en klantinformatie.

POST /orders

Verzoeklichaam

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

Producten-DTO

Veld	Type	Verplicht	Beschrijving
`productId`	UUID	Ja	Het product-ID uit de catalogus
`productTypeId`	integer	Ja	Producttype: `1` = VIGNETTE, `2` = ESIM, `3` = INSURANCE, `4` = FINE_PAYMENT
`quantity`	integer	Ja	Aantal eenheden
`vehiclePlate`	string	Voorwaardelijk	Kenteken van het voertuig (verplicht voor VIGNETTE)
`vehicleCountryIsocode`	string	Voorwaardelijk	Registratieland van het voertuig (verplicht voor VIGNETTE)
`vehicleCategoryId`	UUID	Voorwaardelijk	Voertuigcategorie (verplicht voor VIGNETTE)
`startAt`	ISO 8601	Voorwaardelijk	Startdatum geldigheid (verplicht voor VIGNETTE)
`endAt`	ISO 8601	Voorwaardelijk	Einddatum geldigheid (verplicht voor VIGNETTE)
`driverFirstname`	string	Nee	Voornaam bestuurder
`driverLastname`	string	Nee	Achternaam bestuurder

Betaling-DTO

Veld	Type	Verplicht	Beschrijving
`type`	string	Ja	Een van: `CARD`, `GOOGLE_PAY`, `APPLE_PAY`, `IDEAL`, `REVOLUT`, `BANCONTACT`
`paymentMethodId`	string	Voorwaardelijk	Stripe-betaalmethode-token (verplicht voor `CARD`)
`returnUrl`	string	Voorwaardelijk	HTTPS-URL voor 3DS-omleidingscallback (verplicht voor `CARD`)

Betalingsroutering

CARD-betalingen worden gerouteerd via NestPay en vereisen mogelijk 3D Secure-verificatie.
GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT en BANCONTACT worden gerouteerd via Stripe.

Klant-DTO

Veld	Type	Verplicht	Beschrijving
`email`	string	Ja	E-mailadres van de klant
`firstName`	string	Ja	Voornaam van de klant
`lastName`	string	Ja	Achternaam van de klant
`phone`	string	Nee	Telefoonnummer van de klant (E.164-formaat aanbevolen)

Adres-DTO

Veld	Type	Verplicht	Beschrijving
`countryIsocode`	string	Ja	Land ISO-code
`city`	string	Ja	Plaatsnaam
`addressLine`	string	Ja	Straatnaam en huisnummer
`postalCode`	string	Nee	Postcode
`taxNumber`	string	Nee	Btw-nummer
`companyName`	string	Nee	Bedrijfsnaam (voor zakelijke klanten)

Aanvullende velden

Veld	Type	Verplicht	Beschrijving
`idempotencyKey`	string	Nee	Unieke sleutel om dubbele bestellingen te voorkomen. Dezelfde sleutel met dezelfde payload retourneert de oorspronkelijke bestelling (aanbevolen).
`externalReference`	string	Nee	Uw interne bestelreferentie voor tracking
`callbackUrl`	string	Nee	URL om bestelstatusupdates te ontvangen

Antwoord

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 -- Aanwezig wanneer 3D Secure-verificatie vereist is (CARD-betalingen). Leid de klant om naar deze URL.
clientSecret -- Aanwezig voor via Stripe gerouteerde betalingen. Gebruik dit met Stripe.js om de betaling aan de clientzijde te bevestigen.

409 Conflict (Idempotent)

Als dezelfde idempotencyKey met dezelfde payload wordt verzonden, wordt de oorspronkelijke bestelling geretourneerd met een 409-statuscode. Dit is veilig om opnieuw te proberen.

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