{"openapi":"3.1.0","info":{"title":"Poland e-Invoice QR and Readiness API","version":"0.1.0","description":"Poland e-Invoice QR and Readiness works with the National e-Invoice System (KSeF) verification codes and start dates. compute_invoice_hash gives the SHA-256 of the exact invoice XML bytes in Base64URL, as the QR link needs it. build_invoice_qr_url assembles the type I verification link (seller NIP, issue date, hash) for the production, demo or test host. build_certificate_qr_template assembles...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://pl-ksef-qr.connectorbay.com/mcp.\n\nDisclaimer: General information only, not legal, tax, accounting or payment advice. Poland e-Invoice QR and Readiness is an independent tool: it is not affiliated with, endorsed by or operated by any government body, central bank, standards body or scheme operator. Rates, thresholds and rules change; check the cited official source and confirm with a qualified professional before you rely on a result.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/pl-ksef-qr/docs"},"termsOfService":"https://connectorbay.com/pl-ksef-qr/terms"},"servers":[{"url":"https://pl-ksef-qr.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/pl-ksef-qr/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/compute_invoice_hash":{"post":{"operationId":"compute_invoice_hash","summary":"SHA-256 of the invoice XML bytes as Base64URL (no padding), the hash segment of the KSeF QR link. Use for \"What is the h","description":"SHA-256 of the invoice XML bytes as Base64URL (no padding), the hash segment of the KSeF QR link. Use for \"What is the hash of this invoice XML in the format the KSeF QR link needs?\". The hash covers the exact bytes you submit: any change of whitespace, line endings or encoding gives another hash.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"invoice_xml":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The invoice XML exactly as it is submitted to KSeF, as text (hashed as UTF-8). Give this or invoice_base64, not both (at most 2,000,000 characters)","title":"Invoice Xml"},"invoice_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The invoice XML file bytes, Base64 encoded with the standard alphabet; use it when exact bytes matter (encoding, line endings, BOM). Give this or invoice_xml (at most 3,000,000 characters)","title":"Invoice Base64"}},"title":"compute_invoice_hashArguments","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/build_invoice_qr_url":{"post":{"operationId":"build_invoice_qr_url","summary":"KSeF type I verification link (seller NIP, issue date, invoice hash) for the production, demo or test host. Use for \"Wha","description":"KSeF type I verification link (seller NIP, issue date, invoice hash) for the production, demo or test host. Use for \"What is the KSeF verification QR link for the invoice of seller NIP 1111111111 issued on 01-02-2026 with this hash?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller_nip":{"description":"Seller NIP, 10 digits (an optional PL prefix, spaces and hyphens are removed); the checksum must be valid (at most 50 characters)","title":"Seller Nip","type":"string"},"issue_date":{"description":"Invoice issue date as DD-MM-YYYY or YYYY-MM-DD (the four-digit year position tells them apart) (at most 40 characters)","title":"Issue Date","type":"string"},"invoice_hash":{"description":"SHA-256 of the invoice file in Base64URL without padding (43 characters), for example from compute_invoice_hash (at most 100 characters)","title":"Invoice Hash","type":"string"},"environment":{"default":"prod","description":"prod (default), demo or test: selects the QR host (at most 20 characters)","title":"Environment","type":"string"},"ksef_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The KSeF number of the invoice when it has been assigned; used only for the label to print under the code (at most 100 characters)","title":"Ksef Number"}},"required":["seller_nip","issue_date","invoice_hash"],"title":"build_invoice_qr_urlArguments","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/build_certificate_qr_template":{"post":{"operationId":"build_certificate_qr_template","summary":"KSeF type II (offline certificate) link template and the exact text to sign; never signs. Use for \"What exact text must ","description":"KSeF type II (offline certificate) link template and the exact text to sign; never signs. Use for \"What exact text must my offline certificate sign for the second QR code of an offline invoice?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"context_type":{"description":"Context identifier type: Nip, InternalId, NipVatUe or PeppolId (at most 40 characters)","title":"Context Type","type":"string"},"context_value":{"description":"Value of the context identifier (for Nip a 10-digit NIP with a valid checksum) (at most 100 characters)","title":"Context Value","type":"string"},"seller_nip":{"description":"Seller NIP, 10 digits; the checksum must be valid (at most 50 characters)","title":"Seller Nip","type":"string"},"certificate_serial":{"description":"Serial number of the KSeF offline certificate in hexadecimal (upper case), for example 16 hex characters (at most 100 characters)","title":"Certificate Serial","type":"string"},"invoice_hash":{"description":"SHA-256 of the invoice file in Base64URL without padding (43 characters) (at most 100 characters)","title":"Invoice Hash","type":"string"},"environment":{"default":"prod","description":"prod (default), demo or test: selects the QR host (at most 20 characters)","title":"Environment","type":"string"},"signature":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Base64URL signature you produced yourself over the string_to_sign; when given, the complete link is assembled (at most 5,000 characters)","title":"Signature"}},"required":["context_type","context_value","seller_nip","certificate_serial","invoice_hash"],"title":"build_certificate_qr_templateArguments","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/qr_label_text":{"post":{"operationId":"qr_label_text","summary":"Text printed under a KSeF QR code: the KSeF number, OFFLINE or CERTYFIKAT. Use for \"What text goes under the first and t","description":"Text printed under a KSeF QR code: the KSeF number, OFFLINE or CERTYFIKAT. Use for \"What text goes under the first and the second QR code of an offline invoice?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"qr_type":{"description":"I for the invoice verification code, II for the certificate verification code (at most 40 characters)","title":"Qr Type","type":"string"},"ksef_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"KSeF number when one has been assigned (type I only); leave empty for an offline invoice without a number (at most 100 characters)","title":"Ksef Number"}},"required":["qr_type"],"title":"qr_label_textArguments","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/validate_nip":{"post":{"operationId":"validate_nip","summary":"Polish NIP format and checksum check (no registry lookup). Use for \"Is 1111111111 a well-formed Polish NIP?\". It says no","description":"Polish NIP format and checksum check (no registry lookup). Use for \"Is 1111111111 a well-formed Polish NIP?\". It says nothing about whether the number belongs to an active taxpayer.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"nip":{"description":"NIP as written; an optional PL prefix, spaces and hyphens are removed (at most 50 characters)","title":"Nip","type":"string"}},"required":["nip"],"title":"validate_nipArguments","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/ksef_start_phase":{"post":{"operationId":"ksef_start_phase","summary":"Which published KSeF start date (1 Feb 2026, 1 Apr 2026, 1 Jan 2027) applies to a business, from its 2024 sales and mont","description":"Which published KSeF start date (1 Feb 2026, 1 Apr 2026, 1 Jan 2027) applies to a business, from its 2024 sales and monthly invoiced sales. Use for \"My 2024 sales were PLN 3,000,000 including VAT and I invoice up to PLN 50,000 a month: from when must I use KSeF?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sales_2024_pln":{"description":"Value of the business's sales in 2024 including tax, in PLN, as a plain decimal (use 0 if none), for example 3000000 (at most 30 characters)","title":"Sales 2024 Pln","type":"string"},"max_monthly_invoiced_sales_pln":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Highest monthly value of sales documented with invoices, gross, in PLN, as a plain decimal; leave empty when unknown (the answer is then partial) (at most 30 characters)","title":"Max Monthly Invoiced Sales Pln"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the answer is for, YYYY-MM-DD; defaults to the server date","title":"On Date"}},"required":["sales_2024_pln"],"title":"ksef_start_phaseArguments","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/days_until_ksef_deadline":{"post":{"operationId":"days_until_ksef_deadline","summary":"Days to or since each KSeF milestone and whether the 2026 no-penalty period still applies on a date. Use for \"How many d","description":"Days to or since each KSeF milestone and whether the 2026 no-penalty period still applies on a date. Use for \"How many days are left until KSeF applies to me and is the no-penalty period still running?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sales_2024_pln":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Value of the business's sales in 2024 including tax, in PLN, as a plain decimal; leave empty to list the milestones without picking one (at most 30 characters)","title":"Sales 2024 Pln"},"max_monthly_invoiced_sales_pln":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Highest monthly value of sales documented with invoices, gross, in PLN, as a plain decimal; leave empty when unknown (at most 30 characters)","title":"Max Monthly Invoiced Sales Pln"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the answer is for, YYYY-MM-DD; defaults to the server date","title":"On Date"}},"title":"days_until_ksef_deadlineArguments","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/ksef_offline_modes_guide":{"post":{"operationId":"ksef_offline_modes_guide","summary":"The KSeF offline24, unavailability and emergency modes: when each applies, the sending deadline and the QR codes each ca","description":"The KSeF offline24, unavailability and emergency modes: when each applies, the sending deadline and the QR codes each carries. Use for \"What is the difference between offline24, system unavailability and emergency mode, and which QR codes does each need?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"offline24, unavailability or emergency; leave empty for all three (at most 40 characters)","title":"Mode"}},"title":"ksef_offline_modes_guideArguments","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}}}}