> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/rest-api/invoices.md).

# Invoices

Create, read, update, and delete operations for invoices.

## GET /invoices

> List invoices (paginated)

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Page number (>=1)","required":false,"schema":{"type":"integer","default":1,"minimum":1}},"LimitParam":{"name":"limit","in":"query","description":"Page size (1–200)","required":false,"schema":{"type":"integer","default":25,"maximum":200,"minimum":1}}},"schemas":{"InvoiceListResponse":{"description":"Paginated list of invoices","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"meta":{"$ref":"#/components/schemas/MetaWithPagination"}},"type":"object"},"Invoice":{"description":"Invoice with buyer, seller, receiver data and invoice items","required":["invoiceId","invoiceNo","invoiceFullNo","invoiceType","buyer","seller","receiver","invoiceItems","paymentType","paymentStatus","issueDate","saleDate","paymentDate","currency"],"properties":{"invoiceId":{"type":"integer"},"invoiceNo":{"type":"integer"},"invoiceFullNo":{"type":"string"},"format":{"type":"string"},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice (default), PENDING_KSEF=Pending KSeF submission (readonly), SENT_KSEF=Sent to KSeF system (readonly)","type":"string","enum":["DRAFT","ISSUED","PENDING_KSEF","SENT_KSEF"]},"ksefId":{"description":"KSeF (Polish National e-Invoice System) unique identifier. Readonly - set automatically by backend when invoice is sent to KSeF.","type":"string","nullable":true},"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice, 4=Correction Invoice, 5=VAT Exempt Invoice, 6=Advance Receipt, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"buyer":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF: NIP=Polish tax ID (10-digit), VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier (countryCode optional), NONE=No identifier (BrakID)","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code (e.g. PL, DE, CZ). Required when identifierType=VAT_UE, optional for OTHER.","type":"string","nullable":true}},"type":"object"},"seller":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object"},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF: NIP=Polish tax ID, VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object"},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Used only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis ID or custom text. Only present if invoice has items with 'zw' VAT rate.","type":"string","nullable":true},"exchangeRate":{"description":"Currency exchange rate to PLN. Automatically fetched when invoice currency is not PLN and user is connected to KSeF. Readonly.","type":"number","format":"float","nullable":true},"prepaymentValue":{"description":"For invoiceType=8 (KSeF Advance Invoice): advance payment gross amount (must be > 0, cannot exceed total order value). For invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay after advance payments (must be >= 0). Not used for other invoice types.","type":"number","format":"float","nullable":true},"addDate":{"type":"string","format":"date-time"},"editDate":{"type":"string","format":"date-time"}},"type":"object"},"InvoiceItem":{"description":"Invoice item - single position on invoice","required":["invoiceId","positionId","userId","status","name","grossUnitPrice","quantity","unit","rate","symbol"],"properties":{"invoiceId":{"type":"integer"},"positionId":{"type":"integer"},"userId":{"type":"integer"},"status":{"type":"integer","enum":[0,1]},"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"MetaWithPagination":{"description":"Pagination parameters with request tracking in list responses.","required":["totalItems","currentPage","totalPages","itemsPerPage","ruid"],"properties":{"totalItems":{"type":"integer","minimum":0},"currentPage":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0},"itemsPerPage":{"type":"integer","minimum":1},"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/invoices":{"get":{"tags":["invoices"],"summary":"List invoices (paginated)","operationId":"listInvoices","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"invoiceType","in":"query","description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice, 4=VAT Exempt Invoice, 5=Advance Receipt, 6=Correction VAT, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","required":false,"schema":{"type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]}},{"name":"search","in":"query","description":"Search in taxId, company name or invoice number","required":false,"schema":{"type":"string","maxLength":255}},{"name":"from","in":"query","description":"Filter by issue date from (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Filter by issue date to (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},{"name":"reservationId","in":"query","description":"Filter by reservation ID","required":false,"schema":{"type":"integer","minimum":1}},{"name":"lastEdit","in":"query","description":"Filter: edited since Unix timestamp","required":false,"schema":{"type":"integer","minimum":1}},{"name":"orderBy","in":"query","description":"Sort field","required":false,"schema":{"type":"string","default":"invoiceId","enum":["invoiceId","invoiceNo","issueDate","addDate","editDate"]}},{"name":"orderType","in":"query","description":"Sort direction","required":false,"schema":{"type":"string","default":"DESC","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"Invoice list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```

## POST /invoices

> Create invoice

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"InvoiceCreateRequest":{"description":"Create invoice request payload","required":["invoiceType","buyer","seller","paymentType","paymentStatus","issueDate","saleDate","paymentDate","currency","invoiceItems"],"properties":{"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice (blocked when KSeF connected), 4=VAT Exempt Invoice, 5=Advance Receipt, 6=Correction VAT, 7=Correction Receipt, 8=KSeF Advance Invoice (required when KSeF connected; invoiceItems = full order, prepaymentValue = advance payment amount), 9=KSeF Settlement Invoice (requires KSeF connection; settles KSeF advance invoices type 8 with ksefId; prepaymentValue = remaining amount to pay; prepaymentId = array of type 8 invoice IDs with ksefId assigned), 10=KSeF Correction Invoice (requires KSeF connection; corrects VAT invoices via KSeF; correctionId = original invoice ID), 11=KSeF Advance Correction Invoice (requires KSeF connection; corrects KSeF advance invoices type 8; correctionId = type 8 invoice ID), 12=KSeF Settlement Correction Invoice (requires KSeF connection; corrects KSeF settlement invoices type 9; correctionId = type 9 invoice ID)","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"format":{"type":"string"},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice (default). Note: PENDING_KSEF and SENT_KSEF can only be set by backend KSeF service.","type":"string","enum":["DRAFT","ISSUED"]},"buyer":{"required":["companyName","address","taxId"],"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF XML. Default: NIP. NIP=Polish 10-digit tax ID, VAT_UE=EU VAT number (countryCode required), OTHER=Foreign/other ID (countryCode optional), NONE=No identifier (BrakID in KSeF)","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code. Required when identifierType=VAT_UE, optional for OTHER.","type":"string","nullable":true}},"type":"object"},"seller":{"required":["companyName","address","taxId"],"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object"},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF XML. NIP=Polish tax ID, VAT_UE=EU VAT number (countryCode required), OTHER=Foreign/other ID, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object","nullable":true},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemCreateRequest"},"minItems":1},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Required only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML. Ignored for non-correction invoice types.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"customNumber":{"description":"Custom invoice number, if not provided - auto generated","type":"integer","nullable":true},"prepaymentId":{"type":"array","items":{"type":"integer"},"nullable":true},"correctionId":{"type":"integer","nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis - REQUIRED when invoice contains items with 'zw' (VAT exempt) rate. For Polish invoices only. Can be either: (1) Predefined ID: 'art43_1' (Zwolnienie ze względu na rodzaj prowadzonej działalności - art. 43 ust. 1 ustawy o VAT, KSeF: P_19A), 'art113' (Zwolnienie ze względu na nieprzekroczenie 200 000 PLN obrotu - art. 113 ust. 1 i 9 ustawy o VAT, KSeF: P_19A), 'art82_3' (Zwolnienie na mocy rozporządzenia MF - art. 82 ust. 3 ustawy o VAT, KSeF: P_19A), 'directive' (Zwolnienie art. 132 ust. 1 lub art. 135 ust. 1 Dyrektywy 2006/112/WE, KSeF: P_19B); OR (2) Custom text (minimum 10 characters) - will be mapped to KSeF field P_19A","type":"string","nullable":true},"prepaymentValue":{"description":"REQUIRED for invoiceType=8 (KSeF Advance Invoice): advance payment gross amount, must be > 0 and cannot exceed total gross of invoiceItems. REQUIRED for invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay after advance payments, must be >= 0. For type 8, invoiceItems = full order value, prepaymentValue = advance amount. For type 9, invoiceItems = full order value, prepaymentValue = remaining amount to pay (kwota pozostała do zapłaty).","type":"number","format":"float","nullable":true}},"type":"object"},"InvoiceItemCreateRequest":{"description":"Invoice item create request","required":["name","grossUnitPrice","quantity","unit","rate","symbol"],"properties":{"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"InvoiceCreateResponse":{"description":"Created invoice response with Location header","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Invoice"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"Invoice":{"description":"Invoice with buyer, seller, receiver data and invoice items","required":["invoiceId","invoiceNo","invoiceFullNo","invoiceType","buyer","seller","receiver","invoiceItems","paymentType","paymentStatus","issueDate","saleDate","paymentDate","currency"],"properties":{"invoiceId":{"type":"integer"},"invoiceNo":{"type":"integer"},"invoiceFullNo":{"type":"string"},"format":{"type":"string"},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice (default), PENDING_KSEF=Pending KSeF submission (readonly), SENT_KSEF=Sent to KSeF system (readonly)","type":"string","enum":["DRAFT","ISSUED","PENDING_KSEF","SENT_KSEF"]},"ksefId":{"description":"KSeF (Polish National e-Invoice System) unique identifier. Readonly - set automatically by backend when invoice is sent to KSeF.","type":"string","nullable":true},"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice, 4=Correction Invoice, 5=VAT Exempt Invoice, 6=Advance Receipt, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"buyer":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF: NIP=Polish tax ID (10-digit), VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier (countryCode optional), NONE=No identifier (BrakID)","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code (e.g. PL, DE, CZ). Required when identifierType=VAT_UE, optional for OTHER.","type":"string","nullable":true}},"type":"object"},"seller":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object"},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF: NIP=Polish tax ID, VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object"},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Used only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis ID or custom text. Only present if invoice has items with 'zw' VAT rate.","type":"string","nullable":true},"exchangeRate":{"description":"Currency exchange rate to PLN. Automatically fetched when invoice currency is not PLN and user is connected to KSeF. Readonly.","type":"number","format":"float","nullable":true},"prepaymentValue":{"description":"For invoiceType=8 (KSeF Advance Invoice): advance payment gross amount (must be > 0, cannot exceed total order value). For invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay after advance payments (must be >= 0). Not used for other invoice types.","type":"number","format":"float","nullable":true},"addDate":{"type":"string","format":"date-time"},"editDate":{"type":"string","format":"date-time"}},"type":"object"},"InvoiceItem":{"description":"Invoice item - single position on invoice","required":["invoiceId","positionId","userId","status","name","grossUnitPrice","quantity","unit","rate","symbol"],"properties":{"invoiceId":{"type":"integer"},"positionId":{"type":"integer"},"userId":{"type":"integer"},"status":{"type":"integer","enum":[0,1]},"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem400":{"description":"Request syntax/format error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"400 Bad Request","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/invoices":{"post":{"tags":["invoices"],"summary":"Create invoice","operationId":"createInvoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreateRequest"}}}},"responses":{"201":{"description":"Created","headers":{"Location":{"description":"URL of the new invoice","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreateResponse"}}}},"400":{"description":"Invalid data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```

## GET /invoices/{id}

> Get invoice by ID

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"InvoiceResponse":{"description":"Single invoice response","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Invoice"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"Invoice":{"description":"Invoice with buyer, seller, receiver data and invoice items","required":["invoiceId","invoiceNo","invoiceFullNo","invoiceType","buyer","seller","receiver","invoiceItems","paymentType","paymentStatus","issueDate","saleDate","paymentDate","currency"],"properties":{"invoiceId":{"type":"integer"},"invoiceNo":{"type":"integer"},"invoiceFullNo":{"type":"string"},"format":{"type":"string"},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice (default), PENDING_KSEF=Pending KSeF submission (readonly), SENT_KSEF=Sent to KSeF system (readonly)","type":"string","enum":["DRAFT","ISSUED","PENDING_KSEF","SENT_KSEF"]},"ksefId":{"description":"KSeF (Polish National e-Invoice System) unique identifier. Readonly - set automatically by backend when invoice is sent to KSeF.","type":"string","nullable":true},"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice, 4=Correction Invoice, 5=VAT Exempt Invoice, 6=Advance Receipt, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"buyer":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF: NIP=Polish tax ID (10-digit), VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier (countryCode optional), NONE=No identifier (BrakID)","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code (e.g. PL, DE, CZ). Required when identifierType=VAT_UE, optional for OTHER.","type":"string","nullable":true}},"type":"object"},"seller":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object"},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF: NIP=Polish tax ID, VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object"},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Used only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis ID or custom text. Only present if invoice has items with 'zw' VAT rate.","type":"string","nullable":true},"exchangeRate":{"description":"Currency exchange rate to PLN. Automatically fetched when invoice currency is not PLN and user is connected to KSeF. Readonly.","type":"number","format":"float","nullable":true},"prepaymentValue":{"description":"For invoiceType=8 (KSeF Advance Invoice): advance payment gross amount (must be > 0, cannot exceed total order value). For invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay after advance payments (must be >= 0). Not used for other invoice types.","type":"number","format":"float","nullable":true},"addDate":{"type":"string","format":"date-time"},"editDate":{"type":"string","format":"date-time"}},"type":"object"},"InvoiceItem":{"description":"Invoice item - single position on invoice","required":["invoiceId","positionId","userId","status","name","grossUnitPrice","quantity","unit","rate","symbol"],"properties":{"invoiceId":{"type":"integer"},"positionId":{"type":"integer"},"userId":{"type":"integer"},"status":{"type":"integer","enum":[0,1]},"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem404":{"description":"Resource specified in the request was not found.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"404 Not Found","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]}}},"paths":{"/invoices/{id}":{"get":{"tags":["invoices"],"summary":"Get invoice by ID","operationId":"getInvoice","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem404"}}}}}}}}}
```

## DELETE /invoices/{id}

> Delete invoice

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem404":{"description":"Resource specified in the request was not found.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"404 Not Found","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]}}},"paths":{"/invoices/{id}":{"delete":{"tags":["invoices"],"summary":"Delete invoice","operationId":"deleteInvoice","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Deleted","headers":{"RUID":{"description":"Request unique identifier","required":true,"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem404"}}}}}}}}}
```

