openapi: 3.1.0 info: title: Pickup Point Service version: (dev) description: >- Merchant-facing pickup point lookup API. Authenticated merchant context is required; no additional scope. servers: - url: https://api-1.test.logitrail.com description: Test / Development Server - url: https://api-1.logitrail.com description: Production Server paths: /v1/pickup-points: get: summary: List pickup points description: >- Search pickup points by postal code, city, name (≥3 chars), carrier, or carrier+carrier_id. Country defaults to FI when a search parameter is provided. Returns the simple/merchant response shape. operationId: ListPickupPoints security: - idp: [] parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Matching pickup points (max 100). content: application/json: schema: type: array items: type: object properties: id: type: string name: type: string public_name: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false description: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false address: type: string postalcode: type: string city: type: string country: type: string coordinates: anyOf: - type: array prefixItems: - type: number - type: number - type: 'null' branch: type: string location_info: type: string type: type: string carrier_info: type: object propertyNames: type: string additionalProperties: type: object properties: id: type: string office: type: string type: type: string label_name: type: string servicepoint_id: type: string country_code: type: string required: - id additionalProperties: false required: - id - name - address - postalcode - city - country - coordinates - type - carrier_info additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false /v1/pickup-points/{id}: get: summary: Get a pickup point by id description: Returns a single pickup point in the simple/merchant response shape. operationId: GetPickupPoint security: - idp: [] parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Pickup point. content: application/json: schema: type: object properties: id: type: string name: type: string public_name: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false description: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false address: type: string postalcode: type: string city: type: string country: type: string coordinates: anyOf: - type: array prefixItems: - type: number - type: number - type: 'null' branch: type: string location_info: type: string type: type: string carrier_info: type: object propertyNames: type: string additionalProperties: type: object properties: id: type: string office: type: string type: type: string label_name: type: string servicepoint_id: type: string country_code: type: string required: - id additionalProperties: false required: - id - name - address - postalcode - city - country - coordinates - type - carrier_info additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false '404': description: Pickup point not found. content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /v1/pickup-points/by-carrier/{carrier}/{carrier_id}: get: summary: Get a pickup point by carrier code and carrier-specific id description: >- Singleton lookup of an active pickup point by carrier code and the carrier-specific ID (e.g. the nShift-ID for Posti). Returns the simple/merchant response shape. Merchant visibility rules apply; hidden pickup points return 404 to avoid leaking their existence. operationId: GetPickupPointByCarrier security: - idp: [] parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Matching active pickup point. content: application/json: schema: type: object properties: id: type: string name: type: string public_name: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false description: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false address: type: string postalcode: type: string city: type: string country: type: string coordinates: anyOf: - type: array prefixItems: - type: number - type: number - type: 'null' branch: type: string location_info: type: string type: type: string carrier_info: type: object propertyNames: type: string additionalProperties: type: object properties: id: type: string office: type: string type: type: string label_name: type: string servicepoint_id: type: string country_code: type: string required: - id additionalProperties: false required: - id - name - address - postalcode - city - country - coordinates - type - carrier_info additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false '404': description: >- No active pickup point matches the carrier/id, or it is hidden by merchant visibility. content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /v1/pickup-points/search-near: post: summary: Search pickup points near an address description: >- Find pickup points near a delivery address using geo-search. Applies an adaptive radius strategy: starts at `radius_km` (default 50 km) and expands to `expanded_radius_km` (default 100 km) when fewer than `min_results` (default 5) results are found. If geocoding fails or the geocoded location does not match the postal code area, a postcode-anchor fallback is used. Merchant visibility rules apply (include/exclude lists, carrier skip config). Returns the simple/merchant response shape. operationId: SearchPickupPointsNear security: - idp: [] parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. requestBody: content: application/json: schema: type: object properties: address: type: string minLength: 1 description: Street address line. postalcode: type: string minLength: 1 description: Postal code of the delivery address. city: type: string minLength: 1 description: City of the delivery address. country: description: ISO 3166-1 alpha-2 country code. Defaults to FI. type: string minLength: 2 maxLength: 2 radius_km: description: 'Initial search radius in km. Default: 50.' type: number exclusiveMinimum: 0 expanded_radius_km: description: >- Expanded search radius in km, used when the initial radius returns fewer than min_results. Default: 100. type: number exclusiveMinimum: 0 min_results: description: >- Minimum result count that triggers the expanded-radius pass. Default: 5. type: integer exclusiveMinimum: 0 maximum: 9007199254740991 max_results: description: 'Hard cap on returned results. Default: 50.' type: integer exclusiveMinimum: 0 maximum: 9007199254740991 carriers: description: >- Carrier codes to include. Defaults to all known carriers: fi_posti, fi_matkahuolto, fi_schenker, postnord, budbee. type: array items: type: string required: - address - postalcode - city additionalProperties: false responses: '200': description: Matching pickup points with search metadata. content: application/json: schema: type: object properties: pickup_points: type: array items: type: object properties: id: type: string name: type: string public_name: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false description: type: object properties: fi: type: string en: type: string sv: type: string required: - fi - en - sv additionalProperties: false address: type: string postalcode: type: string city: type: string country: type: string coordinates: anyOf: - type: array prefixItems: - type: number - type: number - type: 'null' branch: type: string location_info: type: string type: type: string carrier_info: type: object propertyNames: type: string additionalProperties: type: object properties: id: type: string office: type: string type: type: string label_name: type: string servicepoint_id: type: string country_code: type: string required: - id additionalProperties: false required: - id - name - address - postalcode - city - country - coordinates - type - carrier_info additionalProperties: false execution_details: type: object properties: used_expanded_radius: type: boolean used_fallback: type: boolean required: - used_expanded_radius - used_fallback additionalProperties: false required: - pickup_points - execution_details additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false /v1/pickup-points/stats/summary: get: summary: Pickup point stats summary description: Counts of active pickup points grouped by branch and by carrier. operationId: GetPickupPointStatsSummary security: - idp: [] parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Counts grouped by branch and carrier, plus total. content: application/json: schema: type: object properties: by_branch: type: object propertyNames: type: string additionalProperties: type: number by_carrier: type: object propertyNames: type: string additionalProperties: type: number total: type: number required: - by_branch - by_carrier - total additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false components: securitySchemes: idp: type: oauth2 flows: clientCredentials: tokenUrl: >- https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token scopes: {}