{"openapi":"3.0.0","paths":{"/v2/partners/products/tickets":{"get":{"operationId":"PartnerProductsController_listTickets_v2","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"default":50,"type":"number"}},{"name":"countryIsocode","required":false,"in":"query","description":"Filter by country ISO code","schema":{"example":"AT","type":"string"}},{"name":"vehicleCategoryId","required":false,"in":"query","description":"Filter by vehicle category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Tickets with partner-effective pricing. Country restrictions are applied after pagination: metadata.total still counts blocked rows and metadata.filtered reports rows dropped from the current page.","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerTicketResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Auth failure, or code PRODUCT_NOT_AVAILABLE when vignettes are disabled for this organization"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List all available vignette tickets","tags":["Partner API - Products"]}},"/v2/partners/products/tickets/{id}":{"get":{"operationId":"PartnerProductsController_getTicket_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Ticket ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerTicketResponseDto"}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Auth failure, code PRODUCT_NOT_AVAILABLE when vignettes are disabled, or COUNTRY_NOT_AVAILABLE for a blocked country"},"404":{"description":"Ticket not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get ticket details by ID","tags":["Partner API - Products"]}},"/v2/partners/products/esim":{"get":{"operationId":"PartnerProductsController_listEsimPackages_v2","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"default":50,"type":"number"}},{"name":"country","required":false,"in":"query","description":"Filter by country ISO code","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by provider slug","schema":{"type":"string"}}],"responses":{"200":{"description":"eSIM packages with partner-effective pricing. Country restrictions are applied after pagination: metadata.total still counts blocked rows and metadata.filtered reports rows dropped from the current page.","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerEsimPackageResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Auth failure, code PRODUCT_NOT_AVAILABLE when eSIM is disabled, or COUNTRY_NOT_AVAILABLE when ?country is blocked"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List all available eSIM packages","tags":["Partner API - Products"]}},"/v2/partners/products/insurance":{"get":{"operationId":"PartnerProductsController_listInsuranceProducts_v2","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerInsuranceProductResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Auth failure, or code PRODUCT_NOT_AVAILABLE when insurance is disabled for this organization"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List all available insurance products","tags":["Partner API - Products"]}},"/v2/partners/products/insurance/{slug}":{"get":{"operationId":"PartnerProductsController_getInsuranceProduct_v2","parameters":[{"name":"slug","required":true,"in":"path","description":"Insurance product slug","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PartnerInsuranceProductResponseDto"},"metadata":{"type":"object","additionalProperties":true}},"required":["data","metadata"]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Insurance product not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get insurance product by slug","tags":["Partner API - Products"]}},"/v2/partners/products/vehicle-categories":{"get":{"operationId":"PartnerProductsController_listVehicleCategories_v2","parameters":[{"name":"language","required":false,"in":"query","description":"Language code","schema":{"example":"en","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerVehicleCategoryResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key"},"403":{"description":"IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List all vehicle categories","tags":["Partner API - Products"]}},"/v2/partners/products/vehicle-categories/by-type/{typeId}":{"get":{"operationId":"PartnerProductsController_listVehicleCategoriesByType_v2","parameters":[{"name":"typeId","required":true,"in":"path","description":"Vehicle type ID","schema":{"$ref":"#/components/schemas/VehicleType"}},{"name":"language","required":false,"in":"query","description":"Language code","schema":{"example":"en","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerVehicleCategoryResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key"},"403":{"description":"IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List vehicle categories by vehicle type","tags":["Partner API - Products"]}},"/v2/partners/products/geo/checkpoints":{"get":{"operationId":"PartnerProductsController_listGeoCheckpoints_v2","parameters":[{"name":"country","required":false,"in":"query","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["VIGNETTE_BORDER","TOLL_BOOTH","ESIM_REQUIREMENT","INSURANCE_REQUIREMENT","INFO_POINT"]}},{"name":"minLat","required":false,"in":"query","schema":{"type":"number"}},{"name":"maxLat","required":false,"in":"query","schema":{"type":"number"}},{"name":"minLng","required":false,"in":"query","schema":{"type":"number"}},{"name":"maxLng","required":false,"in":"query","schema":{"type":"number"}},{"name":"lang","required":false,"in":"query","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"categoryKey","required":false,"in":"query","description":"geo_categories.key, e.g. vignette_border","schema":{"type":"string"}},{"name":"confidence","required":false,"in":"query","schema":{"type":"string","enum":["high","medium","review"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerGeoCheckpointResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key"},"403":{"description":"IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List all geo checkpoints along routes","tags":["Partner API - Products"]}},"/v2/partners/orders":{"post":{"operationId":"PartnerOrdersController_createOrder_v2","parameters":[{"name":"x-timestamp","in":"header","description":"Request timestamp used in the HMAC signature","required":true,"schema":{"type":"string"}},{"name":"x-nonce","in":"header","description":"Single-use nonce; replays are rejected","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"HMAC-SHA256 signature over method, path, timestamp, nonce and body","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCreateOrderDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCreateOrderResponseDto"}}}},"400":{"description":"Validation error, unknown body fields, missing savedCardId for saved_card, or daily order limit exceeded"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Saved card not found for this organization"},"409":{"description":"A request with this idempotency key is already in flight"},"422":{"description":"Insufficient prepaid wallet balance (wallet payments only)","content":{"application/json":{"schema":{"properties":{"statusCode":{"type":"number","example":422},"code":{"type":"string","example":"INSUFFICIENT_WALLET_BALANCE"},"message":{"type":"string"},"balanceMinor":{"type":"string","description":"Current balance in minor units"},"requiredMinor":{"type":"string","description":"Required amount in minor units"}}}}}},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]},{"partner-api-key":[]}],"summary":"Create a new order with payment","tags":["Partner API - Orders"]},"get":{"operationId":"PartnerOrdersController_listOrders_v2","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by order product status","schema":{"type":"number"}},{"name":"productType","required":false,"in":"query","description":"Filter by product type","schema":{"type":"number","enum":[0,1,2,3,4,5,6,7,8,9]}},{"name":"dateFrom","required":false,"in":"query","description":"Filter by date from (ISO 8601)","schema":{"type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Filter by date to (ISO 8601)","schema":{"type":"string"}},{"name":"externalReference","required":false,"in":"query","description":"Filter by external reference","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"400":{"description":"Invalid or unknown query parameters"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List partner orders (organization-scoped)","tags":["Partner API - Orders"]}},"/v2/partners/orders/{id}":{"get":{"operationId":"PartnerOrdersController_getOrder_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrderResponseDto"}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Order not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get order details by ID","tags":["Partner API - Orders"]}},"/v2/partners/orders/{id}/documents":{"get":{"operationId":"PartnerOrdersController_getOrderDocuments_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrderDocumentsResponseDto"}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Order not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get customer-facing order documents with short-lived download URLs","tags":["Partner API - Orders"]}},"/v2/partners/orders/{id}/status":{"get":{"operationId":"PartnerOrdersController_getOrderStatus_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregated order status plus per-product statuses","content":{"application/json":{"schema":{"properties":{"orderId":{"type":"string"},"status":{"type":"number","nullable":true,"description":"Aggregated OrderStatus"},"statusLabel":{"type":"string","nullable":true,"example":"COMPLETED"},"productStatuses":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"productTypeId":{"type":"number"},"status":{"type":"number"},"statusLabel":{"type":"string","nullable":true}}}},"externalReference":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Order not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get order status","tags":["Partner API - Orders"]}},"/v2/partners/webhooks":{"post":{"operationId":"PartnerWebhooksController_createWebhook_v2","parameters":[{"name":"x-timestamp","in":"header","description":"Request timestamp used in the HMAC signature","required":true,"schema":{"type":"string"}},{"name":"x-nonce","in":"header","description":"Single-use nonce; replays are rejected","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"HMAC-SHA256 signature over method, path, timestamp, nonce and body","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartnerWebhookDto"}}}},"responses":{"201":{"description":"Created webhook; signingSecret is returned only once","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PartnerWebhookResponseDto"},{"properties":{"signingSecret":{"type":"string","description":"HMAC secret for verifying deliveries; shown only at creation"}}}]}}}},"400":{"description":"Validation error, webhook limit reached, or webhook URL failed SSRF checks"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]},{"partner-api-key":[]}],"summary":"Register a webhook URL","tags":["Partner API - Webhooks"]},"get":{"operationId":"PartnerWebhooksController_listWebhooks_v2","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerWebhookResponseDto"}},"metadata":{"type":"object","description":"Pagination and context metadata","additionalProperties":true}},"required":["data","metadata"]}}}},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"List registered webhooks","tags":["Partner API - Webhooks"]}},"/v2/partners/webhooks/{id}":{"put":{"operationId":"PartnerWebhooksController_updateWebhook_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Request timestamp used in the HMAC signature","required":true,"schema":{"type":"string"}},{"name":"x-nonce","in":"header","description":"Single-use nonce; replays are rejected","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"HMAC-SHA256 signature over method, path, timestamp, nonce and body","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePartnerWebhookDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhookResponseDto"}}}},"400":{"description":"Invalid UUID, validation error, or webhook URL failed SSRF checks"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Webhook not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]},{"partner-api-key":[]}],"summary":"Update a webhook","tags":["Partner API - Webhooks"]},"delete":{"operationId":"PartnerWebhooksController_deleteWebhook_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Request timestamp used in the HMAC signature","required":true,"schema":{"type":"string"}},{"name":"x-nonce","in":"header","description":"Single-use nonce; replays are rejected","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"HMAC-SHA256 signature over method, path, timestamp, nonce and body","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Webhook not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]},{"partner-api-key":[]}],"summary":"Delete a webhook","tags":["Partner API - Webhooks"]}},"/v2/partners/webhooks/{id}/test":{"post":{"operationId":"PartnerWebhooksController_testWebhook_v2","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}},{"name":"x-timestamp","in":"header","description":"Request timestamp used in the HMAC signature","required":true,"schema":{"type":"string"}},{"name":"x-nonce","in":"header","description":"Single-use nonce; replays are rejected","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","description":"HMAC-SHA256 signature over method, path, timestamp, nonce and body","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Delivery attempt result","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"statusCode":{"type":"number","nullable":true},"error":{"type":"string","nullable":true}}}}}},"400":{"description":"Invalid UUID"},"401":{"description":"Missing or invalid API key, or missing HMAC headers on signed endpoints"},"403":{"description":"Invalid signature, nonce replay, IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"404":{"description":"Webhook not found"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]},{"partner-api-key":[]}],"summary":"Send a test webhook event","tags":["Partner API - Webhooks"]}},"/v2/partners/wallet":{"get":{"operationId":"PartnerWalletController_getBalance_v2","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWalletBalanceResponseDto"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"IP/endpoint not allowlisted or organization inactive; body is a generic 'Authentication failed'"},"429":{"description":"Rate limit exceeded; body includes retryAfter (seconds)"}},"security":[{"partner-api-key":[]}],"summary":"Get prepaid wallet balance","tags":["Partner API - Wallet"]}},"/v2/partners/admin/card-attempts":{"get":{"operationId":"PartnerCardAttemptsAdminController_list_v2","parameters":[{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PartnerHgsCardAttemptStatus"}},{"name":"olderThanMinutes","required":false,"in":"query","schema":{"minimum":0,"maximum":43200,"default":60,"type":"number"}},{"name":"organizationId","required":false,"in":"query","description":"Filter by the counter organization","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCardAttemptListDto"}}}}},"security":[{"bearer":[]}],"summary":"List counter card top-up attempts stuck in a given status","tags":["Partner API - Admin"]}},"/v2/partners/admin/card-attempts/{id}/resolve":{"post":{"operationId":"PartnerCardAttemptsAdminController_resolve_v2","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePartnerCardAttemptDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCardAttemptDto"}}}},"404":{"description":"Card attempt not found"},"409":{"description":"Attempt is not in the started status"}},"security":[{"bearer":[]}],"summary":"Close a stuck attempt as failed (records the ops note; never charges or refunds)","tags":["Partner API - Admin"]}}},"info":{"title":"Vignetim Partner API","description":"REST API for partners to sell e-vignettes, eSIM data packages, and travel insurance.\n\n## Authentication\nEvery request must include your organization API key:\n```\nx-api-key: {your_api_key}\n```\nMutation endpoints (order creation, webhook management) additionally require HMAC-SHA256 request signing via the `x-timestamp`, `x-nonce`, and `x-signature` headers.","version":"1.0.0","contact":{"name":"Vignetim Support","url":"https://vignetim.com","email":"partners@vignetim.com"}},"tags":[{"name":"Partner API - Products","description":"Partner product listing endpoints (vignettes, eSIM, insurance)"},{"name":"Partner API - Orders","description":"Partner order management endpoints"},{"name":"Partner API - Webhooks","description":"Partner webhook configuration endpoints"},{"name":"Partner API - Wallet","description":"Partner wallet balance endpoints"}],"servers":[{"url":"https://api.vignetim.com","description":"Production"}],"components":{"securitySchemes":{"partner-api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Partner API Key (HMAC-SHA256 signed mutations)"}},"schemas":{"PartnerTicketResponseDto":{"type":"object","properties":{"id":{"type":"string"},"countryIsocode":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"displayName":{"type":"object"},"typeId":{"type":"number"},"ticketCategoryId":{"type":"number"},"validDurationId":{"type":"number"},"vehicleTypeId":{"type":"number"},"vehicleCategoryId":{"type":"string"},"endDateRuleId":{"type":"number"},"price":{"type":"number","description":"Customer-facing price"},"ticketConditionsId":{"type":"number"},"imageUrls":{"type":"object"}},"required":["id","countryIsocode","name","description","displayName","typeId","ticketCategoryId","validDurationId","vehicleTypeId","endDateRuleId","price","ticketConditionsId"]},"PartnerEsimPackageResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"planType":{"type":"string"},"dataLabel":{"type":"string"},"day":{"type":"number"},"price":{"type":"number","description":"Customer-facing price"},"imageUrl":{"type":"string"}},"required":["id","slug","planType","dataLabel","day","price"]},"PartnerInsuranceProductResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isActive":{"type":"boolean"},"displayOrder":{"type":"number"},"iconUrl":{"type":"string"},"metadata":{"type":"object","description":"Product configuration (required fields, durations, currencies)"}},"required":["id","slug","name","isActive","displayOrder"]},"PartnerVehicleCategoryResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"localizedName":{"type":"string","description":"Localized name when a language is requested"},"categoryTypeId":{"type":"number"},"vehicleCategoryExplanations":{"type":"number"},"typeId":{"type":"number"},"parentVehicleTypeId":{"type":"number"},"lengthTypeId":{"type":"number"},"weightTypeId":{"type":"number"},"heightTypeId":{"type":"number"},"emissionClassId":{"type":"number"},"axlesTypeId":{"type":"number"},"seatTypeId":{"type":"number"},"wheelbaseTypeId":{"type":"number"},"iconTypeId":{"type":"number"},"withTrailer":{"type":"boolean"}},"required":["id","name","categoryTypeId","vehicleCategoryExplanations","typeId","parentVehicleTypeId","lengthTypeId","weightTypeId","heightTypeId","emissionClassId","axlesTypeId","seatTypeId","wheelbaseTypeId","iconTypeId","withTrailer"]},"VehicleType":{"type":"number","enum":[0,1,2,3,4,5,6,7,8,9,10,11]},"PartnerGeoCheckpointResponseDto":{"type":"object","properties":{"id":{"type":"string"},"countryIsocode":{"type":"string"},"type":{"type":"string","description":"Checkpoint type discriminator"},"latitude":{"type":"number"},"longitude":{"type":"number"},"title":{"type":"object","description":"Localized title map"},"description":{"type":"object","description":"Localized description map"},"infoText":{"type":"object","description":"Localized info text map"},"iconType":{"type":"string"},"color":{"type":"string"},"productType":{"type":"string"},"sortOrder":{"type":"number"},"ticketIds":{"description":"IDs of tickets sold for this checkpoint","type":"array","items":{"type":"string"}}},"required":["id","countryIsocode","latitude","longitude","title","description","sortOrder"]},"PartnerOrderProductDto":{"type":"object","properties":{"productId":{"type":"string","description":"Product ID (ticket ID, eSIM package ID, or insurance product slug)"},"productTypeId":{"type":"number","description":"Product type: 1 = ticket, 2 = eSIM, 4 = insurance, 5 = fines","enum":[1,2,4,5]},"quantity":{"type":"number","description":"Quantity","default":1},"vehiclePlate":{"type":"string","description":"Vehicle license plate (for vignettes)"},"vehicleCountryIsocode":{"type":"string","description":"Vehicle country ISO code (for vignettes)"},"vehicleCategoryId":{"type":"string","description":"Vehicle category ID (for vignettes)"},"vehicleVin":{"type":"string","description":"Vehicle identification number (for vignettes)"},"startAt":{"type":"string","description":"Start date (ISO 8601)"},"endAt":{"type":"string","description":"End date (ISO 8601)"},"driverFirstname":{"type":"string","description":"Driver first name (required by some countries)"},"driverLastname":{"type":"string","description":"Driver last name (required by some countries)"}},"required":["productId","productTypeId","quantity"]},"PartnerPaymentDto":{"type":"object","properties":{"method":{"type":"string","description":"Payment method","enum":["saved_card","wallet"]},"savedCardId":{"type":"string","description":"Vaulted card ID (required when method is saved_card)"},"returnUrl":{"type":"string","description":"Return URL after payment"}},"required":["method"]},"PartnerCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number"}},"required":["email","firstName","lastName"]},"PartnerAddressDto":{"type":"object","properties":{"countryIsocode":{"type":"string","description":"Country ISO code","example":"NL"},"city":{"type":"string","description":"City"},"addressLine":{"type":"string","description":"Address line"},"postalCode":{"type":"string","description":"Postal code"},"taxNumber":{"type":"string","description":"Tax/VAT number (for B2B invoicing)"},"companyName":{"type":"string","description":"Company name (for B2B invoicing)"}},"required":["countryIsocode","city","addressLine"]},"PartnerCreateOrderDto":{"type":"object","properties":{"products":{"description":"Order products (1-50 items)","type":"array","items":{"$ref":"#/components/schemas/PartnerOrderProductDto"}},"payment":{"description":"Payment details (tokenized - no raw card data)","allOf":[{"$ref":"#/components/schemas/PartnerPaymentDto"}]},"customer":{"description":"Customer details (required unless customerLinkId is set)","allOf":[{"$ref":"#/components/schemas/PartnerCustomerDto"}]},"customerLinkId":{"type":"string","description":"Stored customer link ID (mutually exclusive with inline customer details)"},"address":{"description":"Billing address","allOf":[{"$ref":"#/components/schemas/PartnerAddressDto"}]},"idempotencyKey":{"type":"string","description":"Idempotency key to prevent duplicate orders (recommended)"},"externalReference":{"type":"string","description":"Partner external reference (your own order ID)"},"callbackUrl":{"type":"string","description":"Callback URL for order status updates (HTTPS only)"}},"required":["products","payment","address"]},"PartnerCreateOrderResponseDto":{"type":"object","properties":{"transactionId":{"type":"string","description":"Payment transaction ID"},"status":{"type":"string","description":"Payment status, e.g. 'COMPLETED', 'FAILED', 'PENDING_3D'"},"statusLabel":{"type":"string","description":"Same as status; human-readable payment status"},"orderId":{"type":"string","description":"Created order ID (sandbox only today)"},"redirectUrl":{"type":"string","description":"Redirect URL for redirect-based payments"},"sandbox":{"type":"boolean","description":"True when created with a TEST key"}},"required":["transactionId","status","statusLabel"]},"PartnerOrderProductVehicleDto":{"type":"object","properties":{"plate":{"type":"string"},"countryIsocode":{"type":"string"},"categoryId":{"type":"string"}}},"PartnerOrderProductResponseDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"number","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"statusLabel":{"type":"string","nullable":true,"description":"OrderStatus enum key, e.g. 'COMPLETED'"},"productId":{"type":"string"},"productTypeId":{"type":"number","enum":[0,1,2,3,4,5,6,7,8,9]},"price":{"type":"number","description":"Customer-facing price"},"vehicle":{"$ref":"#/components/schemas/PartnerOrderProductVehicleDto"},"startAt":{"type":"string","description":"Validity start (ISO 8601)"},"endAt":{"type":"string","description":"Validity end (ISO 8601)"}},"required":["id","status","statusLabel","productId","productTypeId","price"]},"PartnerOrderResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Order ID"},"orderNumber":{"type":"string","description":"Human-readable order number"},"status":{"type":"number","description":"Aggregated order status","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"statusLabel":{"type":"string","nullable":true,"description":"OrderStatus enum key for the aggregated status, e.g. 'COMPLETED'"},"totalAmount":{"type":"number"},"discountAmount":{"type":"number"},"taxAmount":{"type":"number"},"currency":{"type":"string","description":"Currency code"},"externalReference":{"type":"string","description":"External reference provided by partner"},"products":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderProductResponseDto"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","statusLabel","totalAmount","discountAmount","taxAmount","currency","products","createdAt","updatedAt"]},"PartnerOrderDocumentDto":{"type":"object","properties":{"type":{"type":"string","description":"File type enum name","example":"CONFIRMATION_PDF"},"typeId":{"type":"number","description":"Numeric file type","example":1},"orderProductId":{"type":"string","description":"Order product the document belongs to"},"filename":{"type":"string","description":"File name derived from the storage key"},"url":{"type":"string","description":"Short-lived presigned download URL"},"expiresAt":{"type":"string","description":"Expiry of the presigned URL","format":"date-time"}},"required":["type","typeId","orderProductId","url","expiresAt"]},"PartnerOrderEsimDto":{"type":"object","properties":{"orderProductId":{"type":"string"},"iccid":{"type":"string","description":"SIM ICCID once provisioned"},"providerOrderId":{"type":"string","description":"Provider order identifier"}},"required":["orderProductId"]},"PartnerOrderDocumentsResponseDto":{"type":"object","properties":{"orderId":{"type":"string"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderDocumentDto"}},"esim":{"description":"eSIM identifiers for eSIM line items (empty for other products)","type":"array","items":{"$ref":"#/components/schemas/PartnerOrderEsimDto"}}},"required":["orderId","documents","esim"]},"PartnerWebhookResponseDto":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":"string"},"lastDeliveredAt":{"type":"string"},"failureCount":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","url","events","active","failureCount","createdAt"]},"CreatePartnerWebhookDto":{"type":"object","properties":{"url":{"type":"string","description":"Webhook URL (must be HTTPS)","example":"https://partner.com/webhooks/vignetim"},"events":{"type":"array","description":"Events to subscribe to","example":["order.completed","order.failed"],"items":{"type":"string","enum":["order.completed","order.fulfilled","order.failed","order.refunded","order.cancelled","*"]}},"description":{"type":"string","description":"Description for this webhook"}},"required":["url","events"]},"UpdatePartnerWebhookDto":{"type":"object","properties":{"url":{"type":"string","description":"Webhook URL (must be HTTPS)"},"events":{"description":"Events to subscribe to","type":"array","items":{"type":"string"}},"active":{"type":"boolean","description":"Enable or disable the webhook"},"description":{"type":"string","description":"Description"}}},"PartnerWalletBalanceDto":{"type":"object","properties":{"currency":{"type":"string","example":"TRY"},"balanceMinor":{"type":"string","description":"Wallet balance in minor units"},"balance":{"type":"number","description":"Wallet balance in major units"}},"required":["currency","balanceMinor","balance"]},"PartnerWalletBalanceResponseDto":{"type":"object","properties":{"currency":{"type":"string","example":"EUR"},"balanceMinor":{"type":"string","description":"Wallet balance in minor units"},"balance":{"type":"number","description":"Wallet balance in major units"},"balances":{"description":"One entry per wallet currency","type":"array","items":{"$ref":"#/components/schemas/PartnerWalletBalanceDto"}}},"required":["currency","balanceMinor","balance","balances"]},"PartnerHgsCardAttemptStatus":{"type":"string","enum":["started","processing","failed"]},"PartnerCardAttemptDto":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"organizationName":{"type":"object","nullable":true},"productNo":{"type":"string"},"idempotencyKey":{"type":"string"},"amountMinor":{"type":"string","description":"Requested TRY minor amount"},"intentId":{"type":"object","nullable":true},"transactionId":{"type":"object","nullable":true},"status":{"allOf":[{"$ref":"#/components/schemas/PartnerHgsCardAttemptStatus"}]},"errorCode":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","organizationId","organizationName","productNo","idempotencyKey","amountMinor","intentId","transactionId","status","errorCode","createdAt","updatedAt"]},"PartnerCardAttemptListDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PartnerCardAttemptDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"}},"required":["items","total","page","limit"]},"ResolvePartnerCardAttemptDto":{"type":"object","properties":{"note":{"type":"string","maxLength":500,"description":"Ops note recorded on the attempt and audit log"}},"required":["note"]}}}}