openapi: 3.1.0 info: title: POSnavigator PresetFilters API version: "1.0.0" description: |- Reusable offer-search presets that drive the wizard, homepage hero, Arena, promotions, and industry landings. The filters field is a URL query string, NOT JSON, using the same keys as POST /api/v1/offers (s_channels, s_servicetypes, s_income, sortBy, ...). Example: s_channels=&s_income=1000000&sortBy=sumprice. Requires presetfilter:read on GET and presetfilter:write on POST/PATCH/DELETE. Older keys may lack these scopes — create a new key. Unique slug when isLanding. # The happy path 1. GET /openapi/presetfilters.yaml 2. GET /api/v1/presetfilters?showInHeroEntry=true 3. POST with translations, filters query string, and at least one channel id 4. PATCH flags (showOnHomepage, agentEnabled, isArena) without rebuilding filters unless the search itself changed Send `X-Api-Key: ` on every operation except this document itself. Create a key at /user/api-keys. Format: `pn_` plus a random string. Copy it immediately; it is shown once. Default new keys include blog, legal, presetfilter, versus-landing, widget, agent-analytics and hero-analytics scopes. Missing scopes return 403 INSUFFICIENT_PERMISSIONS. Bank-scoped resources also require the key owner to be admin or listed on that bank; otherwise 403 FORBIDDEN. # Response envelope Success: `{ "success": true, "data": ... }`. Failure: `{ "success": false, "error": { "code", "message" } }`. Branch on error.code, never on error.message. # Error codes | code | status | what to do | | --- | --- | --- | | MISSING_API_KEY | 401 | add X-Api-Key; do not retry blindly | | INVALID_API_KEY | 401 | stop; ask a human for a new key | | INSUFFICIENT_PERMISSIONS | 403 | stop; this key lacks a required scope | | FORBIDDEN | 403 | stop or switch to a key with bank/admin access | | RATE_LIMIT_EXCEEDED | 429 | wait Retry-After seconds | | INTERNAL_ERROR | 500 | retry with backoff | # Rate limiting Every response after successful authentication carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 also carries Retry-After. The two 401s are emitted before rate-limit accounting. Default window is 100 requests per rolling hour unless the key was configured otherwise. # Canonical host Use https://posnavigator.eu. Legacy .hu hosts redirect; authenticated writes should call .eu directly. Additional codes: INVALID_QUERY 400, INVALID_PAYLOAD 400, NOT_FOUND 404, CONFLICT 409 (slug). servers: - url: https://posnavigator.eu tags: - name: Discovery - name: PresetFilters security: - ApiKeyAuth: [] paths: /openapi/presetfilters.yaml: get: operationId: getPresetFiltersOpenApi tags: [Discovery] security: [] summary: Public OpenAPI 3.1 description description: |- This document. Public: no API key, no rate limit. Fetch it first and treat it as the complete manual. Every schema, limit, example, error code and header an agent needs is here. Linked from GET /openapi/catalog.yaml. Data operations below require authentication as described in info. responses: '200': description: OpenAPI YAML content: application/yaml: schema: type: string example: 'openapi: 3.1.0' /api/v1/presetfilters: get: operationId: listPresetFilters tags: [PresetFilters] summary: List preset filters description: |- Requires presetfilter:read. Optional boolean query flags isprod, showOnHomepage, showInHeroEntry, agentEnabled, isArena, isLanding, isPromotion. limit 1-100 default 50, offset default 0. Use this to discover presetfilterId and to inspect stored filters query strings. parameters: - name: isprod in: query schema: { type: boolean } - name: showOnHomepage in: query schema: { type: boolean } - name: showInHeroEntry in: query schema: { type: boolean } - name: agentEnabled in: query schema: { type: boolean } - name: isArena in: query schema: { type: boolean } - name: isLanding in: query schema: { type: boolean } - name: isPromotion in: query schema: { type: boolean } - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 50 } - name: offset in: query schema: { type: integer, minimum: 0, default: 0 } responses: '200': description: Preset list headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PresetListResponse' '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: createPresetFilter tags: [PresetFilters] summary: Create a preset filter description: |- Requires presetfilter:write. Required translations (hu/en name+description), filters query string, and channels (at least one ObjectId). Optional homepage/hero/agent/arena/landing flags, slug (required uniqueness when isLanding), overridableFields enum list, arenaTranslations, landingTranslations. 409 when slug is taken. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PresetWriteRequest' example: translations: hu: { name: Éttermi POS, description: Vendéglátás } en: { name: Restaurant POS, description: Hospitality } filters: s_income=1000000&sortBy=sumprice channels: ['507f1f77bcf86cd799439011'] showInHeroEntry: true responses: '201': description: Created headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PresetDetailResponse' '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /api/v1/presetfilters/{presetfilterId}: parameters: - name: presetfilterId in: path required: true schema: { type: string, pattern: '^[a-fA-F0-9]{24}$', maxLength: 24 } get: operationId: getPresetFilter tags: [PresetFilters] summary: Get one preset filter description: |- Requires presetfilter:read. Returns filters query string, flags, translations, overridableFields, and related channel objects. 404 when missing. responses: '200': description: Preset headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PresetDetailResponse' '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' patch: operationId: patchPresetFilter tags: [PresetFilters] summary: Partially update a preset filter description: |- Requires presetfilter:write. translations merge per locale. filters is replaced entirely when sent — it is not merged as JSON. channels is a list of ObjectIds. overridableFields must stay a subset of the supported wizard dimensions listed on the schema. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PresetWriteRequest' responses: '200': description: Updated headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PresetDetailResponse' '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' delete: operationId: deletePresetFilter tags: [PresetFilters] summary: Delete a preset filter description: |- Requires presetfilter:write. Irreversible. Widgets and landings that still point at this id will break — re-point them first. responses: '200': description: Deleted headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PresetDetailResponse' '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: |- Send `X-Api-Key: pn_...` on every data operation. Create a key at /user/api-keys; it is shown once. Inactive or expired keys return 401. headers: X-RateLimit-Limit: description: Maximum requests allowed in the current window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: Unix epoch seconds when the window resets schema: type: integer Retry-After: description: Seconds to wait before retrying a 429 schema: type: integer parameters: BankId: name: bankId in: path required: true description: 24-character hex Mongo ObjectId of the bank schema: type: string pattern: '^[a-fA-F0-9]{24}$' maxLength: 24 schemas: ErrorEnvelope: type: object additionalProperties: false required: [success, error] properties: success: type: boolean const: false error: type: object additionalProperties: false required: [code, message] properties: code: type: string maxLength: 80 description: Stable machine code. Branch on this, never on message. message: type: string maxLength: 2000 details: type: array maxItems: 50 items: type: string maxLength: 500 retryAfter: type: integer description: Present on RATE_LIMIT_EXCEEDED field_errors: type: object additionalProperties: type: array maxItems: 20 items: type: string maxLength: 500 LocalePair: type: object additionalProperties: false properties: hu: type: string maxLength: 20000 en: type: string maxLength: 20000 OffsetPagination: type: object additionalProperties: false required: [total, limit, offset, hasMore] properties: total: type: integer limit: type: integer offset: type: integer hasMore: type: boolean PresetListResponse: type: object required: [success, data] additionalProperties: true properties: success: { type: boolean, const: true } data: type: object additionalProperties: true PresetDetailResponse: type: object required: [success, data] additionalProperties: false properties: success: { type: boolean, const: true } data: type: object additionalProperties: true OverridableField: type: string enum: [company_profile, company_type, mcc, company_activity, channels, currencies, income_basket, merchant_template, pos_terminal, webstore, payment_schemes, servicetypes, languages, features, banks, itproviders, promotions] PresetWriteRequest: type: object additionalProperties: true properties: translations: type: object additionalProperties: true description: hu/en name (max 200) and description (max 2000) filters: type: string maxLength: 8000 description: URL query string for offer search, not JSON channels: type: array minItems: 1 maxItems: 20 items: { type: string, maxLength: 24 } priority: { type: integer, minimum: 0 } isprod: { type: boolean } showOnHomepage: { type: boolean } showInHeroEntry: { type: boolean, description: Homepage hero / mini-wizard entry } agentEnabled: { type: boolean, description: Allow agent-platform recommendations on this preset } isPromotion: { type: boolean } isArena: { type: boolean } isLanding: { type: boolean } slug: type: string maxLength: 80 pattern: '^[a-z0-9-]+$' overridableFields: type: array maxItems: 30 items: { $ref: '#/components/schemas/OverridableField' } arenaTranslations: type: object additionalProperties: true landingTranslations: type: object additionalProperties: true