Crear pedido

Envíe un nuevo pedido (order) con selección de productos, datos de pago e información del cliente.

POST /orders

Cuerpo de la solicitud

{
	"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 de productos

Campo	Tipo	Requerido	Descripción
`productId`	UUID	Sí	El ID del producto del catálogo
`productTypeId`	integer	Sí	Tipo de producto: `1` = VIGNETTE, `2` = ESIM, `3` = INSURANCE, `4` = FINE_PAYMENT
`quantity`	integer	Sí	Número de unidades
`vehiclePlate`	string	Condicional	Matrícula del vehículo (requerido para VIGNETTE)
`vehicleCountryIsocode`	string	Condicional	País de registro del vehículo (requerido para VIGNETTE)
`vehicleCategoryId`	UUID	Condicional	Categoría del vehículo (requerido para VIGNETTE)
`startAt`	ISO 8601	Condicional	Fecha de inicio de validez (requerido para VIGNETTE)
`endAt`	ISO 8601	Condicional	Fecha de fin de validez (requerido para VIGNETTE)
`driverFirstname`	string	No	Nombre del conductor
`driverLastname`	string	No	Apellido del conductor

DTO de pago

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	Uno de: `CARD`, `GOOGLE_PAY`, `APPLE_PAY`, `IDEAL`, `REVOLUT`, `BANCONTACT`
`paymentMethodId`	string	Condicional	Token de método de pago de Stripe (requerido para `CARD`)
`returnUrl`	string	Condicional	URL HTTPS para el callback de redirección 3DS (requerido para `CARD`)

Enrutamiento de pagos

Los pagos con CARD se enrutan a través de NestPay y pueden requerir verificación 3D Secure.
GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT y BANCONTACT se enrutan a través de Stripe.

DTO de cliente

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de correo electrónico del cliente
`firstName`	string	Sí	Nombre del cliente
`lastName`	string	Sí	Apellido del cliente
`phone`	string	No	Número de teléfono del cliente (se recomienda formato E.164)

DTO de dirección

Campo	Tipo	Requerido	Descripción
`countryIsocode`	string	Sí	Código ISO del país
`city`	string	Sí	Nombre de la ciudad
`addressLine`	string	Sí	Dirección
`postalCode`	string	No	Código postal
`taxNumber`	string	No	Número de identificación fiscal
`companyName`	string	No	Nombre de la empresa (para clientes comerciales)

Campos adicionales

Campo	Tipo	Requerido	Descripción
`idempotencyKey`	string	No	Clave única para prevenir pedidos duplicados. La misma clave con la misma carga útil devuelve el pedido original (recomendado).
`externalReference`	string	No	Su referencia interna de pedido para seguimiento
`callbackUrl`	string	No	URL para recibir actualizaciones de estado del pedido

Respuesta

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 -- Presente cuando se requiere verificación 3D Secure (pagos con CARD). Redirija al cliente a esta URL.
clientSecret -- Presente para pagos enrutados a través de Stripe. Use esto con Stripe.js para confirmar el pago en el lado del cliente.

409 Conflict (Idempotente)

Si se envía la misma idempotencyKey con la misma carga útil, se devuelve el pedido original con un código de estado 409. Es seguro reintentar.

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