{"openapi":"3.0.3","info":{"title":"KsięgujęSam Public API","version":"1.0.0-rc43","description":"REST API do wystawiania faktur VAT z zewnętrznych systemów. Pełna instrukcja: https://app.ksiegujesam.pl/integracja","contact":{"email":"kontakt@ksiegujesam.pl","url":"https://ksiegujesam.pl/api/"}},"servers":[{"url":"https://api.ksiegujesam.pl","description":"Production"}],"tags":[{"name":"Public API v1","description":"Faktury i kontrahenci"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Klucz ks_… z Zaplecze → Publiczne API (PRO+)"}},"schemas":{"Buyer":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"nip":{"type":"string"},"email":{"type":"string","format":"email"},"addressLine1":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","default":"PL"}}},"InvoiceLine":{"type":"object","required":["name","quantity","unitNetPrice","vatRate"],"properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string","example":"szt."},"unitNetPrice":{"type":"number","description":"Cena netto za jednostkę"},"vatRate":{"type":"string","enum":["23","8","5","0","0_wdt","0_ex","zw","np"]}}},"CreateInvoice":{"type":"object","required":["organizationId","kind","issueDate","buyer","lines"],"properties":{"organizationId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["VAT"],"default":"VAT"},"issueDate":{"type":"string","format":"date"},"buyer":{"$ref":"#/components/schemas/Buyer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}},"notes":{"type":"string"},"sendToKsef":{"type":"boolean","default":false},"emailBuyer":{"type":"boolean","default":false},"callbackUrl":{"type":"string","format":"uri"}}}}},"paths":{"/v1/me":{"get":{"tags":["Public API v1"],"summary":"Konta i organizacje klucza API","security":[{"apiKey":[]}],"responses":{"200":{"description":"organizations[].id → organizationId"},"401":{"description":"Nieprawidłowy klucz"}}}},"/v1/invoices":{"get":{"tags":["Public API v1"],"summary":"Lista faktur","security":[{"apiKey":[]}],"parameters":[{"name":"organizationId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista faktur"}}},"post":{"tags":["Public API v1"],"summary":"Wystaw fakturę VAT","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoice"}}}},"responses":{"201":{"description":"Faktura utworzona — id, number, paymentUrl, htmlUrl"},"400":{"description":"Walidacja"},"401":{"description":"Nieprawidłowy klucz"},"403":{"description":"Plan / scope"}}}},"/v1/invoices/{id}":{"get":{"tags":["Public API v1"],"summary":"Szczegóły faktury","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"organizationId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Faktura"}}}},"/v1/invoices/{id}/html":{"get":{"tags":["Public API v1"],"summary":"Publiczny HTML faktury","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"organizationId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML"}}}},"/v1/invoices/{id}/email":{"post":{"tags":["Public API v1"],"summary":"Wyślij mail z FV do nabywcy","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"email.sent"}}}},"/v1/contractors":{"get":{"tags":["Public API v1"],"summary":"Szukaj kontrahentów","security":[{"apiKey":[]}],"parameters":[{"name":"organizationId","in":"query","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista kontrahentów"}}}}}}