{"openapi":"3.1.0","info":{"title":"Bsale (BYOK) API","version":"0.1.0","description":"Bsale (BYOK) lets an AI assistant read your own Bsale data through the Bsale API with a key you supply (Bsale access token). Read-only: 8 tools (list_documents, get_document, get_document_details, list_products, list_variants, list_stocks, list_price_lists, list_product_types). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-bsale.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-bsale/docs"},"termsOfService":"https://connectorbay.com/byok-bsale/terms"},"servers":[{"url":"https://byok-bsale.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-bsale/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_documents":{"post":{"operationId":"list_documents","summary":"List sales documents (invoices, receipts, quotes) with number, emission and expiry dates (Unix seconds), net, tax and to","description":"List sales documents (invoices, receipts, quotes) with number, emission and expiry dates (Unix seconds), net, tax and total amounts, SII status and the linked document type, office and client ids. Use for \"What sales documents did Bsale issue this month and for how much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"emissiondate":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only documents emitted on this day, as Unix seconds at midnight, for example 1463540400.","title":"Emissiondate"},"documenttypeid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this document type id.","title":"Documenttypeid"},"officeid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this office (branch) id.","title":"Officeid"},"clientid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this client id.","title":"Clientid"},"number":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this document number (folio).","title":"Number"},"codesii":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"SII document code, for example 33 (invoice) or 39 (receipt).","title":"Codesii"},"informedsii":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 for documents already reported to SII, 0 for the rest.","title":"Informedsii"},"state":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 returns active records, 1 returns inactive ones.","title":"State"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_documentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_document":{"post":{"operationId":"get_document","summary":"Get one sales document by id with its amounts, dates, SII status and linked ids. Use for \"What are the amounts and statu","description":"Get one sales document by id with its amounts, dates, SII status and linked ids. Use for \"What are the amounts and status of Bsale document 421\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"document_id":{"description":"Bsale document id.","title":"Document Id","type":"integer"}},"required":["document_id"],"title":"get_documentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_document_details":{"post":{"operationId":"get_document_details","summary":"List the line items of one sales document: quantity, net and total unit value, net, tax and total amount, discounts and ","description":"List the line items of one sales document: quantity, net and total unit value, net, tax and total amount, discounts and the variant sold. Use for \"Which items were on Bsale document 12644\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"document_id":{"description":"Bsale document id.","title":"Document Id","type":"integer"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"required":["document_id"],"title":"get_document_detailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_products":{"post":{"operationId":"list_products","summary":"List products and services with name, classification (0 product, 1 service, 3 pack), stock control flag, state and produ","description":"List products and services with name, classification (0 product, 1 service, 3 pack), stock control flag, state and product type. Use for \"Which products are active in my Bsale catalogue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by product name.","title":"Name"},"producttypeid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this product type id.","title":"Producttypeid"},"state":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 returns active records, 1 returns inactive ones.","title":"State"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_variants":{"post":{"operationId":"list_variants","summary":"List product variants with description, SKU code, bar code, stock flags, state and the parent product id. Use for \"What ","description":"List product variants with description, SKU code, bar code, stock flags, state and the parent product id. Use for \"What SKU does the 240 ML variant have in Bsale\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"description":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by variant name.","title":"Description"},"code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by SKU.","title":"Code"},"barcode":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by bar code.","title":"Barcode"},"productid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this product id.","title":"Productid"},"state":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 returns active records, 1 returns inactive ones.","title":"State"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_variantsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_stocks":{"post":{"operationId":"list_stocks","summary":"List stock levels per variant and office: real, reserved and available quantity. Use for \"Which variants are low on stoc","description":"List stock levels per variant and office: real, reserved and available quantity. Use for \"Which variants are low on stock in my Bsale office 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"officeid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this office (branch) id.","title":"Officeid"},"variantid":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this variant id.","title":"Variantid"},"code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by variant SKU.","title":"Code"},"barcode":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by bar code.","title":"Barcode"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_stocksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_price_lists":{"post":{"operationId":"list_price_lists","summary":"List price lists with name, state and currency id. Use for \"Which price lists do I have in Bsale\".","description":"List price lists with name, state and currency id. Use for \"Which price lists do I have in Bsale\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by price list name.","title":"Name"},"state":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 returns active records, 1 returns inactive ones.","title":"State"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_price_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_product_types":{"post":{"operationId":"list_product_types","summary":"List product types (categories) with name, editable flag and state. Use for \"Which product types exist in my Bsale accou","description":"List product types (categories) with name, editable flag and state. Use for \"Which product types exist in my Bsale account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by type name.","title":"Name"},"state":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 returns active records, 1 returns inactive ones.","title":"State"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip, for paging.","title":"Offset"}},"title":"list_product_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}