{"openapi":"3.1.0","info":{"title":"InvoiceHub API","description":"InvoiceHub customer REST API. Getting started: /en/api-guide (English), /api-guide (Bulgarian). Invoice issuance requires a scoped API key and a live authorized issuing member. POST creates a numbered invoice immediately and queues email; this is not a sandbox. Use the same Idempotency-Key and payload on every retry. Legacy purchase-document reads also accept the existing company OAuth tokens.","contact":{"name":"InvoiceHub support","email":"support@invoicehub.work"},"version":"1.0.0"},"servers":[{"url":"https://web.invoicehub.work","description":"Canonical service origin"}],"paths":{"/v1/invoices":{"get":{"tags":["invoices"],"summary":"List Invoices","operationId":"list_invoices_v1_invoices_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date To"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"}},{"name":"issuer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer"}},{"name":"amount_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Min"}},{"name":"amount_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Max"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Per Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/invoices/{invoice_id}":{"get":{"tags":["invoices"],"summary":"Get Invoice","operationId":"get_invoice_v1_invoices__invoice_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"integer","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sales/invoices":{"post":{"tags":["sales-invoices"],"summary":"Issue and email an invoice","description":"Requires sales:invoices:issue and a live authorized issuing member. A 201 confirms issuance and queued email, not delivery.","operationId":"issue_invoice_v1_sales_invoices_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"idempotency-key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"Stable identifier for this invoice operation; reuse on every retry.","title":"Idempotency-Key"},"description":"Stable identifier for this invoice operation; reuse on every retry."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateInvoiceRequest"},"example":{"client":{"id":123},"invoice":{"payment_method":"bank","language":"bg","lines":[{"description":"Accounting services","quantity":"1","unit_price":"100.00","vat_rate":"20.00"}]},"delivery":{"mode":"explicit","to_email":"billing@client.example"}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateInvoiceResponse"},"example":{"client":{"id":123,"created":false,"name":"Client Ltd","eik":"203078445","vat":null},"invoice":{"id":456,"kind":"invoice","status":"issued","number":"0000000123","issue_date":"2026-10-10","event_date":"2026-10-10","due_date":null,"currency":"EUR","subtotal":"100.00","vat_total":"20.00","total":"120.00","pdf_url":"/v1/sales/invoices/456/pdf"},"delivery":[{"id":789,"to_email":"billing@client.example","status":"pending"}],"warnings":[]}}},"headers":{"Location":{"description":"Relative URL for polling this invoice.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"true when the original successful response is replayed.","schema":{"type":"string","enum":["true","false"]}}}},"401":{"description":"Scoped API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"403":{"description":"Key permission or member rights missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"404":{"description":"Resource not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"409":{"description":"Identity, idempotency or concurrent-operation conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"422":{"description":"Request or domain validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"429":{"description":"Issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"503":{"description":"Temporary infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}}},"x-api-permissions":["sales:invoices:issue"]}},"/v1/sales/invoices/{invoice_id}":{"get":{"tags":["sales-invoices"],"summary":"Get Invoice","operationId":"get_invoice_v1_sales_invoices__invoice_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"integer","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateInvoiceResponse"}}}},"401":{"description":"Scoped API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"403":{"description":"Key permission or member rights missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"404":{"description":"Resource not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"409":{"description":"Identity, idempotency or concurrent-operation conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"422":{"description":"Request or domain validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"429":{"description":"Issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"503":{"description":"Temporary infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}}},"x-api-permissions":["sales:invoices:read"]}},"/v1/sales/invoices/{invoice_id}/pdf":{"get":{"tags":["sales-invoices"],"summary":"Get Pdf","operationId":"get_pdf_v1_sales_invoices__invoice_id__pdf_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"integer","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Scoped API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"403":{"description":"Key permission or member rights missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"404":{"description":"Resource not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"409":{"description":"Identity, idempotency or concurrent-operation conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"422":{"description":"Request or domain validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"429":{"description":"Issuance rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}},"503":{"description":"Temporary infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesApiErrorResponse"}}}}},"x-api-permissions":["sales:invoices:read"]}}},"components":{"schemas":{"ClientContactsDelivery":{"properties":{"mode":{"type":"string","const":"client_contacts","title":"Mode"}},"additionalProperties":false,"type":"object","required":["mode"],"title":"ClientContactsDelivery"},"ClientIdentity":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"eik":{"type":"string","maxLength":32,"title":"Eik","default":""},"vat":{"type":"string","maxLength":32,"title":"Vat","default":""},"address":{"type":"string","maxLength":500,"title":"Address","default":""},"mol":{"type":"string","maxLength":255,"title":"Mol","default":""},"registry_confirmed":{"type":"string","maxLength":32,"title":"Registry Confirmed","default":""}},"additionalProperties":false,"type":"object","required":["name"],"title":"ClientIdentity"},"ClientReference":{"properties":{"id":{"type":"integer","exclusiveMinimum":0.0,"title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"ClientReference"},"ClientResult":{"properties":{"id":{"type":"integer","title":"Id"},"created":{"type":"boolean","title":"Created"},"name":{"type":"string","title":"Name"},"eik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eik"},"vat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat"}},"additionalProperties":false,"type":"object","required":["id","created","name","eik","vat"],"title":"ClientResult"},"DeliveryResult":{"properties":{"id":{"type":"integer","title":"Id"},"to_email":{"type":"string","title":"To Email"},"status":{"type":"string","title":"Status"}},"additionalProperties":false,"type":"object","required":["id","to_email","status"],"title":"DeliveryResult"},"ExplicitDelivery":{"properties":{"mode":{"type":"string","const":"explicit","title":"Mode"},"to_email":{"type":"string","maxLength":320,"minLength":1,"title":"To Email"}},"additionalProperties":false,"type":"object","required":["mode","to_email"],"title":"ExplicitDelivery"},"GenerateInvoiceRequest":{"properties":{"client":{"anyOf":[{"$ref":"#/components/schemas/ClientReference"},{"$ref":"#/components/schemas/ClientIdentity"}],"title":"Client"},"invoice":{"$ref":"#/components/schemas/InvoiceInput"},"delivery":{"oneOf":[{"$ref":"#/components/schemas/ExplicitDelivery"},{"$ref":"#/components/schemas/ClientContactsDelivery"}],"title":"Delivery","discriminator":{"propertyName":"mode","mapping":{"client_contacts":"#/components/schemas/ClientContactsDelivery","explicit":"#/components/schemas/ExplicitDelivery"}}}},"additionalProperties":false,"type":"object","required":["client","invoice","delivery"],"title":"GenerateInvoiceRequest"},"GenerateInvoiceResponse":{"properties":{"client":{"$ref":"#/components/schemas/ClientResult"},"invoice":{"$ref":"#/components/schemas/InvoiceResult"},"delivery":{"items":{"$ref":"#/components/schemas/DeliveryResult"},"type":"array","title":"Delivery"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"additionalProperties":false,"type":"object","required":["client","invoice","delivery","warnings"],"title":"GenerateInvoiceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InvoiceInput":{"properties":{"issue_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Issue Date"},"event_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Event Date"},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due Date"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"range_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Range Id"},"bank_account_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Bank Account Id"},"counterparty_address":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Counterparty Address"},"language":{"$ref":"#/components/schemas/Language","default":"bg"},"prices_include_vat":{"type":"boolean","title":"Prices Include Vat","default":false},"discount_percent":{"type":"string","maxLength":30,"minLength":1,"pattern":"^[0-9]+(?:\\.[0-9]+)?$","title":"Discount Percent","description":"Decimal string from 0 to 100 inclusive; up to 2 fractional places.","default":"0","decimal_places":2,"ge":0,"le":100},"mark_paid":{"type":"boolean","title":"Mark Paid","default":false},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"},"vat_basis_text":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Vat Basis Text"},"lines":{"items":{"$ref":"#/components/schemas/InvoiceLine"},"type":"array","maxItems":200,"minItems":1,"title":"Lines"}},"additionalProperties":false,"type":"object","required":["payment_method","lines"],"title":"InvoiceInput"},"InvoiceLine":{"properties":{"description":{"type":"string","maxLength":500,"minLength":1,"title":"Description"},"quantity":{"type":"string","maxLength":30,"minLength":1,"pattern":"^[0-9]+(?:\\.[0-9]+)?$","title":"Quantity","description":"Decimal string greater than 0 and less than 100000000; up to 4 fractional places.","default":"1","decimal_places":4,"gt":0,"lt":"100000000"},"unit_price":{"type":"string","maxLength":30,"minLength":1,"pattern":"^[0-9]+(?:\\.[0-9]+)?$","title":"Unit Price","description":"Nonnegative decimal string less than 10000000000; up to 4 fractional places.","decimal_places":4,"ge":0,"lt":"10000000000"},"unit":{"anyOf":[{"type":"string","maxLength":16,"minLength":1},{"type":"null"}],"title":"Unit"},"discount_percent":{"type":"string","maxLength":30,"minLength":1,"pattern":"^[0-9]+(?:\\.[0-9]+)?$","title":"Discount Percent","description":"Decimal string from 0 to 100 inclusive; up to 2 fractional places.","default":"0","decimal_places":2,"ge":0,"le":100},"vat_rate":{"type":"string","maxLength":30,"minLength":1,"pattern":"^[0-9]+(?:\\.[0-9]+)?$","title":"Vat Rate","description":"Decimal string from 0 to 100 inclusive; up to 2 fractional places.","default":"0","decimal_places":2,"ge":0,"le":100},"revenue_kind":{"anyOf":[{"$ref":"#/components/schemas/RevenueKind"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["description","unit_price"],"title":"InvoiceLine"},"InvoiceListResponse":{"properties":{"invoices":{"items":{"$ref":"#/components/schemas/InvoiceResponse"},"type":"array","title":"Invoices"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}},"type":"object","required":["invoices","pagination"],"title":"InvoiceListResponse"},"InvoiceResponse":{"properties":{"id":{"type":"integer","title":"Id"},"invoice_number":{"type":"string","title":"Invoice Number"},"type":{"type":"string","title":"Type"},"issuer":{"type":"string","title":"Issuer"},"issuer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Id"},"issuer_vat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Vat"},"recipient":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient"},"recipient_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Id"},"amount_without_tax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amount Without Tax"},"amount_with_tax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amount With Tax"},"currency":{"type":"string","title":"Currency"},"original_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Currency"},"original_amount_with_tax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Amount With Tax"},"original_amount_without_tax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Amount Without Tax"},"original_tax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Tax"},"issue_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Issue Date"},"payment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Type"},"services":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Services"},"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iban"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","invoice_number","type","issuer","issuer_id","issuer_vat","recipient","recipient_id","amount_without_tax","amount_with_tax","currency","issue_date","payment_type","services","iban","created_at"],"title":"InvoiceResponse"},"InvoiceResult":{"properties":{"id":{"type":"integer","title":"Id"},"kind":{"type":"string","const":"invoice","title":"Kind"},"status":{"type":"string","title":"Status"},"number":{"type":"string","title":"Number"},"issue_date":{"type":"string","format":"date","title":"Issue Date"},"event_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Event Date"},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due Date"},"currency":{"type":"string","title":"Currency"},"subtotal":{"type":"string","title":"Subtotal"},"vat_total":{"type":"string","title":"Vat Total"},"total":{"type":"string","title":"Total"},"pdf_url":{"type":"string","title":"Pdf Url"}},"additionalProperties":false,"type":"object","required":["id","kind","status","number","issue_date","event_date","due_date","currency","subtotal","vat_total","total","pdf_url"],"title":"InvoiceResult"},"Language":{"type":"string","enum":["bg","bg-en"],"title":"Language"},"PaginationResponse":{"properties":{"page":{"type":"integer","title":"Page"},"per_page":{"type":"integer","title":"Per Page"},"total":{"type":"integer","title":"Total"},"total_pages":{"type":"integer","title":"Total Pages"}},"type":"object","required":["page","per_page","total","total_pages"],"title":"PaginationResponse"},"PaymentMethod":{"type":"string","enum":["bank","cash","card","other"],"title":"PaymentMethod"},"RevenueKind":{"type":"string","enum":["services","goods"],"title":"RevenueKind"},"SalesApiErrorResponse":{"properties":{"code":{"type":"string","title":"Code"},"detail":{"type":"string","title":"Detail"},"fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Fields"}},"additionalProperties":false,"type":"object","required":["code","detail","fields"],"title":"SalesApiErrorResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"sales-invoices","description":"Issue, email and retrieve app-issued sales invoices using explicit sales permissions."},{"name":"invoices","description":"Read uploaded purchase invoices using legacy:access or an existing company OAuth credential."}],"externalDocs":{"description":"Customer integration guide","url":"https://web.invoicehub.work/en/api-guide"}}