## PATCH /invoices/{id}

> Update invoice

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"InvoiceUpdateRequest":{"description":"Update invoice request payload - all fields optional","properties":{"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice (blocked when KSeF connected), 4=VAT Exempt Invoice, 5=Advance Receipt, 6=Correction VAT, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice. Note: Cannot update invoices with PENDING_KSEF or SENT_KSEF status (will return 422 error).","type":"string","enum":["DRAFT","ISSUED"]},"buyer":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF XML. NIP=Polish 10-digit tax ID, VAT_UE=EU VAT number (countryCode required), OTHER=Foreign/other ID, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","type":"string","nullable":true}},"type":"object","nullable":true},"seller":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object","nullable":true},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF XML.","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object","nullable":true},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItemUpdateRequest"},"nullable":true},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Used only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"prepaymentId":{"type":"array","items":{"type":"integer"},"nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis - REQUIRED when invoice contains items with 'zw' (VAT exempt) rate. For Polish invoices only. Can be either: (1) Predefined ID: 'art43_1' (Zwolnienie ze względu na rodzaj prowadzonej działalności - art. 43 ust. 1 ustawy o VAT, KSeF: P_19A), 'art113' (Zwolnienie ze względu na nieprzekroczenie 200 000 PLN obrotu - art. 113 ust. 1 i 9 ustawy o VAT, KSeF: P_19A), 'art82_3' (Zwolnienie na mocy rozporządzenia MF - art. 82 ust. 3 ustawy o VAT, KSeF: P_19A), 'directive' (Zwolnienie art. 132 ust. 1 lub art. 135 ust. 1 Dyrektywy 2006/112/WE, KSeF: P_19B); OR (2) Custom text (minimum 10 characters) - will be mapped to KSeF field P_19A","type":"string","nullable":true},"prepaymentValue":{"description":"REQUIRED for invoiceType=8 (KSeF Advance Invoice): advance payment gross amount, must be > 0. REQUIRED for invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay (kwota pozostała do zapłaty), must be >= 0.","type":"number","format":"float","nullable":true}},"type":"object"},"InvoiceItemUpdateRequest":{"description":"Invoice item update request","properties":{"positionId":{"description":"If provided - updates existing item, if null - creates new item","type":"integer","nullable":true},"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"InvoiceResponse":{"description":"Single invoice response","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Invoice"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"Invoice":{"description":"Invoice with buyer, seller, receiver data and invoice items","required":["invoiceId","invoiceNo","invoiceFullNo","invoiceType","buyer","seller","receiver","invoiceItems","paymentType","paymentStatus","issueDate","saleDate","paymentDate","currency"],"properties":{"invoiceId":{"type":"integer"},"invoiceNo":{"type":"integer"},"invoiceFullNo":{"type":"string"},"format":{"type":"string"},"extraChar":{"type":"string"},"invoiceStatus":{"description":"Invoice status: DRAFT=Editable draft, ISSUED=Issued invoice (default), PENDING_KSEF=Pending KSeF submission (readonly), SENT_KSEF=Sent to KSeF system (readonly)","type":"string","enum":["DRAFT","ISSUED","PENDING_KSEF","SENT_KSEF"]},"ksefId":{"description":"KSeF (Polish National e-Invoice System) unique identifier. Readonly - set automatically by backend when invoice is sent to KSeF.","type":"string","nullable":true},"invoiceType":{"description":"Invoice type: 0=Standard Invoice, 1=VAT Invoice, 2=Pro Forma Invoice, 3=Advance Invoice, 4=Correction Invoice, 5=VAT Exempt Invoice, 6=Advance Receipt, 7=Correction Receipt, 8=KSeF Advance Invoice, 9=KSeF Settlement Invoice, 10=KSeF Correction Invoice, 11=KSeF Advance Correction Invoice, 12=KSeF Settlement Correction Invoice","type":"integer","enum":[0,1,2,3,4,5,6,7,8,9,10,11,12]},"buyer":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Buyer identifier type for KSeF: NIP=Polish tax ID (10-digit), VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier (countryCode optional), NONE=No identifier (BrakID)","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"]},"countryCode":{"description":"ISO 3166-1 alpha-2 country code (e.g. PL, DE, CZ). Required when identifierType=VAT_UE, optional for OTHER.","type":"string","nullable":true}},"type":"object"},"seller":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"bankNo":{"type":"string"}},"type":"object"},"receiver":{"properties":{"companyName":{"type":"string"},"address":{"type":"string"},"taxId":{"type":"string"},"identifierType":{"description":"Receiver identifier type for KSeF: NIP=Polish tax ID, VAT_UE=EU VAT number (requires countryCode), OTHER=Foreign/other identifier, NONE=No identifier","type":"string","enum":["NIP","VAT_UE","OTHER","NONE"],"nullable":true},"countryCode":{"description":"ISO 3166-1 alpha-2 country code for receiver.","type":"string","nullable":true},"bankNo":{"type":"string"}},"type":"object"},"invoiceItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"paymentType":{"description":"Payment method: 0=None, 1=Cash, 2=Bank Transfer, 3=Credit Card, 4=Virtual Card, 5=Online Payment","type":"integer","enum":[0,1,2,3,4,5]},"paymentStatus":{"description":"Payment status: 0=Unpaid, 1=Paid","type":"integer","enum":[0,1]},"issueDate":{"type":"string","format":"date"},"saleDate":{"type":"string","format":"date"},"town":{"type":"string"},"paymentDate":{"type":"string","format":"date"},"currency":{"type":"string"},"additionalInfo":{"type":"string","nullable":true},"correctionReason":{"description":"Reason for correction. Used only for correction invoice types (6, 10, 11, 12). Sent to KSeF as PrzyczynaKorekty in the FA(3) XML.","type":"string","maxLength":1024,"nullable":true},"personCollect":{"type":"string","nullable":true},"personIssue":{"type":"string","nullable":true},"clientId":{"type":"integer","nullable":true},"reservationId":{"type":"integer","nullable":true},"exemptionBasis":{"description":"Tax exemption legal basis ID or custom text. Only present if invoice has items with 'zw' VAT rate.","type":"string","nullable":true},"exchangeRate":{"description":"Currency exchange rate to PLN. Automatically fetched when invoice currency is not PLN and user is connected to KSeF. Readonly.","type":"number","format":"float","nullable":true},"prepaymentValue":{"description":"For invoiceType=8 (KSeF Advance Invoice): advance payment gross amount (must be > 0, cannot exceed total order value). For invoiceType=9 (KSeF Settlement Invoice): remaining amount to pay after advance payments (must be >= 0). Not used for other invoice types.","type":"number","format":"float","nullable":true},"addDate":{"type":"string","format":"date-time"},"editDate":{"type":"string","format":"date-time"}},"type":"object"},"InvoiceItem":{"description":"Invoice item - single position on invoice","required":["invoiceId","positionId","userId","status","name","grossUnitPrice","quantity","unit","rate","symbol"],"properties":{"invoiceId":{"type":"integer"},"positionId":{"type":"integer"},"userId":{"type":"integer"},"status":{"type":"integer","enum":[0,1]},"name":{"type":"string"},"grossUnitPrice":{"type":"number","format":"float"},"quantity":{"type":"number","format":"float"},"unit":{"type":"string"},"rate":{"type":"string"},"symbol":{"type":"string"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem400":{"description":"Request syntax/format error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"400 Bad Request","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem404":{"description":"Resource specified in the request was not found.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"404 Not Found","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/invoices/{id}":{"patch":{"tags":["invoices"],"summary":"Update invoice","operationId":"updateInvoice","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpdateRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"400":{"description":"Invalid data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem404"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```

## Send invoice to KSeF

> Manually sends an invoice to KSeF (Krajowy System e-Faktur) and polls for acceptance status. The endpoint sends the invoice, waits up to \~10 seconds for KSeF to process it (2 polling attempts × 5s), and returns the result. If KSeF has not processed the invoice within that time, a 202 response is returned – a background worker will complete the status check.

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"invoices","description":"Create, read, update, and delete operations for invoices."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/invoices/{id}/send-ksef":{"post":{"tags":["invoices"],"summary":"Send invoice to KSeF","description":"Manually sends an invoice to KSeF (Krajowy System e-Faktur) and polls for acceptance status. The endpoint sends the invoice, waits up to ~10 seconds for KSeF to process it (2 polling attempts × 5s), and returns the result. If KSeF has not processed the invoice within that time, a 202 response is returned – a background worker will complete the status check.","operationId":"sendInvoiceToKsef","parameters":[{"name":"id","in":"path","description":"Invoice ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Invoice accepted by KSeF","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"success":{"type":"boolean"},"ksefId":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"},"invoiceId":{"type":"integer"},"sessionReferenceNumber":{"type":"string"},"durationMs":{"type":"integer"}},"type":"object"},"meta":{"properties":{"ruid":{"type":"string"}},"type":"object"}},"type":"object"}}}},"202":{"description":"Invoice sent but not yet processed by KSeF – background worker will complete","content":{"application/json":{"schema":{"properties":{"data":{"properties":{"success":{"type":"boolean"},"ksefId":{"type":"string","nullable":true},"status":{"type":"string"},"message":{"type":"string"},"invoiceId":{"type":"integer"},"sessionReferenceNumber":{"type":"string"},"durationMs":{"type":"integer"}},"type":"object"},"meta":{"properties":{"ruid":{"type":"string"}},"type":"object"}},"type":"object"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"422":{"description":"Validation error (invoice not eligible, already sent, rejected by KSeF, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mobile-calendar.gitbook.io/v1/rest-api/invoices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.