openapi: 3.0.3 info: title: RustOpus XML API version: 1.0.0 description: Get Octopus 8 ERP SOAP XML with english tags instead of hungarians paths: /get-product: get: summary: Get product data description: Returns basic data for the products. tags: - Products parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML product list content: application/xml: schema: $ref: '#/components/schemas/ProductResponse' /get-stock: get: summary: Get stock data description: Returns stock for the products. tags: - Stocks parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML stock list content: application/xml: schema: $ref: '#/components/schemas/StockResponse' /get-price: get: summary: Get price data description: Returns price for the products tags: - Prices parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: pid in: query required: true description: Partner ID schema: type: integer - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML price list content: application/xml: schema: $ref: '#/components/schemas/PriceResponse' /get-image: get: summary: Get image data description: Returns images for the products tags: - Images parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML image list content: application/xml: schema: $ref: '#/components/schemas/ImageResponse' /get-barcode: get: summary: Get barcodes data description: Returns barcodes/eans for the products tags: - Barcodes parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML barcode list content: application/xml: schema: $ref: '#/components/schemas/BarcodeResponse' /get-invoice: get: summary: Get invoice data description: Returns invoice data. tags: - Invoices parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: pid in: query required: true description: Partner ID schema: type: integer - name: type_mod in: query required: false description: Invoice type schema: type: integer - name: from_date in: query required: true description: First date in YYYY-MM-DDThh:mm:ssZ format (2025-01-01T00:00:00Z) schema: type: string - name: to_date in: query required: true description: Last date in YYYY-MM-DDThh:mm:ssZ format (2025-01-01T00:00:00Z) schema: type: string - name: unpaid in: query required: false description: 1 if only the unpaid invoices should be inclouded schema: type: integer - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML invoice list content: application/xml: schema: $ref: '#/components/schemas/InvoiceResponse' /get-bulk: get: summary: Get bulk data (XML) description: Returns concatenated data for the products. This containts every main information, but takes a long time to get. tags: - Bulk parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: pid in: query required: true description: Partner ID schema: type: integer responses: '200': description: XML bulk list content: application/xml: schema: $ref: '#/components/schemas/BulkResponse' /get-mat: get: summary: Get mathematican models data description: Returns the mathematican models (product attributes/concepts). Supports XML or CSV output. tags: - Mat parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: from_date in: query required: false description: Optional filter date in YYYY-MM-DDThh:mm:ssZ format (2025-01-01T00:00:00Z) schema: type: string - name: data_type in: query required: false description: Optional output format; set to `csv` for semicolon-delimited CSV schema: type: string - name: language in: query required: false description: Optional language (only supports `HU`) schema: type: string responses: '200': description: XML (or CSV) mathematican models list content: application/xml: schema: $ref: '#/components/schemas/MatResponse' text/csv: schema: type: string /post-order: post: summary: Submit an order to Octopus 8 ERP description: Submit an order in English XML format. Converts to Hungarian, sends to Octopus, and returns the response in English XML format. tags: - Orders parameters: - name: url in: query required: true description: Endpoint URL with the ```.asmx``` file schema: type: string - name: authcode in: query required: true description: Authorization code schema: type: string - name: xmlns in: query required: false description: Optional XML namespace schema: type: string - name: pid in: query required: true description: Partner ID schema: type: integer requestBody: required: true content: application/xml: schema: $ref: '#/components/schemas/OrderRequest' responses: '200': description: Order submission response with confirmation details content: application/xml: schema: $ref: '#/components/schemas/OrderResponse' '400': description: Invalid XML format '500': description: Failed to parse Octopus response # The entries below are NOT REST endpoints and are documented here only so this # file stays a complete map of what the binary serves. They exist only in an # instance started with `[mcp] enabled = true` (and, for the OAuth ones, with # `oauth_enabled = true`); on the public API instance they return 404. /mcp: post: summary: Model Context Protocol endpoint description: | **Not a REST endpoint.** A Streamable HTTP MCP transport (JSON-RPC 2.0 over POST, with GET for the SSE stream and DELETE to close a session), intended for AI assistants rather than for direct calls. Add it to a client as a custom connector; do not try it from this page. Credentials travel as request headers or as a bearer token, never as query parameters, so an authcode never lands in an access log. - `X-Authcode` — the caller's Octopus authentication code - `X-Pid` — the caller's partner id, fixed per user With `[mcp] oauth_enabled = true` this endpoint is an OAuth 2.1 protected resource instead: an unauthenticated request is refused with `401` and a `WWW-Authenticate: Bearer resource_metadata="…"` challenge, which is what starts a connector's sign-in flow. The headers above keep working while `oauth_allow_headers` is on. See `/oauth/authorize` below. Five tools are exposed: `search_products`, `get_product`, `list_categories`, `catalog_status` and `export_products`. Answers come from a cached catalog snapshot refreshed by a background job, so they are fast but not live; `catalog_status` reports the snapshot's age. `export_products` writes an Excel or CSV file and returns a link to `/export/{token}` rather than the rows themselves — a catalog of ~24,000 products cannot be delivered through a chat at any page size. tags: - MCP parameters: - name: X-Authcode in: header required: false description: Octopus authentication code (required unless a bearer token is sent) schema: type: string - name: X-Pid in: header required: false description: Partner ID (required unless a bearer token is sent) schema: type: integer format: int64 - name: Authorization in: header required: false description: '`Bearer `, when OAuth is enabled' schema: type: string requestBody: required: true description: A JSON-RPC 2.0 request, as defined by the MCP specification content: application/json: schema: type: object responses: '200': description: JSON-RPC response, as JSON or as an SSE stream content: text/event-stream: schema: type: string '401': description: | No credentials, or an unknown, expired or wrong-audience bearer token. Carries the `WWW-Authenticate` challenge that starts the OAuth flow. '403': description: The caller's authcode is on the access blocklist (error code 204) '404': description: MCP is disabled on this instance /.well-known/oauth-protected-resource: get: summary: OAuth protected-resource metadata (RFC 9728) description: | **Not a REST endpoint.** Tells an MCP client which authorization server guards `/mcp` and what to ask it for. Also served at `/.well-known/oauth-protected-resource/mcp`, because clients disagree about where to look. Public and cross-origin readable. Registered only when `[mcp] oauth_enabled = true`. tags: - MCP responses: '200': description: The metadata document content: application/json: schema: type: object '404': description: OAuth is disabled on this instance /.well-known/oauth-authorization-server: get: summary: OAuth authorization-server metadata (RFC 8414) description: | **Not a REST endpoint.** Advertises the endpoints, grants and PKCE method this server supports. Also served at `/.well-known/oauth-authorization-server/mcp`. No `registration_endpoint` is published: clients are created by hand in `/admin` (RFC 7591 dynamic registration is deliberately not implemented), which is what the connector dialog's Client ID / Client Secret fields are for. tags: - MCP responses: '200': description: The metadata document content: application/json: schema: type: object '404': description: OAuth is disabled on this instance /oauth/authorize: get: summary: OAuth sign-in page description: | **Not a REST endpoint.** The start of the authorization-code flow, opened in the partner's browser by their MCP client — never called directly. Validates `client_id`, an exactly-matching `redirect_uri`, `response_type=code`, `code_challenge` with `code_challenge_method=S256`, the scope (`catalog.read`) and the `resource`, then renders a sign-in page asking for the partner's **existing Octopus authcode and partner id**. This server issues no separate password. A failure after the client and redirect URI are known is reported by redirecting back with `error=`; a failure *of* the client or redirect URI renders a plain page instead, because redirecting to an unverified URI is how open redirectors are built. The form posts to `/oauth/login`, which proves the authcode against Octopus, records the sign-in and redirects to the client with a single-use authorization code. `/oauth/token` exchanges that code (with the PKCE verifier and the client secret) for a bearer token, and `/oauth/revoke` invalidates one (RFC 7009). tags: - MCP parameters: - name: client_id in: query required: true schema: type: string - name: redirect_uri in: query required: true schema: type: string - name: response_type in: query required: true schema: type: string enum: [code] - name: code_challenge in: query required: true schema: type: string - name: code_challenge_method in: query required: true schema: type: string enum: [S256] - name: state in: query required: false schema: type: string - name: scope in: query required: false schema: type: string - name: resource in: query required: false schema: type: string responses: '200': description: The sign-in page content: text/html: schema: type: string '303': description: Redirect back to the client with `error=` (RFC 6749 §4.1.2.1) '400': description: Unknown client, or a redirect URI this client has not registered '404': description: OAuth is disabled on this instance /export/{token}: get: summary: Download a generated product export description: | **Not a REST endpoint in the usual sense.** Serves an Excel or CSV export produced by the MCP `export_products` tool. Exists because ~24,000 product rows cannot be delivered through a chat: the tool writes a file and returns a link to it. The token in the path is the only credential — unguessable, single-purpose and short-lived (`[mcp] export_ttl_secs`, default one hour). An authcode is deliberately **not** used here: it would appear in every access log between the browser and this service. An unknown or expired token returns 404 with no hint about whether it ever existed. The file holds the requesting partner's own negotiated prices and stock, so treat the link as confidential for as long as it lives. tags: - MCP parameters: - name: token in: path required: true description: Download token returned by `export_products` schema: type: string responses: '200': description: The export, as a file attachment content: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary text/csv: schema: type: string '404': description: Unknown or expired token, or MCP is disabled on this instance /admin: get: summary: Administration dashboard description: | **Not a REST endpoint.** A small internal web application for managing the access blocklist, and — on an instance with MCP enabled — which `(authcode, pid)` combinations the background job keeps warm, plus cache usage. With OAuth enabled it also registers the connectors that may sign partners in, and lists (and revokes) the sign-ins they hold; creating a connector is the one response in this service that ever carries a client secret, and it is shown exactly once. The blocklist refuses matching callers with `403` and error code `204` before they reach any endpoint. Rules match on an IP address or CIDR range, or on an authcode (held hashed, never in the clear), and each applies to everything, to the REST endpoints only, or to `/mcp` and its exports only. `/admin` itself is never blocked. It has its own authentication — an admin token supplied as HTTP Basic credentials or an `X-Admin-Token` header, never a SOAP authcode — and is not registered at all when no token is configured. Because the entries behind it hold authcodes at rest, bind it to an internal interface or put it behind the VPN rather than exposing it on a public hostname. The JSON API under `/admin/api/` never returns a full authcode. tags: - MCP responses: '200': description: The dashboard content: text/html: schema: type: string '401': description: Missing or invalid admin token '404': description: No admin token is configured components: schemas: ProductResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: properties: version: type: string error: type: object properties: code: type: number description: type: string products: type: array items: $ref: '#/components/schemas/ProductProducts' ProductProducts: type: object properties: product: type: object properties: id: type: number no: type: string name: type: string unit: type: string base_unit: type: string base_unit_qty: type: number brand: type: string category_code: type: string category_name: type: string description: type: string weight: type: number size: type: object properties: x: type: number y: type: number z: type: number oem_code: type: string main_category_code: type: string main_category_name: type: string sell_unit: type: number origin_country: type: string StockResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string products: type: array items: $ref: '#/components/schemas/StockProducts' StockProducts: type: object xml: name: products properties: product: type: object properties: id: type: number no: type: string stock: type: number PriceResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string products: type: array items: $ref: '#/components/schemas/PriceProducts' PriceProducts: type: object xml: name: products properties: product: type: object properties: id: type: number no: type: string list_price: type: number price: type: number sale_price: type: number currency: type: string ImageResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string products: type: array items: $ref: '#/components/schemas/ImageProducts' ImageProducts: type: object xml: name: products properties: product: type: object properties: id: type: number no: type: string images: type: array items: $ref: '#/components/schemas/ImageImages' ImageImages: type: object xml: name: images properties: image: type: object properties: gallery: type: string url: type: string BulkResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string products: type: array items: $ref: '#/components/schemas/BulkProducts' BulkProducts: type: object xml: name: products properties: product: type: object properties: id: type: number no: type: string name: type: string unit: type: string base_unit: type: string base_unit_qty: type: string brand: type: string oem_code: type: string category_code: type: string category_name: type: string description: type: string weight: type: number size: type: object properties: x: type: number y: type: number z: type: number main_category_code: type: string main_category_name: type: string sell_unit: type: number origin_country: type: string price: type: number currency: type: string stock: type: number ean: type: string images: type: array items: $ref: '#/components/schemas/BulkImages' BulkImages: type: object xml: name: images properties: url: type: string MatResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string attributes: type: array items: $ref: '#/components/schemas/MatAttributes' MatAttributes: type: object xml: name: attributes properties: attribute: type: object properties: id: type: number code: type: string name: type: string product_id: type: number product_no: type: string string_value: type: string num_value: type: number order: type: number delstatus: type: number filter: type: number data_type: type: number value_set: type: number BarcodeResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string barcodes: type: array items: $ref: '#/components/schemas/Barcodes' Barcodes: type: object xml: name: barcodes properties: barcode: type: object properties: ean: type: string id: type: number no: type: string unit: type: string main_ean: type: boolean InvoiceResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string error: type: object properties: code: type: number description: type: string invoices: type: array items: $ref: '#/components/schemas/Invoices' Invoices: type: object xml: name: invoices properties: invoice: type: object properties: head: type: object properties: id: type: integer no: type: string date: type: string completition_date: type: string payment_deadline: type: string net_price: type: string price: type: number remaining: type: number cancellation_no: type: string currency: type: string pid: type: integer partner_name: type: string status: type: integer foreign_order_no: type: string delivery_name: type: string delivery_country: type: string delivery_zip: type: string delivery_city: type: string delivery_street: type: string products: type: array items: $ref: '#/components/schemas/InvoiceProducts' InvoiceProducts: type: object xml: name: products properties: product: type: object properties: lot_no: type: integer id: type: integer no: type: string name: type: string qty: type: number unit: type: string net_unit_price: type: number unit_price: type: number net_price: type: number price: type: number order_no: type: string order_foreign_no: type: string OrderRequest: type: object xml: name: order properties: version: type: string example: "1.0" header: type: object properties: pid: type: integer example: 7824 foreign_order_number: type: string example: "rustopus_test_1" delivery_mode: type: integer example: 1 items: type: array xml: name: items items: type: object xml: name: item properties: lot_no: type: integer example: 1 no: type: string description: Product/article number example: "PAPIRA4CAN" qty: type: number example: 1.0 OrderResponse: type: object xml: name: Envelope properties: body: type: object properties: response: type: object properties: result: type: object properties: answer: type: object properties: version: type: string example: "1.0" header: type: object xml: name: header properties: identifier: type: integer example: 1773747 web_identifier: type: string format: uuid example: "f6f9f502-1446-4183-aaeb-9df2245457fe" document_number: type: string example: "XKBRE2608459" delivery_date: type: string format: date example: "2026.03.31" items: type: array xml: name: items items: type: object xml: name: item properties: item_number: type: integer example: 1 recorded_item_number: type: integer example: 1 product_number: type: string example: "PAPIRA4CAN" quantity: type: object properties: type: type: string example: "1" coverage: type: string example: "1-50" date: type: string format: date-time example: "2026-03-31T00:00:00" value: type: number example: 1.0 unit_price_net: type: number example: 1193.5007520 unit_price_gross: type: number example: 1515.74595504 value_net: type: number example: 1193.500752 value_gross: type: number example: 1515.745955 currency: type: string example: "HUF" extra_items: type: string nullable: true shipping_cost: type: string nullable: true cash_on_delivery: type: string nullable: true extra_services: type: string nullable: true return_fee: type: string nullable: true