{ "openapi": "3.1.0", "x-stoplight": { "id": "vmkem8axekx2a" }, "info": { "title": "OpenAPI", "version": "1.0", "summary": "OpenApi", "contact": { "name": "Altera Support", "url": "https://altera.co", "email": "wsparcie@altera.co" }, "description": "", "license": { "url": "https://altera.co/regulamin", "name": "Terms of services for Altera.app" } }, "servers": [ { "url": "https://api.altera.co", "description": "Production endpoint (proxied)" } ], "paths": { "/sales": { "parameters": [], "get": { "summary": "List available invoices", "operationId": "get-sales-list", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "invoices": [ { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2070, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "2/10/2022", "year": 2022, "month": 10, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": true, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "CAD", "exchangeRate": 3.4171, "exchangeRateDate": "2022-06-08T00:00:00.000Z", "vatPLN": 6724.85, "issueDate": "2022-10-24T00:00:00.000Z", "saleDate": "2022-10-24T00:00:00.000Z", "uploadDate": "2022-10-24T06:49:16.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "\"copy General\" sp. z o.o.", "contractorId": 41, "taxIdentificationNumber": "5260004434", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "CAD", "city": "Warszawa", "street": "ul. Usypiskowa", "houseNumber": "1", "flatNumber": "2", "postCode": "02-386", "email": "", "phoneNumber": "", "areaNumber": "" }, "buyer": { "contractorName": "\"copy General\" sp. z o.o.", "contractorId": 41, "taxIdentificationNumber": "5260004434", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "CAD", "city": "Warszawa", "street": "ul. Usypiskowa", "houseNumber": "1", "flatNumber": "2", "postCode": "02-386", "email": "", "phoneNumber": "", "areaNumber": "" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-11-07T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2069, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/10/2022", "year": 2022, "month": 10, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 1500, "grossPrice": 1845, "currency": "PLN", "exchangeRate": 1, "vatPLN": 345, "issueDate": "2022-10-11T00:00:00.000Z", "saleDate": "2022-10-11T00:00:00.000Z", "uploadDate": "2022-10-11T06:40:16.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Test działania", "contractorId": 34, "taxIdentificationNumber": "1589651654", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "postCode": "62-156", "email": "sdafdaf@dafadfafd.co", "phoneNumber": "518 961 516", "areaNumber": "+58" }, "buyer": { "contractorName": "Test działania", "contractorId": 34, "taxIdentificationNumber": "1589651654", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "postCode": "62-156", "email": "sdafdaf@dafadfafd.co", "phoneNumber": "518 961 516", "areaNumber": "+58" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-25T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 17, "invoiceType": "SALES", "invoiceFormat": "FV %N/%M/%Y", "invoiceNumber": "1/1/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 609, "grossPrice": 749.07, "currency": "PLN", "exchangeRate": 1, "vatPLN": 140.07, "issueDate": "2022-09-21T00:00:00.000Z", "saleDate": "2022-09-21T00:00:00.000Z", "uploadDate": "2022-03-24T14:26:17.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Airgas, Inc.", "contractorId": 42, "taxIdentificationNumber": "9241211595", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Jandira", "street": "Opdi Manor", "houseNumber": "393", "flatNumber": "714", "postCode": "30-424", "email": "team@rose.com,test@gmail.com", "phoneNumber": "638207337", "areaNumber": "+48" }, "buyer": { "contractorName": "Airgas, Inc.", "contractorId": 42, "taxIdentificationNumber": "9241211595", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Jandira", "street": "Opdi Manor", "houseNumber": "393", "flatNumber": "714", "postCode": "30-424", "email": "team@rose.com,test@gmail.com", "phoneNumber": "638207337", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-21T00:00:00.000Z", "isSplitPayment": false, "isPaid": true, "bankAccountNumber": "11 1140 1231 2312 3123 1231 2312" }, "invoicePosition": [], "costCenterPerItem": false, "projects": [ { "tagId": 1, "name": "Nowe BOA", "enabled": true, "color": 4283215696 } ], "accounting": { "accountingDate": "2022-09-23T00:00:00.000Z", "receiptDate": "2022-09-23T00:00:00.000Z", "vatProcedures": [], "registrationPlate": "", "isSubjectToVat": true, "activeVat": true, "bufferOnly": false } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2061, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "2/9/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-09-20T00:00:00.000Z", "saleDate": "2022-09-20T00:00:00.000Z", "uploadDate": "2022-09-20T10:08:19.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-10T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true }, "unreadMessagesCount": 3 }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2060, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/9/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 1, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-09-20T00:00:00.000Z", "saleDate": "2022-09-20T00:00:00.000Z", "uploadDate": "2022-09-20T10:07:48.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-04T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2026, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/5/2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 86484600, "grossPrice": 93403368, "currency": "PLN", "exchangeRate": 1, "vatPLN": 6918768, "issueDate": "2022-05-26T00:00:00.000Z", "saleDate": "2022-05-26T00:00:00.000Z", "uploadDate": "2022-05-26T10:09:25.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Wrocław", "street": "ul. Grabarska", "houseNumber": "1", "flatNumber": "", "postCode": "50-079", "email": "", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Wrocław", "street": "ul. Grabarska", "houseNumber": "1", "flatNumber": "", "postCode": "50-079", "email": "", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-06-09T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": true, "basicInformation": { "invoiceId": 1989, "invoiceType": "INTERIM_FINAL", "invoiceFormat": "ZK %N %M %Y", "invoiceNumber": "ZK 1 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 400, "grossPrice": 432, "currency": "PLN", "exchangeRate": 1, "vatPLN": 32, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:40:22.000Z", "relatedInvoicesIds": [ 1988, 1987 ], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [ "ALK-123", "312" ], "isSubjectToVat": true, "activeVat": true, "bufferOnly": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1988, "invoiceType": "INTERIM", "invoiceFormat": "ZAL %N %M %Y", "invoiceNumber": "ZAL 2 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": true, "isRelatedTo": 1989, "netPrice": 44000, "grossPrice": 47520, "currency": "PLN", "exchangeRate": 1, "vatPLN": 3520, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:15:25.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1987, "invoiceType": "INTERIM", "invoiceFormat": "ZAL %N %M %Y", "invoiceNumber": "ZAL 1 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": true, "isRelatedTo": 1989, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:03:52.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1992, "invoiceType": "CORRECTION", "invoiceFormat": "KOR %N/%Y", "invoiceNumber": "KOR 2/2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 2, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 92, "grossPrice": 159.36, "currency": "PLN", "exchangeRate": 1, "vatPLN": 67.36, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:57:03.000Z", "relatedInvoicesIds": [ 23 ], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Zielonka", "street": "ul. Tropikalna", "houseNumber": "7", "flatNumber": "4", "postCode": "86-005", "email": "kontakt@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Zielonka", "street": "ul. Tropikalna", "houseNumber": "7", "flatNumber": "4", "postCode": "86-005", "email": "kontakt@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "projects": [ { "tagId": 1, "name": "Nowe BOA", "enabled": true, "color": 4283215696 }, { "tagId": 2, "name": "Super Altera", "enabled": true, "color": 4283080899 } ], "correctionReason": "Zmiana adresu, ilości godzin, stawki VAT", "accounting": { "vatProcedures": [] } } ], "pagesAmount": "2", "sumGross": "93671661.302800", "sumNet": "86730390.570000" } }, "properties": { "result": { "type": "string", "x-stoplight": { "id": "kor3uoxt05dsr" }, "default": "OK", "example": "OK" }, "data": { "type": "object", "x-stoplight": { "id": "e3px74375kmho" }, "properties": { "invoices": { "type": "array", "x-stoplight": { "id": "ocnng2uxcafzj" }, "items": { "$ref": "#/components/schemas/Invoice", "x-stoplight": { "id": "230zo9wzs81bm" } } }, "pagesAmount": { "type": "string", "x-stoplight": { "id": "gtr46nxmtg8eo" } }, "sumGross": { "type": "string", "x-stoplight": { "id": "ybp3vl8fvc81p" } }, "sumNet": { "type": "string", "x-stoplight": { "id": "omw18kkmele90" } } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "invoices": [ { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2070, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "2/10/2022", "year": 2022, "month": 10, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": true, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "CAD", "exchangeRate": 3.4171, "exchangeRateDate": "2022-06-08T00:00:00.000Z", "vatPLN": 6724.85, "issueDate": "2022-10-24T00:00:00.000Z", "saleDate": "2022-10-24T00:00:00.000Z", "uploadDate": "2022-10-24T06:49:16.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "\"copy General\" sp. z o.o.", "contractorId": 41, "taxIdentificationNumber": "5260004434", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "CAD", "city": "Warszawa", "street": "ul. Usypiskowa", "houseNumber": "1", "flatNumber": "2", "postCode": "02-386", "email": "", "phoneNumber": "", "areaNumber": "" }, "buyer": { "contractorName": "\"copy General\" sp. z o.o.", "contractorId": 41, "taxIdentificationNumber": "5260004434", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "CAD", "city": "Warszawa", "street": "ul. Usypiskowa", "houseNumber": "1", "flatNumber": "2", "postCode": "02-386", "email": "", "phoneNumber": "", "areaNumber": "" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-11-07T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2069, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/10/2022", "year": 2022, "month": 10, "invoiceNumberInPeriod": 1, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 1500, "grossPrice": 1845, "currency": "PLN", "exchangeRate": 1, "vatPLN": 345, "issueDate": "2022-10-11T00:00:00.000Z", "saleDate": "2022-10-11T00:00:00.000Z", "uploadDate": "2022-10-11T06:40:16.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Test działania", "contractorId": 34, "taxIdentificationNumber": "1589651654", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "postCode": "62-156", "email": "sdafdaf@dafadfafd.co", "phoneNumber": "518 961 516", "areaNumber": "+58" }, "buyer": { "contractorName": "Test działania", "contractorId": 34, "taxIdentificationNumber": "1589651654", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "postCode": "62-156", "email": "sdafdaf@dafadfafd.co", "phoneNumber": "518 961 516", "areaNumber": "+58" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-25T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 17, "invoiceType": "SALES", "invoiceFormat": "FV %N/%M/%Y", "invoiceNumber": "1/1/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 609, "grossPrice": 749.07, "currency": "PLN", "exchangeRate": 1, "vatPLN": 140.07, "issueDate": "2022-09-21T00:00:00.000Z", "saleDate": "2022-09-21T00:00:00.000Z", "uploadDate": "2022-03-24T14:26:17.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Airgas, Inc.", "contractorId": 42, "taxIdentificationNumber": "9241211595", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Jandira", "street": "Opdi Manor", "houseNumber": "393", "flatNumber": "714", "postCode": "30-424", "email": "team@rose.com,test@gmail.com", "phoneNumber": "638207337", "areaNumber": "+48" }, "buyer": { "contractorName": "Airgas, Inc.", "contractorId": 42, "taxIdentificationNumber": "9241211595", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Jandira", "street": "Opdi Manor", "houseNumber": "393", "flatNumber": "714", "postCode": "30-424", "email": "team@rose.com,test@gmail.com", "phoneNumber": "638207337", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-21T00:00:00.000Z", "isSplitPayment": false, "isPaid": true, "bankAccountNumber": "11 1140 1231 2312 3123 1231 2312" }, "invoicePosition": [], "costCenterPerItem": false, "projects": [ { "tagId": 1, "name": "Nowe BOA", "enabled": true, "color": 4283215696 } ], "accounting": { "accountingDate": "2022-09-23T00:00:00.000Z", "receiptDate": "2022-09-23T00:00:00.000Z", "vatProcedures": [], "registrationPlate": "", "isSubjectToVat": true, "activeVat": true, "bufferOnly": false } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2061, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "2/9/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-09-20T00:00:00.000Z", "saleDate": "2022-09-20T00:00:00.000Z", "uploadDate": "2022-09-20T10:08:19.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-10T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true }, "unreadMessagesCount": 3 }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2060, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/9/2022", "year": 2022, "month": 9, "invoiceNumberInPeriod": 1, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-09-20T00:00:00.000Z", "saleDate": "2022-09-20T00:00:00.000Z", "uploadDate": "2022-09-20T10:07:48.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Niemcz", "street": "ul. Alpejczyków", "houseNumber": "13", "flatNumber": "", "postCode": "86-032", "email": "kontakt@altera.co,l.kowalski@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-10-04T00:00:00.000Z", "isSplitPayment": true, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 2026, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "invoiceNumber": "1/5/2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 86484600, "grossPrice": 93403368, "currency": "PLN", "exchangeRate": 1, "vatPLN": 6918768, "issueDate": "2022-05-26T00:00:00.000Z", "saleDate": "2022-05-26T00:00:00.000Z", "uploadDate": "2022-05-26T10:09:25.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Wrocław", "street": "ul. Grabarska", "houseNumber": "1", "flatNumber": "", "postCode": "50-079", "email": "", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Wrocław", "street": "ul. Grabarska", "houseNumber": "1", "flatNumber": "", "postCode": "50-079", "email": "", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-06-09T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": true, "basicInformation": { "invoiceId": 1989, "invoiceType": "INTERIM_FINAL", "invoiceFormat": "ZK %N %M %Y", "invoiceNumber": "ZK 1 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 400, "grossPrice": 432, "currency": "PLN", "exchangeRate": 1, "vatPLN": 32, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:40:22.000Z", "relatedInvoicesIds": [ 1988, 1987 ], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [ "ALK-123", "312" ], "isSubjectToVat": true, "activeVat": true, "bufferOnly": true } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1988, "invoiceType": "INTERIM", "invoiceFormat": "ZAL %N %M %Y", "invoiceNumber": "ZAL 2 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": true, "isRelatedTo": 1989, "netPrice": 44000, "grossPrice": 47520, "currency": "PLN", "exchangeRate": 1, "vatPLN": 3520, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:15:25.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1987, "invoiceType": "INTERIM", "invoiceFormat": "ZAL %N %M %Y", "invoiceNumber": "ZAL 1 5 2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 1, "statusId": "SENT", "isReceipt": false, "isRelated": true, "isRelatedTo": 1989, "netPrice": 24600, "grossPrice": 26568, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1968, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:03:52.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "buyer": { "contractorName": "Alphamoon sp. z o.o.", "contractorId": 23, "taxIdentificationNumber": "8943079568", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Gruba", "street": "Fancy fancy", "houseNumber": "t12312", "flatNumber": "3412", "postCode": "52-341", "email": "affix@fix.pl", "phoneNumber": "", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "accounting": { "vatProcedures": [] } }, { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 1992, "invoiceType": "CORRECTION", "invoiceFormat": "KOR %N/%Y", "invoiceNumber": "KOR 2/2022", "year": 2022, "month": 5, "invoiceNumberInPeriod": 2, "statusId": "ISSUED", "isReceipt": false, "isRelated": false, "netPrice": 92, "grossPrice": 159.36, "currency": "PLN", "exchangeRate": 1, "vatPLN": 67.36, "issueDate": "2022-05-05T00:00:00.000Z", "saleDate": "2022-05-05T00:00:00.000Z", "uploadDate": "2022-05-05T12:57:03.000Z", "relatedInvoicesIds": [ 23 ], "priceTypeId": "NET" }, "contractor": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Zielonka", "street": "ul. Tropikalna", "houseNumber": "7", "flatNumber": "4", "postCode": "86-005", "email": "kontakt@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "buyer": { "contractorName": "Jakub Lankiewicz", "contractorId": 30, "taxIdentificationNumber": "5542878782", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Zielonka", "street": "ul. Tropikalna", "houseNumber": "7", "flatNumber": "4", "postCode": "86-005", "email": "kontakt@altera.co", "phoneNumber": "784038003", "areaNumber": "+48" }, "seller": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-05-19T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "13 1231 2312 3133 2131 1111 111" }, "invoicePosition": [], "costCenterPerItem": false, "projects": [ { "tagId": 1, "name": "Nowe BOA", "enabled": true, "color": 4283215696 }, { "tagId": 2, "name": "Super Altera", "enabled": true, "color": 4283080899 } ], "correctionReason": "Zmiana adresu, ilości godzin, stawki VAT", "accounting": { "vatProcedures": [] } } ], "pagesAmount": "2", "sumGross": "93671661.30", "sumNet": "86730390.57" } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Sales" ], "description": "Gets a list of invoices created in the system for your company.", "parameters": [ { "schema": { "type": "string", "default": "20", "enum": [ "10", "20", "50", "100" ] }, "in": "query", "name": "documentsPerPage", "description": "Defines the amount of invoices polled per page" }, { "schema": { "type": "string" }, "in": "query", "name": "pageNumber", "description": "Defines the page we want to poll" }, { "schema": { "type": "string", "enum": [ "INVOICE_NUMBER", "ISSUE_DATE", "SALE_DATE", "DUE_DATE", "AMOUNT_GROSS", "CONTRACTOR_NAME" ], "example": "ISSUE_DATE" }, "in": "query", "name": "sortBy" }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "example": "DESC" }, "in": "query", "name": "order" }, { "schema": { "type": "string" }, "in": "query", "name": "searchPhrase", "description": "Case-insensitive substring search over invoice number, buyer and seller names and tax IDs, registration plate, additionalDetails and invoice line product names. Internal debit-note metadata is excluded. This is free-text search, without external-reference uniqueness or an idempotency guarantee." }, { "schema": { "type": "string" }, "in": "query", "name": "contractorName" }, { "schema": { "type": "array", "enum": [ "SALES", "PRO_FORMA", "INTERIM", "INTERIM_FINAL", "CORRECTION" ], "example": "INTERIM,INTERIM_FINAL", "uniqueItems": true }, "in": "query", "name": "invoiceType", "style": "pipeDelimited" }, { "schema": { "type": "string", "enum": [ "PAID", "UNPAID", "OVERDUE" ], "example": "OVERDUE" }, "in": "query", "name": "paymentStatus" } ] } }, "/sales/invoice": { "post": { "summary": "Create/update invoice", "operationId": "post-sales", "responses": { "200": { "description": "Invoice saved. HTTP 200 confirms the save, not acceptance by KSeF. A failed immediate submission can be reported in optional data.ksefWarning, data.ksefErrorMessage and data.ksefReason fields.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "object", "properties": { "invoiceId": { "type": "number", "x-stoplight": { "id": "ng63zj0yg4qvv" }, "example": 12413 }, "ksefWarning": { "type": "string", "description": "Optional warning when immediate KSeF submission returns an unsuccessful result after the invoice was saved." }, "ksefErrorMessage": { "type": "string", "description": "Optional KSeF failure details. The invoice identified by invoiceId is already saved." }, "ksefReason": { "type": "string", "description": "Optional machine-readable reason, for example KSEF_SUBMISSION_FAILED or KSEF_PRIVATE_PERSON_SEND_DISABLED. Treat this as an open set of values." }, "statusId": { "type": "string", "description": "Current invoice status, also available in basicInformation.statusId." }, "ksefProcessing": { "type": "object", "description": "Optional KSeF processing result, as in the application save response.", "additionalProperties": true } }, "required": [ "invoiceId" ] } ] }, "warnings": { "type": "array", "description": "Optional non-blocking validation warnings.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "messagePL": { "type": "string" } } } } } }, { "$ref": "#/components/schemas/SuccessResponse", "x-stoplight": { "id": "wfh8d9tigst1z" } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Calendar date required": { "summary": "A date-time value rejected by strict date validation", "value": { "result": "Error", "errorMessage": "Enter a date in YYYY-MM-DD format, without a time or time zone, for example 2026-09-14.", "errorMessagePL": "Podaj datę w formacie RRRR-MM-DD, bez godziny i strefy czasowej, np. 2026-09-14.", "validationErrors": [ { "field": "basicInformation.issueDate", "message": "DATE_REQUIRES_LOCAL_DATE", "code": "DATE_REQUIRES_LOCAL_DATE" } ] } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Sales" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDtoIn" }, "examples": { "Example 1": { "value": { "modelType": "INVOICE", "override": false, "basicInformation": { "invoiceId": 2069, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "saleDate": "2022-10-11", "issueDate": "2022-10-11", "isReceipt": false, "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Test działania", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "city": "Bydgoszcz", "postCode": "62-156", "defaultCurrency": "PLN", "taxIdentificationNumber": "1589651654", "email": "testing@attention.please", "areaNumber": "+58", "phoneNumber": "518 961 516" }, "invoicePosition": [ { "productPosition": 0, "productName": "A", "positionType": "PRODUCT", "productCategory": "Health", "quantity": 10, "unit": "szt.", "priceType": null, "unitNetPrice": 150, "unitGrossPrice": 184.5, "vat": "23%", "pkwiu": "", "discount": "0", "deductions": false, "netPrice": "1500", "grossPrice": "1845", "invoiceProductId": 179 } ], "additionalDetails": "", "correctionReason": "", "payments": { "isPaid": false, "paymentMethod": "TRANSFER", "dueDate": "2022-10-25", "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516", "isSplitPayment": false }, "project": { "tagId": 161, "name": "Website implementation", "enabled": true, "color": 4286963618 } } } } } } }, "description": "Create or update a sales invoice. No idempotency key or company-unique externalId is supported. A timed-out request can already have saved the invoice; do not blindly repeat creation. The response returns the full saved invoice in data, including data.invoiceId and data.basicInformation.invoiceNumber, as in the application. It has no data.invoice wrapper. If reloading fails, the in-memory save result is returned." }, "parameters": [], "get": { "summary": "Get invoice data", "operationId": "get-sales-invoice", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "x-stoplight": { "id": "x9vn9vue45evr" }, "default": "OK" }, "data": { "type": "object", "x-stoplight": { "id": "xixugdj8mrgf2" }, "properties": { "invoice": { "$ref": "#/components/schemas/Invoice", "x-stoplight": { "id": "pgphon7hux58h" } }, "relatedInvoices": { "x-stoplight": { "id": "gpz22kpcomvca" }, "type": "array", "items": { "$ref": "#/components/schemas/Invoice", "x-stoplight": { "id": "ghiep02zumers" } } }, "defaults": { "type": "object", "x-stoplight": { "id": "scnla0pet85gk" } } } } } }, "examples": { "ProForma invoice": { "value": { "invoice": { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 118584, "invoiceType": "PRO_FORMA", "invoiceFormat": "PRO %N/%M/%Y", "invoiceNumber": "PRO 2/12/2022", "year": 2022, "month": 12, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 5760, "grossPrice": 7084.8, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1324.8, "issueDate": "2022-12-27T00:00:00.000Z", "saleDate": "2022-12-27T00:00:00.000Z", "uploadDate": "2022-12-27T08:52:22.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorName": "American Water Works Company, Inc.", "contractorId": 106, "taxIdentificationNumber": "3748414103", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Norton Canes", "street": "Dezsez View", "houseNumber": "396", "flatNumber": "154", "postCode": "97-135", "email": "went@able.com,fv@altera.co", "phoneNumber": "420577850", "areaNumber": "" }, "buyer": { "contractorName": "American Water Works Company, Inc.", "contractorId": 106, "taxIdentificationNumber": "3748414103", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Norton Canes", "street": "Dezsez View", "houseNumber": "396", "flatNumber": "154", "postCode": "97-135", "email": "went@able.com,fv@altera.co", "phoneNumber": "420577850", "areaNumber": "" }, "seller": { "taxIdentificationNumber": "1397887352", "contractorName": "Express Scripts Inc." }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2023-01-26T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "29 1111 1111 1111 1111 1111 1111" }, "invoicePosition": [ { "invoiceProductId": 57822, "positionType": "SERVICE", "productPosition": 0, "productCategory": "Facebook", "productCategoryId": 808, "productName": "Facebook Ads", "unit": "szt.", "unitNetPrice": 480, "unitGrossPrice": 590.4, "quantity": 12, "discount": 0, "vat": "23%", "priceNet": 5760, "netPrice": "5760", "vatAmt": 1324.8, "priceGross": 7084.8, "grossPrice": "7084.8", "gtu": "-", "deductions": true } ], "attachments": [ { "id": 41660, "fileName": "1_3_2022_1.pdf", "fileSize": 26968 } ], "costCenterPerItem": false, "accounting": { "vatProcedures": [], "isSubjectToVat": true, "activeVat": true } }, "defaults": { "suggestedProducts": [ { "productId": 780, "productName": "Facebook Ads" }, { "productId": 781, "productName": "Google Ads" }, { "productId": 779, "productName": "Prowadzenie FP" } ], "suggestedContractor": [ { "contractorId": 106, "tinCountry": "PL", "tin": "3748414103", "name": "American Water Works Company, Inc.", "contractorType": "COMPANY" }, { "contractorId": 104, "tinCountry": "PL", "tin": "4387990234", "name": "Whirlpool Corporation", "contractorType": "COMPANY" }, { "contractorId": 87, "tinCountry": "PL", "tin": "2231185845", "name": "World Fuel Services Corporation", "contractorType": "COMPANY" } ], "suggestedCategories": [ { "categoryName": "Google" }, { "categoryName": "Facebook" }, { "categoryName": "" } ], "suggestedReasons": [ "Brak adnotacji \"mechanizm podzielonej płatności\"", "Pomyłka w cenie", "Pomyłka w dacie", "Pomyłka w danych nabywcy", "Pomyłka w ilości", "Pomyłka w kwocie", "Pomyłka w opisie", "Pomyłka w stawce VAT", "Rabat", "Reklamacja", "Zwrot towaru / płatności" ], "units": [ "szt.", "godz", "dni", "kg", "mb" ], "pkwiu": [], "vatPcs": [ { "name": "23%", "value": 0.23 }, { "name": "8%", "value": 0.08 }, { "name": "5%", "value": 0.05 }, { "name": "zw", "nameEN": "exempt.", "value": 0 }, { "name": "np", "nameEN": "reverse charge", "value": 0 }, { "name": "0%", "value": 0 } ] }, "relatedInvoices": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Gateway authorization failure. Invalid keys or companies without OpenAPI access may return {\"message\":\"Forbidden\"}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "NOT_FOUND. Generic for missing, permanently deleted or other-company invoices; \"Invoice has been deleted\" only for a soft-deleted invoice owned by the key company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Sales" ], "description": "Retrieve data for a particular invoice available in the system\n\nThis endpoint may be used as a base for new invoice data that we wish to create based on a set of related invoices\n\nIf you wish to generate such object base you will need to provide both:\n* `related` parameter, listing the related invoices\n* `invoiceType` of the new invoice we wish to create\n\nThe return object will be a temporary invoice object you may further extend before saving it.\n\nMissing, permanently deleted and other-company invoices return 404 NOT_FOUND with a generic message. Own soft-deleted invoices return 404 NOT_FOUND with \"Invoice has been deleted\" and no invoice data. This applies to ref and related lookups. For CORRECTION, rows come from the referenced document, without applying later corrections automatically. Reference the previous correction to use its stored after-correction state.", "parameters": [ { "schema": { "type": "integer", "example": 36891 }, "in": "query", "name": "ref", "style": "form", "description": "InvoiceId identificator of the exact invoice we wish to retrieve" }, { "schema": { "type": "array", "example": "124,551" }, "in": "query", "name": "related", "description": "Comma delimited list of related invoices we wish to create a reference from. For CORRECTION this copies the referenced invoice, not the cumulative state after previous corrections. For a correction of a correction, pass the previous correction identifier.", "style": "pipeDelimited" }, { "schema": { "type": "string", "enum": [ "SALES", "CORRECTION", "INTERIM_FINAL" ], "example": "CORRECTION" }, "in": "query", "name": "invoiceType", "description": "Invoice type for the new invoice we wish to create based on related invoices" } ], "requestBody": { "content": {} } } }, "/export": { "get": { "summary": "Export invoice information", "tags": [ "Data export" ], "responses": { "200": { "description": "Returns a pre-signed URL with requested data file", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": "https://dev-altera-stack-support-tempdocsbucketd3373e14-oeryktk9o7gb.s3.eu-central-1.amazonaws.com/temporary/xlsx_mcuzbNcrwLYuRDwcm0WCMTJsO9viG6Bj?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAX3I6YW7PCNYSG7JM%2F20230316%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230316T072716Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEgaDGV1LWNlbnRyYWwtMSJHMEUCIHkqs6J0qIIVUjqbAO3WEHz8HHeDb8wvETRwgYQR65H9AiEAvRNEOKR4Rw%2BkQAfbvF2s3BwDfEyP91z%2F%2Bif1CcGsnvsqyAMIERACGgw1Mzk2MTk4MDEwNTQiDBs091tyAz3XSjWaFyqlA9E1HnxQmcbPEfmhl5O%2F5PkIBxKDazHkNnX2ZT58pGhH5iacYWo%2BilLvMBqYqLi%2F4%2FBDTR2HMyCCT1OHlkeaCMBewIc5SRjkBrHQUK0NZnan5ZeaYoCgOT7i1wbPfkBPHy4eVQWvWO%2FQ8fiMZWm3pfIj4%2Bug8mM5ngDjCJye8y8%2Fok5UKgpkmDa8sPKK5meEEtanFkH8meqP%2F30qedFeXHv5MKr947Yn8ZEr%2F86HTVXJo%2Fa%2FdHN8WhflvYMkGxUyqOV%2B0oNxSa%2FVg7b4XTcU3DpkHqBQvw%2FzmgpZvFp7a6cvZ8bFl5V6gqjWC5pvnvc0TTjwEtdZoxYSyqXJUcu1hQZnQoOGC9se632GGnueojyDn4JKPyRCsniOAM1PA7Ar7WzGuMgwfsQiA5vehV%2BHjA9ABvzN2WfRT1a0LZ8xdSAjlCQSb%2FPSjsZJgqQ%2FT2EROyME%2BEL9J0h4Exq1pCq%2Fnr0PSDKad4hTi9%2B65I6yooEcsqiAbw0KY%2Fs%2FnUB5On5F7IX575HIUhD8SxUC%2B%2BHSoT4GSIK568TExytKHIDgELBvd47cE7Aw0YnLoAY6ngHgq%2BqAOo3UjDPIrh5a5RQ%2BYWppNdzp%2BtffWesIVJTJQLNyJosoZN8t8dcU9IH9oS0t96JMnDLVA7CZa%2B0SdiHdURLFHrYqd6VECDgseRAGQXES2n2VIS9Z8ydWmsksPg%2FgNe0Gz3QkiPNI7ovOmdAAVn%2FC98fwsPQdD2sCGIPiFM%2Bbw74sJdY6IbCu%2Bz8OdRKjGWPUMQZ82QOo%2BKxUEQ%3D%3D&X-Amz-Signature=4aac18b700959c65d17198e2708db279273af00df4249b474cac1e3386227508&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3D%22Exported_Invoices_1678951636693.xlsx%22&response-content-type=application%2Foctet-stream" } }, "properties": { "result": { "type": "string", "example": "OK" }, "data": { "type": "string", "description": "Pre-signed URL that allows us to download the file requested" } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": "https://dev-altera-stack-support-tempdocsbucketd3373e14-oeryktk9o7gb.s3.eu-central-1.amazonaws.com/temporary/xlsx_mcuzbNcrwLYuRDwcm0WCMTJsO9viG6Bj?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAX3I6YW7PCNYSG7JM%2F20230316%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230316T072716Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEgaDGV1LWNlbnRyYWwtMSJHMEUCIHkqs6J0qIIVUjqbAO3WEHz8HHeDb8wvETRwgYQR65H9AiEAvRNEOKR4Rw%2BkQAfbvF2s3BwDfEyP91z%2F%2Bif1CcGsnvsqyAMIERACGgw1Mzk2MTk4MDEwNTQiDBs091tyAz3XSjWaFyqlA9E1HnxQmcbPEfmhl5O%2F5PkIBxKDazHkNnX2ZT58pGhH5iacYWo%2BilLvMBqYqLi%2F4%2FBDTR2HMyCCT1OHlkeaCMBewIc5SRjkBrHQUK0NZnan5ZeaYoCgOT7i1wbPfkBPHy4eVQWvWO%2FQ8fiMZWm3pfIj4%2Bug8mM5ngDjCJye8y8%2Fok5UKgpkmDa8sPKK5meEEtanFkH8meqP%2F30qedFeXHv5MKr947Yn8ZEr%2F86HTVXJo%2Fa%2FdHN8WhflvYMkGxUyqOV%2B0oNxSa%2FVg7b4XTcU3DpkHqBQvw%2FzmgpZvFp7a6cvZ8bFl5V6gqjWC5pvnvc0TTjwEtdZoxYSyqXJUcu1hQZnQoOGC9se632GGnueojyDn4JKPyRCsniOAM1PA7Ar7WzGuMgwfsQiA5vehV%2BHjA9ABvzN2WfRT1a0LZ8xdSAjlCQSb%2FPSjsZJgqQ%2FT2EROyME%2BEL9J0h4Exq1pCq%2Fnr0PSDKad4hTi9%2B65I6yooEcsqiAbw0KY%2Fs%2FnUB5On5F7IX575HIUhD8SxUC%2B%2BHSoT4GSIK568TExytKHIDgELBvd47cE7Aw0YnLoAY6ngHgq%2BqAOo3UjDPIrh5a5RQ%2BYWppNdzp%2BtffWesIVJTJQLNyJosoZN8t8dcU9IH9oS0t96JMnDLVA7CZa%2B0SdiHdURLFHrYqd6VECDgseRAGQXES2n2VIS9Z8ydWmsksPg%2FgNe0Gz3QkiPNI7ovOmdAAVn%2FC98fwsPQdD2sCGIPiFM%2Bbw74sJdY6IbCu%2Bz8OdRKjGWPUMQZ82QOo%2BKxUEQ%3D%3D&X-Amz-Signature=4aac18b700959c65d17198e2708db279273af00df4249b474cac1e3386227508&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3D%22Exported_Invoices_1678951636693.xlsx%22&response-content-type=application%2Foctet-stream" } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "operationId": "get-export", "parameters": [ { "schema": { "type": "string", "enum": [ "Excel", "JPK_FA", "PDF" ], "example": "Excel" }, "in": "query", "name": "exportFileType", "description": "Defines the output file type of export; JPK_FA is only available for SALES", "required": true }, { "schema": { "type": "string", "enum": [ "SALES", "PROCESSED_EXPENSES" ], "example": "SALES" }, "in": "query", "description": "Defines the dataset for our export", "name": "exportType", "required": true } ], "description": "This endpoint allows you to download any set of invoices (either sales or expenses) from your company\n\nAdditional filters (with same parameters as for listing invoices) may be applied to reduce the amount of documents requested." }, "parameters": [] }, "/sales/markPaid": { "parameters": [], "post": { "summary": "Mark Invoice as paid", "operationId": "postsales-markPaid", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceIds": { "type": "array", "items": { "type": "integer" } } }, "x-examples": { "Example 1": { "invoiceIds": [ 12679 ] } } } } } }, "tags": [ "Sales" ], "description": "Sets the payment status of selected invoices as paid, marks paidAmount as whole amount." } }, "/sales/markUnpaid": { "parameters": [], "post": { "summary": "Mark Invoice as unpaid", "operationId": "postsales-markUnpaid", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceIds": { "type": "array", "items": { "type": "integer" } } }, "x-examples": { "Example 1": { "invoiceIds": [ 12679 ] } } } } } }, "tags": [ "Sales" ], "description": "Sets the payment status of selected invoices as unpaid, sets paidAmount to 0." } }, "/sales/pdfUrl": { "parameters": [], "post": { "summary": "Generate PDF url", "operationId": "postsales-pdfUrl", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": "https://example-bucket.s3.eu-central-1.amazonaws.com/invoices/example.pdf?X-Amz-Expires=300&X-Amz-Signature=example" } }, "properties": { "result": { "type": "string", "enum": [ "OK" ], "default": "OK", "example": "OK" }, "data": { "type": "string", "description": "Pre-signed invoice PDF download URL, valid for 5 minutes." } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The invoice PDF is still being generated. Wait at least 2 seconds before retrying within a bounded budget.", "headers": { "Retry-After": { "description": "Minimum delay before retrying, in seconds.", "schema": { "type": "integer", "example": 2 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "PDF_NOT_READY", "errorMessage": "Invoice PDF is not ready. Try again later." } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "invoiceId": 12679 } }, "properties": { "invoiceId": { "type": "integer", "minimum": 1 } }, "required": [ "invoiceId" ] }, "examples": { "One invoice": { "value": { "invoiceId": 12679 } } } } }, "required": true }, "tags": [ "Sales" ], "description": "Returns a pre-signed PDF URL for one invoice, valid for 5 minutes. A company-owned PDF still being generated returns 409 PDF_NOT_READY with Retry-After: 2; retry within a bounded budget. Invalid or unavailable invoice selection returns 400. Pending PDF requests do not change status. A successful request changes an ISSUED sales document, including a pro forma, to SENT even if the URL is never downloaded. DRAFT remains DRAFT. SENT is not proof of email delivery." } }, "/expenses": { "get": { "summary": "List available expenses", "tags": [ "Expenses" ], "parameters": [ { "schema": { "type": "string", "default": "20", "enum": [ "10", "20", "50", "100" ] }, "in": "query", "name": "documentsPerPage", "description": "Defines the amount of invoices polled per page" }, { "schema": { "type": "string" }, "in": "query", "name": "pageNumber", "description": "Defines the page we want to poll" }, { "schema": { "type": "string", "enum": [ "INVOICE_NUMBER", "ISSUE_DATE", "SALE_DATE", "DUE_DATE", "AMOUNT_GROSS", "CONTRACTOR_NAME" ], "example": "ISSUE_DATE" }, "in": "query", "name": "sortBy" }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "example": "DESC" }, "in": "query", "name": "order" }, { "schema": { "type": "string" }, "in": "query", "name": "searchPhrase", "description": "Freetext search over concatenated fields InvoiceNumber, ContractorName, ContractorTIN and ContractorCity" }, { "schema": { "type": "string" }, "in": "query", "name": "contractorName" }, { "schema": { "type": "array", "enum": [ "SALES", "PRO_FORMA", "INTERIM", "INTERIM_FINAL", "CORRECTION" ], "example": "INTERIM", "uniqueItems": true }, "in": "query", "name": "invoiceType", "style": "pipeDelimited" }, { "schema": { "type": "string", "enum": [ "PAID", "UNPAID", "OVERDUE" ], "example": "OVERDUE" }, "in": "query", "name": "paymentStatus" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": { "expenses": [ { "modelType": "PROCESSED_EXPENSE", "readOnly": false, "basicInformation": { "invoiceId": 18, "invoiceType": "SALES", "invoiceNumber": "2/1/2022", "year": 2022, "month": 6, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 8500, "grossPrice": 10455, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1955, "issueDate": "2022-06-16T00:00:00.000Z", "saleDate": "2022-06-27T00:00:00.000Z", "uploadDate": "2022-03-24T14:26:17.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET", "paymentGenerationStatus": "ACCEPTED" }, "contractor": { "contractorName": "Altera sp. z o.o.", "contractorId": 25, "taxIdentificationNumber": "7010978165", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "ul. Grunwaldzka", "houseNumber": "4", "postCode": "85-236" }, "buyer": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "seller": { "contractorName": "Altera sp. z o.o.", "contractorId": 25, "taxIdentificationNumber": "7010978165", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "ul. Grunwaldzka", "houseNumber": "4", "postCode": "85-236" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-07-11T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "bankAccountNumber": "PL78114020040000360280396856" }, "invoicePosition": [], "costCenterPerItem": false, "additionalDetails": "Usługi księgowe Koszty ogólne", "accounting": { "accountingDate": "2022-09-16T00:00:00.000Z", "receiptDate": "2022-09-23T00:00:00.000Z", "vatProcedures": [], "registrationPlate": "", "isSubjectToVat": false, "activeVat": false, "bufferOnly": false } } ], "pagesAmount": "1", "sumGross": "10455.00", "sumNet": "8500.00" } } }, "properties": { "result": { "type": "string" }, "data": { "type": "object", "properties": { "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagesAmount": { "type": "string" }, "sumGross": { "type": "string" }, "sumNet": { "type": "string" } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "expenses": [ { "modelType": "PROCESSED_EXPENSE", "readOnly": false, "basicInformation": { "invoiceId": 18, "invoiceType": "SALES", "invoiceNumber": "2/1/2022", "year": 2022, "month": 6, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 8500, "grossPrice": 10455, "currency": "PLN", "exchangeRate": 1, "vatPLN": 1955, "issueDate": "2022-06-16T00:00:00.000Z", "saleDate": "2022-06-27T00:00:00.000Z", "uploadDate": "2022-03-24T14:26:17.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET", "paymentGenerationStatus": "ACCEPTED" }, "contractor": { "contractorName": "Altera sp. z o.o.", "contractorId": 25, "taxIdentificationNumber": "7010978165", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "ul. Grunwaldzka", "houseNumber": "4", "postCode": "85-236" }, "buyer": { "taxIdentificationNumber": "9671391067", "contractorName": "ITKO Łukasz Kowalski" }, "seller": { "contractorName": "Altera sp. z o.o.", "contractorId": 25, "taxIdentificationNumber": "7010978165", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Bydgoszcz", "street": "ul. Grunwaldzka", "houseNumber": "4", "postCode": "85-236" }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2022-07-11T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "bankAccountNumber": "PL78114020040000360280396856" }, "invoicePosition": [], "costCenterPerItem": false, "additionalDetails": "Usługi księgowe Koszty ogólne", "accounting": { "accountingDate": "2022-09-16T00:00:00.000Z", "receiptDate": "2022-09-23T00:00:00.000Z", "vatProcedures": [], "registrationPlate": "", "isSubjectToVat": false, "activeVat": false, "bufferOnly": false } } ], "pagesAmount": "1", "sumGross": "10455.000", "sumNet": "8500.00" } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "operationId": "get-expenses-list", "security": [ { "Authorization": [] } ], "description": "Gets a list of expense invoices imported into the system for your company." }, "parameters": [] }, "/expenses/generate": { "post": { "summary": "Generate new expense reference", "tags": [ "Expenses" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": { "uploadURL": "https://dev-altera-stack-altera-alterabucket37643c33-10cnlsbxvjnti.s3.eu-central-1.amazonaws.com/expense/manual/11/2023/3/2_10_2022-kCsizgeU66UwKCn.pdf?Content-Type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAX3I6YW7PGDIS6M7M%2F20230316%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230316T070405Z&X-Amz-Expires=120&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEcaDGV1LWNlbnRyYWwtMSJHMEUCIQD0O2KlIUmsoIpHajIpsYh0HEP8HslH3rxQdxmtBV4TzgIgN8mQpodBXAs4UWI0E9mwhrrTMKTZDlb2VrSLuJVozVAq0gMIEBACGgw1Mzk2MTk4MDEwNTQiDPE%2BgemeHivrQZ%2B7eiqvA6Mc0LVPon8X32guntOfGWBwbmrV6pPj1Jm%2Fa1sdtkFtz%2F4VuP4GgLWfw85e%2F1USmnQ9ARj1Zxl1w%2BPhhFkW3Bi40SUjvoou7N6q%2FDoSnCIKqfvPP4OkV4Bfjne4UJE%2B4bpK5eta2qWXOpKl7uUGlFr8hEqvtXBfvGL0viqGWZC8kWJzu1ribEP2wGplxQuIoniGAkjqpFvi88Qf8g%2FUF%2BVYKDQzDrgw%2B%2B2naWLSDkIBPEVMCpcIHoUoAX79fgb8imjKLq1%2BT%2BK1j7IWuyBndFCz0utIUo3pS%2BdwiWEK3WIOjusS%2BmEnUpIwn7vcNDBO5f%2BxUNu1uYQUYQMtl5C16VDuznjvRA8x%2FoMEIeJDbVU8ZU0Pj15198n636pwFOS7g6ViebhEoJ6ZqfL5mHgRHzanjBdvjGzyCQkdz4DLXIBnHT8JN%2F2OcAFurviHAd5qbJyZyogTuvsM7JzNbGDYJw9cSetecWG5voRPnGPYjbJfsMTSC%2BE5WF2xuxP1WcABcZuMaql%2BwSmAD4LGGdTpJGaQM1u8D%2BKl7woBjArShTWEiJr9jpchMJuzX6xuvXxIMP79yqAGOp4BFWbXm5QJlyuND9972BdYVBIL9F99LgXITwHOwvkNSPHC5yvycCSsFMG6or5QZGY1yOeQOWDzxDot6GxtIxQJbBVYfgY9YeP5SN2oZ0VX%2F%2FYY5Wf%2B5r16jsRAL4GQs%2BTwDguEz5UANEWqRhH3yLKKHXVahIfF469iMe8htz9HeA%2FKK%2FxY1KAXw%2F3CZ6eCtvqU1rD2XfXcIkKsXyD2iEU%3D&X-Amz-Signature=d94cd5d84789ea35d0a3104cddb5251de73e6ea6e7ecdb2ee1a78dccd31610c2&X-Amz-SignedHeaders=host%3Bx-amz-meta-companyid%3Bx-amz-meta-nanoid&x-amz-meta-companyid=11&x-amz-meta-nanoid=kCsizgeU66UwKCn", "invoiceId": 1595 } } }, "properties": { "result": { "type": "string", "example": "OK" }, "data": { "type": "object", "properties": { "uploadURL": { "type": "string" }, "invoiceId": { "type": "integer", "example": 1500 } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "uploadURL": "https://dev-altera-stack-altera-alterabucket37643c33-10cnlsbxvjnti.s3.eu-central-1.amazonaws.com/expense/manual/11/2023/3/2_10_2022-kCsizgeU66UwKCn.pdf?Content-Type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAX3I6YW7PGDIS6M7M%2F20230316%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20230316T070405Z&X-Amz-Expires=120&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEcaDGV1LWNlbnRyYWwtMSJHMEUCIQD0O2KlIUmsoIpHajIpsYh0HEP8HslH3rxQdxmtBV4TzgIgN8mQpodBXAs4UWI0E9mwhrrTMKTZDlb2VrSLuJVozVAq0gMIEBACGgw1Mzk2MTk4MDEwNTQiDPE%2BgemeHivrQZ%2B7eiqvA6Mc0LVPon8X32guntOfGWBwbmrV6pPj1Jm%2Fa1sdtkFtz%2F4VuP4GgLWfw85e%2F1USmnQ9ARj1Zxl1w%2BPhhFkW3Bi40SUjvoou7N6q%2FDoSnCIKqfvPP4OkV4Bfjne4UJE%2B4bpK5eta2qWXOpKl7uUGlFr8hEqvtXBfvGL0viqGWZC8kWJzu1ribEP2wGplxQuIoniGAkjqpFvi88Qf8g%2FUF%2BVYKDQzDrgw%2B%2B2naWLSDkIBPEVMCpcIHoUoAX79fgb8imjKLq1%2BT%2BK1j7IWuyBndFCz0utIUo3pS%2BdwiWEK3WIOjusS%2BmEnUpIwn7vcNDBO5f%2BxUNu1uYQUYQMtl5C16VDuznjvRA8x%2FoMEIeJDbVU8ZU0Pj15198n636pwFOS7g6ViebhEoJ6ZqfL5mHgRHzanjBdvjGzyCQkdz4DLXIBnHT8JN%2F2OcAFurviHAd5qbJyZyogTuvsM7JzNbGDYJw9cSetecWG5voRPnGPYjbJfsMTSC%2BE5WF2xuxP1WcABcZuMaql%2BwSmAD4LGGdTpJGaQM1u8D%2BKl7woBjArShTWEiJr9jpchMJuzX6xuvXxIMP79yqAGOp4BFWbXm5QJlyuND9972BdYVBIL9F99LgXITwHOwvkNSPHC5yvycCSsFMG6or5QZGY1yOeQOWDzxDot6GxtIxQJbBVYfgY9YeP5SN2oZ0VX%2F%2FYY5Wf%2B5r16jsRAL4GQs%2BTwDguEz5UANEWqRhH3yLKKHXVahIfF469iMe8htz9HeA%2FKK%2FxY1KAXw%2F3CZ6eCtvqU1rD2XfXcIkKsXyD2iEU%3D&X-Amz-Signature=d94cd5d84789ea35d0a3104cddb5251de73e6ea6e7ecdb2ee1a78dccd31610c2&X-Amz-SignedHeaders=host%3Bx-amz-meta-companyid%3Bx-amz-meta-nanoid&x-amz-meta-companyid=11&x-amz-meta-nanoid=kCsizgeU66UwKCn", "invoiceId": 1595 } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "operationId": "get-expenses-uploadUrl", "parameters": [], "description": "Creates a reference for the new expense to be imported into the system\nReturns a pre-signed url that allows you to send the expense file directly to the system's storage.\n\nIn order to finish the job you need to use the pre-signed link from response (`data.uploadURL`) in another PUT command, attaching the file in question.\n\nNote: The response now returns `invoiceId` instead of `fileId` to align with the expense creation workflow.", "security": [ { "Authorization": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 255, "x-stoplight": { "id": "yyhrz2rgk0nz8" }, "description": "The filename (including extension)" }, "mime": { "type": "string", "x-stoplight": { "id": "du7rfeaysrfb1" }, "description": "Mime type of the file we wish to upload" }, "md5": { "type": "string", "pattern": "^[a-f0-9]{32}$", "x-stoplight": { "id": "lpghwmhmqyiic" }, "description": "MD5 checksum of the file we wish to upload" }, "override": { "type": "boolean", "x-stoplight": { "id": "9b28itdkpfgw1" }, "description": "Override if a duplicate was found?" }, "private": { "type": "boolean", "description": "Whether the file should be marked as private" } }, "required": [ "name", "mime", "md5" ] }, "examples": { "Example 1": { "value": { "name": "foto.jpg", "mime": "image/jpeg", "md5": "d41d8cd98f00b204e9800998ecf8427e", "override": true, "private": false } } } } } } }, "parameters": [] }, "/company/contractors": { "parameters": [], "post": { "summary": "Add/modify contractor", "operationId": "postcompany-contractors", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": { "contractorId": 4527 } } }, "properties": { "result": { "type": "string", "default": "OK", "example": "OK" }, "data": { "type": "object", "properties": { "contractorId": { "type": "integer", "example": 15232 } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "contractorId": 4527 } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Configuration" ], "description": "This endpoint provides the means for adding/updating contractor data for later use in the system", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "contractorId": 4527, "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Apple Computer, Inc.", "street": "Rejsi Manor", "houseNumber": "465", "flatNumber": "42", "city": "Menahga", "postCode": "58-261", "taxIdentificationNumber": "8958666780", "email": "spend@different.com", "areaNumber": "", "phoneNumber": "337507196" } }, "properties": { "contractorId": { "type": "integer", "description": "Identifier used if we wish to update an already existing contractor" }, "contractorRegion": { "type": "string", "enum": [ "POLAND", "EU", "OUTSIDE_OF_EU" ], "example": "POLAND" }, "country": { "type": "string", "description": "Two letter country code according to ISO 3166-1 alfa-2" }, "contractorType": { "type": "string", "enum": [ "COMPANY", "PRIVATE_PERSON" ], "example": "PRIVATE_PERSON" }, "contractorName": { "type": "string" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "flatNumber": { "type": "string" }, "city": { "type": "string" }, "postCode": { "type": "string" }, "taxIdentificationNumber": { "type": "string" }, "email": { "type": "string" }, "areaNumber": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "contractorRegion", "country", "contractorType", "contractorName" ] }, "examples": { "Example 1": { "value": { "contractorId": 4527, "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Apple Computer, Inc.", "street": "Rejsi Manor", "houseNumber": "465", "flatNumber": "42", "city": "Menahga", "postCode": "58-261", "taxIdentificationNumber": "8958666780", "email": "spend@different.com", "areaNumber": "", "phoneNumber": "337507196" } } } } } } } }, "/company/products/categories": { "parameters": [], "post": { "summary": "Add/modify products' category", "operationId": "postcompany-products-categories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": { "categoryId": 15451 } } }, "properties": { "result": { "type": "string", "default": "OK" }, "data": { "type": "object", "properties": { "categoryId": { "type": "integer" } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "categoryId": 15451 } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Configuration" ], "description": "This endpoint provides the means for adding/updating sale invoice Categories for later use in the system", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "CompanyProductCategory_Id": 15451, "CompanyProductCategoryName": "Youth", "enabled": false } }, "properties": { "CompanyProductCategory_Id": { "type": "integer", "description": "Required if performing update" }, "CompanyProductCategoryName": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "CompanyProductCategoryName", "enabled" ] }, "examples": { "Example 1": { "value": { "CompanyProductCategory_Id": 15451, "CompanyProductCategoryName": "Youth", "enabled": false } } } } }, "description": "" } } }, "/company/products": { "parameters": [], "post": { "summary": "Add/modify a product", "operationId": "postcompany-products", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": { "productId": 7638 } } }, "properties": { "result": { "type": "string", "default": "OK" }, "data": { "type": "object", "properties": { "productId": { "type": "integer" } } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": { "productId": 7638 } } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "tags": [ "Configuration" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceProduct", "x-examples": { "Example 1": { "productId": 7638, "itemType": "PRODUCT", "productName": "Accurate made letter", "unit": "m2", "price": "98.00", "vatPerc": "23%", "pkwiu": "3.2.7", "gtu": "04", "category": 15465, "favourite": false, "enabled": false } } }, "examples": { "Example 1": { "value": { "productId": 7638, "itemType": "PRODUCT", "productName": "Accurate made letter", "unit": "m2", "price": "98.00", "vatPerc": "23%", "pkwiu": "3.2.7", "gtu": "04", "category": 15465, "favourite": false, "enabled": false } } } } } }, "description": "This endpoint provides the means for adding/updating sale invoice products for later use in the system" } }, "/company/projects": { "get": { "summary": "List projects", "operationId": "get-company-projects", "description": "List projects belonging to the company identified by the Authorization API key. Returns active and disabled projects by default. Use onlyActive=1 to return only active projects. Find the desired project by name in data and pass its complete object as project when saving a sales invoice; tagId is the project identifier. No companyId parameter is needed.", "tags": [ "Configuration" ], "parameters": [ { "name": "onlyActive", "in": "query", "required": false, "description": "Set to 1 to return only active projects. Omit or set to 0 to include disabled projects.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "example": 1 } ], "responses": { "200": { "description": "Company projects. data is an empty array when no projects match.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "data" ], "properties": { "result": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTag" } } } }, "examples": { "Projects": { "value": { "result": "OK", "data": [ { "tagId": 123, "name": "Grow", "enabled": true, "color": 4286963618 } ] } }, "No projects": { "value": { "result": "OK", "data": [] } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } } }, "post": { "summary": "Add/modify a project", "operationId": "post-company-projects", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "result": "OK", "data": [ { "tagId": 1, "name": "Marketing", "color": 4286963618, "enabled": false }, { "tagId": 2, "name": "IT", "color": 4294933887, "enabled": false }, { "tagId": 3, "name": "new", "color": 4281667055, "enabled": true }, { "tagId": 4, "name": "new 2", "color": 4281667055, "enabled": true }, { "tagId": 5, "name": "new3", "color": 4284816155, "enabled": true }, { "tagId": 9, "name": "Testttt", "color": 4281954268, "enabled": true }, { "tagId": 10, "name": "Nowy test", "color": 4278430196, "enabled": true }, { "tagId": 11, "name": "Test 2", "color": 4288423856, "enabled": true }, { "tagId": 12, "name": "Haha test 3", "color": 4288423856, "enabled": true }, { "tagId": 23, "name": "Analfabeta", "color": 4293467747, "enabled": true }, { "tagId": 26, "name": "Test odświeżania", "color": 4280391411, "enabled": true }, { "tagId": 27, "name": "Test odświeżania 2", "color": 4284513675, "enabled": true }, { "tagId": 28, "name": "Test odświeżania 3", "color": 4280391411, "enabled": true }, { "tagId": 161, "name": "Bardzo długa nazwa projektu", "color": 4294961979, "enabled": true } ] } }, "properties": { "result": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTag" } } } }, "examples": { "Example 1": { "value": { "result": "OK", "data": [ { "tagId": 1, "name": "Marketing", "color": 4286963618, "enabled": false }, { "tagId": 2, "name": "IT", "color": 4294933887, "enabled": false }, { "tagId": 3, "name": "new", "color": 4281667055, "enabled": true }, { "tagId": 4, "name": "new 2", "color": 4281667055, "enabled": true }, { "tagId": 5, "name": "new3", "color": 4284816155, "enabled": true }, { "tagId": 9, "name": "Testttt", "color": 4281954268, "enabled": true }, { "tagId": 10, "name": "Nowy test", "color": 4278430196, "enabled": true }, { "tagId": 11, "name": "Test 2", "color": 4288423856, "enabled": true }, { "tagId": 12, "name": "Haha test 3", "color": 4288423856, "enabled": true }, { "tagId": 23, "name": "Analfabeta", "color": 4293467747, "enabled": true }, { "tagId": 26, "name": "Test odświeżania", "color": 4280391411, "enabled": true }, { "tagId": 27, "name": "Test odświeżania 2", "color": 4284513675, "enabled": true }, { "tagId": 28, "name": "Test odświeżania 3", "color": 4280391411, "enabled": true }, { "tagId": 161, "name": "Bardzo długa nazwa projektu", "color": 4294961979, "enabled": true } ] } } } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "description": "", "tags": [ "Configuration" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceTag", "x-examples": { "Example 1": { "tagId": 1, "name": "Marketing", "enabled": false, "color": 4286963618 } } }, "examples": { "Example 1": { "value": { "tagId": 1, "name": "Marketing", "enabled": false, "color": 4286963618 } } } } } } }, "parameters": [] }, "/sales/invoice/send": { "post": { "summary": "Send invoice email to contractor", "tags": [ "Sales" ], "responses": { "200": { "description": "Email accepted into the sending queue. This confirms enqueueing, not delivery to the recipient mailbox.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "data" ], "properties": { "result": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "string", "enum": [ "Ok" ] } } }, "example": { "result": "OK", "data": "Ok" } } } }, "400": { "description": "Invalid request, missing company reply-to, missing invoice or recipient, or omitted content without a configured invoice email template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } }, "operationId": "post-sales-invoice-send", "x-stoplight": { "id": "kvd5kp5g6i6pu" }, "security": [ { "Authorization": [] } ], "description": "Send an invoice to its contractor by email. Configure the company global reply-to address in Settings > Sales > E-mail messages before calling this endpoint. HTTP 200 with result OK confirms that the email was queued; it does not confirm mailbox delivery. In QA, external recipient addresses are filtered out by sandbox routing. To verify actual receipt in QA, coordinate a recipient address in the @altera.co domain with Altera support. See the endpoint guide for template requirements and testing.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "integer", "x-stoplight": { "id": "t22p1bpr1btte" }, "minimum": 1, "description": "ID of an invoice belonging to the company identified by the API token." }, "topic": { "type": "string", "x-stoplight": { "id": "a5hpyzlc5tcfb" }, "example": "New invoice #123", "maxLength": 400, "description": "Optional email subject. If omitted, empty or whitespace-only, generates Faktura numer {invoiceNumber}, independently of the company body template and invoice document language. A nonblank topic overrides the standard subject. Requires the subject fallback fix in the target environment; see the endpoint guide for the older-version workaround." }, "content": { "type": "string", "x-stoplight": { "id": "06p82inxcfrf4" }, "maxLength": 900000, "description": "Optional email body as plain text or HTML. If omitted, empty or whitespace-only, uses the company invoice-send email template with invoice placeholders expanded. Configure that template in Settings > Sales > E-mail messages first; a missing template returns HTTP 400. A nonblank value overrides the company template." }, "recipient": { "type": "array", "x-stoplight": { "id": "aykqecgp3bwje" }, "items": { "x-stoplight": { "id": "4e5kiqhkdptx3" }, "type": "string", "format": "email" }, "description": "Explicit email recipients. Required unless recipientFromSystem is true. Ignored when recipientFromSystem is true." }, "recipientFromSystem": { "type": "boolean", "x-stoplight": { "id": "r5bq0s5y64yt5" }, "default": false, "description": "When true, load recipient addresses from the contractor saved on the invoice. Takes precedence over recipient. At least one contractor email address must exist." } }, "required": [ "invoiceId" ], "anyOf": [ { "required": [ "recipient" ], "properties": { "recipient": { "minItems": 1 } } }, { "required": [ "recipientFromSystem" ], "properties": { "recipientFromSystem": { "enum": [ true ] } } } ] }, "examples": { "company-template": { "summary": "Use the company body template and generated subject", "value": { "invoiceId": 12345, "recipientFromSystem": true } }, "explicit-email": { "summary": "Override the subject and body for explicit recipients", "value": { "invoiceId": 12345, "recipient": [ "recipient@example.com" ], "topic": "Invoice 12345", "content": "

Please find your invoice attached.

" } } } } }, "description": "Provide invoiceId and either a nonempty recipient array or recipientFromSystem: true. If topic is omitted, empty or whitespace-only, Altera generates the standard subject from the invoice number. If content is omitted, empty or whitespace-only, configure the company invoice email template before sending. Explicit nonblank values override these defaults independently. content accepts plain text or HTML. The company template configures the body; the standard subject is generated separately. See the endpoint guide for the older-version subject fallback limitation.", "required": true } } }, "/sales/delete": { "post": { "summary": "Delete a sales invoice", "operationId": "post-sales-delete", "tags": [ "Sales" ], "description": "Existing removal endpoint, including test drafts. DRAFT is deleted permanently; an eligible issued invoice is soft-deleted. Related documents, read-only or accounting-approved documents, and invoices submitted to or accepted by KSeF cannot be deleted. fullDelete and softDelete count removed invoice records. This endpoint uses POST, not DELETE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoiceId" ], "properties": { "invoiceId": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 5, "maxLength": 400, "description": "Optional deletion reason." } } }, "examples": { "Delete test draft": { "value": { "invoiceId": 12345, "reason": "Removing a QA test draft" } } } } } }, "responses": { "200": { "description": "Removal processed. Inspect fullDelete and softDelete to determine how many invoice records were removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "fullDelete": { "type": "integer", "minimum": 0, "description": "Permanently deleted invoice count." }, "softDelete": { "type": "integer", "minimum": 0 }, "counterRollbackResult": { "type": "string", "enum": [ "OK", "NOK" ], "description": "Invoice-number counter rollback result for eligible issued invoices. Draft deletion returns NOK." } }, "required": [ "fullDelete", "softDelete", "counterRollbackResult" ] } }, "required": [ "result", "data" ] }, "examples": { "Deleted draft": { "value": { "result": "OK", "data": { "fullDelete": 1, "softDelete": 0, "counterRollbackResult": "NOK" } } } } } } }, "400": { "description": "Invalid request or document cannot be deleted due to relations, read-only/accounting state, prior deletion or KSeF submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Invoice not found within the API key company, or authorization denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "KEY_EXPIRED: a verified API key has expired. This requires that the company still has OpenAPI access. Unknown/invalid keys can receive the gateway 403.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "result": "Error", "errorCode": "KEY_EXPIRED", "errorMessage": "API key has expired" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "x-examples": { "Example 1": { "result": "Error", "errorMessage": "This tag cannot be deleted, it has been used in at least one invoice. You can disable it so it won't appear on the suggestion lists.", "errorMessagePL": "Ta kategoria nie może zostać usunięta ponieważ została użyta w przynajmniej jednej fakturze. Możesz ją zablokować aby nie pojawiała się na liście sugerowanych." } }, "examples": [ { "result": "Error", "errorMessage": "This tag cannot be deleted, it has been used in at least one invoice. You can disable it so it won't appear on the suggestion lists.", "errorMessagePL": "Ta kategoria nie może zostać usunięta ponieważ została użyta w przynajmniej jednej fakturze. Możesz ją zablokować aby nie pojawiała się na liście sugerowanych." } ], "properties": { "result": { "type": "string", "enum": [ "Error" ], "default": "Error", "example": "Error" }, "errorMessage": { "type": "string" }, "errorMessagePL": { "type": "string" }, "validationErrors": { "type": "array", "description": "Optional field-level validation details. Use code for programmatic error handling.", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "basicInformation.issueDate" }, "message": { "type": "string" }, "code": { "type": "string", "example": "DATE_REQUIRES_LOCAL_DATE" } } } }, "errorCode": { "type": "string", "description": "Machine-readable error code when available, including KEY_EXPIRED, NOT_FOUND or PDF_NOT_READY." } }, "description": "Default error message format in Altera API\nDepending on particular reason, different HTTP Status codes will be employed" }, "Invoice": { "type": "object", "x-examples": { "Example 1": { "modelType": "INVOICE", "readOnly": false, "basicInformation": { "invoiceId": 118584, "invoiceType": "PRO_FORMA", "invoiceFormat": "PRO %N/%M/%Y", "invoiceNumber": "PRO 2/12/2022", "year": 2022, "month": 12, "invoiceNumberInPeriod": 2, "statusId": "SENT", "isReceipt": false, "isRelated": false, "netPrice": 5760, "grossPrice": 7084.8, "currency": "PLN", "exchangeRate": 1.43, "vatPLN": 1324.8, "issueDate": "2022-12-27T00:00:00.000Z", "saleDate": "2022-12-27T00:00:00.000Z", "uploadDate": "2022-12-27T08:52:22.000Z", "relatedInvoicesIds": [], "priceTypeId": "NET" }, "buyer": { "contractorName": "American Water Works Company, Inc.", "contractorId": 106, "taxIdentificationNumber": "3748414103", "country": "PL", "contractorType": "COMPANY", "contractorRegion": "POLAND", "defaultCurrency": "PLN", "city": "Norton Canes", "street": "Dezsez View", "houseNumber": "396", "flatNumber": "154", "postCode": "97-135", "email": "went@able.com,fv@altera.co", "phoneNumber": "420577850", "areaNumber": "" }, "seller": { "taxIdentificationNumber": "1397887352", "contractorName": "Express Scripts Inc." }, "payments": { "paymentMethod": "TRANSFER", "dueDate": "2023-01-26T00:00:00.000Z", "isSplitPayment": false, "isPaid": false, "paidAmount": 0, "bankAccountNumber": "29 1111 1111 1111 1111 1111 1111" }, "invoicePosition": [ { "invoiceProductId": 57822, "positionType": "SERVICE", "productPosition": 0, "productCategory": "Facebook", "productCategoryId": 808, "productName": "Facebook Ads", "unit": "szt.", "unitNetPrice": 480, "unitGrossPrice": 590.4, "quantity": 12, "discount": 0, "vat": "23%", "priceNet": 5760, "netPrice": "5760", "vatAmt": 1324.8, "priceGross": 7084.8, "grossPrice": "7084.8", "gtu": "-" } ] } }, "title": "Invoice", "properties": { "modelType": { "type": "string" }, "readOnly": { "type": "boolean" }, "basicInformation": { "type": "object", "properties": { "invoiceId": { "type": "integer" }, "invoiceType": { "type": "string", "enum": [ "SALES", "PRO_FORMA", "INTERIM", "INTERIM_FINAL", "CORRECTION" ], "example": "SALES" }, "invoiceFormat": { "type": "string" }, "invoiceNumber": { "type": "string" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "invoiceNumberInPeriod": { "type": "integer" }, "statusId": { "type": "string" }, "isReceipt": { "type": "boolean" }, "isRelated": { "type": "boolean" }, "netPrice": { "type": "integer" }, "grossPrice": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "Invoice currency stored as a three-letter code." }, "exchangeRate": { "type": "number" }, "vatPLN": { "type": "number" }, "issueDate": { "type": "string" }, "saleDate": { "type": "string" }, "uploadDate": { "type": "string" }, "relatedInvoicesIds": { "type": "array", "items": { "type": "object" } }, "priceTypeId": { "type": "string" }, "language": { "type": "string", "enum": [ "pl", "en", "de", "es", "en_pl", "de_pl" ], "default": "pl", "example": "en", "description": "Language of the invoice document: pl, en, de, es, en_pl or de_pl." }, "isDeleted": { "description": "Soft-deletion marker. Public GET excludes soft-deleted documents and returns 404 instead of their data.", "oneOf": [ { "type": "boolean" }, { "type": "integer", "enum": [ 0, 1 ] } ] } }, "required": [ "invoiceId", "invoiceType", "invoiceFormat", "year", "month" ] }, "contractor": { "type": "object", "x-stoplight": { "id": "3h79oxtj5267w" }, "properties": { "contractorName": { "type": "string" }, "contractorId": { "type": "integer" }, "taxIdentificationNumber": { "type": "string" }, "country": { "type": "string" }, "contractorType": { "type": "string" }, "contractorRegion": { "type": "string" }, "defaultCurrency": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "flatNumber": { "type": "string" }, "postCode": { "type": "string" }, "email": { "type": "string" }, "phoneNumber": { "type": "string" }, "areaNumber": { "type": "string" } } }, "seller": { "type": "object", "properties": { "taxIdentificationNumber": { "type": "string" }, "contractorName": { "type": "string" } } }, "payments": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "dueDate": { "type": "string" }, "isSplitPayment": { "type": "boolean" }, "isPaid": { "type": "boolean" }, "paidAmount": { "type": "integer" }, "bankAccountNumber": { "type": "string" } } }, "ksef": { "type": "object", "properties": { "ksefId": { "type": "string" }, "ksefSubmissionDate": { "type": "string" }, "ksefStatus": { "type": "string", "enum": [ "ACCEPTED", "PENDING", "ERROR" ] }, "ksefErrorMessage": { "type": "string" }, "ksefRetryCount": { "type": "integer" }, "ksefSourceXmlKey": { "type": "string" } } }, "offlineMode": { "type": "boolean" }, "offlineModeReason": { "type": "string" }, "invoicePosition": { "type": "array", "items": { "type": "object", "properties": { "invoiceProductId": { "type": "integer" }, "positionType": { "type": "string" }, "productPosition": { "type": "integer" }, "productCategory": { "type": "string" }, "productCategoryId": { "type": "integer" }, "productName": { "type": "string" }, "unit": { "type": "string" }, "unitNetPrice": { "type": "integer" }, "unitGrossPrice": { "type": "number" }, "quantity": { "type": "integer" }, "discount": { "type": "integer" }, "vat": { "type": "string", "description": "VAT rate for this invoice line. np I and np II are distinct supported values and map to separate KSeF summary fields P_13_8 and P_13_9. The generic np value is retained for legacy invoices and maps to np I; use an explicit np I or np II value for new invoices." }, "priceNet": { "type": "integer" }, "netPrice": { "type": "string" }, "vatAmt": { "type": "number" }, "priceGross": { "type": "number" }, "grossPrice": { "type": "string" }, "gtu": { "type": [ "string", "null" ], "maxLength": 10, "example": "2", "description": "Optional GTU classification for this invoice line. Use a string from 1 to 13, for example \"2\"; zero-padded values such as \"02\" and KSeF values such as \"GTU_02\" are also supported. KSeF export converts the numeric value to GTU_01 through GTU_13. Omit, pass null or an empty string when no GTU applies." } } } }, "vatExemptionReason": { "type": "string", "nullable": true, "maxLength": 50, "enum": [ "Zwolnienie podmiotowe z art. 113 ust. 1 i 9", "Zwolnienie przedmiotowe z art. 43 ust. 1", "Zwolnienie przedmiotowe z art. 82 ust. 3" ], "description": "Legal basis for VAT exemption selected for an invoice containing a line with the `zw` VAT rate." }, "vatExemptionReasonDetailed": { "type": "string", "nullable": true, "maxLength": 500, "description": "Optional detailed wording shown on the invoice below the selected VAT exemption legal basis." }, "additionalParties": { "type": "array", "description": "Additional parties, including a separate recipient (Podmiot3). Each entry is a snapshot; contractor continues to identify the buyer.", "items": { "$ref": "#/components/schemas/InvoiceAdditionalParty" } } }, "description": "Invoice model for objects returned from server" }, "InvoiceDtoIn": { "type": "object", "x-examples": { "Example 1": { "modelType": "INVOICE", "override": false, "basicInformation": { "invoiceId": 2069, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "saleDate": "2022-10-11", "issueDate": "2022-10-11", "isReceipt": false, "relatedInvoicesIds": [], "priceTypeId": "NET" }, "contractor": { "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Test działania", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "city": "Bydgoszcz", "postCode": "62-156", "defaultCurrency": "PLN", "taxIdentificationNumber": "1589651654", "email": "testing@attention.please", "areaNumber": "+58", "phoneNumber": "518 961 516" }, "invoicePosition": [ { "productPosition": 0, "productName": "A", "positionType": "PRODUCT", "productCategory": "Health", "quantity": 10, "unit": "szt.", "priceType": null, "unitNetPrice": 150, "unitGrossPrice": 184.5, "vat": "23%", "pkwiu": "", "discount": "0", "deductions": false, "netPrice": "1500", "grossPrice": "1845", "invoiceProductId": 179 } ], "additionalDetails": "", "correctionReason": "", "payments": { "isPaid": false, "paymentMethod": "TRANSFER", "dueDate": "2022-10-25", "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516", "isSplitPayment": false }, "project": { "tagId": 161, "name": "Website implementation", "enabled": true, "color": 4286963618 } } }, "examples": [ { "modelType": "INVOICE", "override": false, "basicInformation": { "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "saleDate": "2022-10-11", "issueDate": "2022-10-11", "isReceipt": false, "relatedInvoicesIds": [], "priceTypeId": "NET", "statusId": "DRAFT" }, "contractor": { "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Test działania", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "city": "Bydgoszcz", "postCode": "62-156", "defaultCurrency": "PLN", "taxIdentificationNumber": "1589651654", "email": "testing@attention.please", "areaNumber": "+58", "phoneNumber": "518 961 516" }, "invoicePosition": [ { "productPosition": 0, "productName": "A", "positionType": "PRODUCT", "productCategory": "Health", "quantity": 10, "unit": "szt.", "unitNetPrice": 150, "unitGrossPrice": 184.5, "vat": "23%", "pkwiu": "", "discount": "0", "deductions": false, "netPrice": "1500", "grossPrice": "1845", "invoiceProductId": 179 } ], "additionalDetails": "", "correctionReason": "", "payments": { "isPaid": false, "paymentMethod": "TRANSFER", "dueDate": "2022-10-25", "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516", "isSplitPayment": false } }, { "modelType": "INVOICE", "override": false, "sendToKSEF": true, "basicInformation": { "invoiceId": 2069, "invoiceType": "SALES", "invoiceFormat": "%N/%M/%Y", "saleDate": "2022-10-11", "issueDate": "2022-10-11", "isReceipt": false, "relatedInvoicesIds": [], "priceTypeId": "NET", "statusId": "ISSUED" }, "contractor": { "contractorRegion": "POLAND", "country": "PL", "contractorType": "COMPANY", "contractorName": "Test działania", "street": "Testowa", "houseNumber": "10", "flatNumber": "10", "city": "Bydgoszcz", "postCode": "62-156", "defaultCurrency": "PLN", "taxIdentificationNumber": "1589651654", "email": "testing@attention.please", "areaNumber": "+58", "phoneNumber": "518 961 516" }, "invoicePosition": [ { "productPosition": 0, "productName": "A", "positionType": "PRODUCT", "productCategory": "Health", "quantity": 10, "unit": "szt.", "unitNetPrice": 150, "unitGrossPrice": 184.5, "vat": "23%", "pkwiu": "", "discount": "0", "deductions": false, "netPrice": "1500", "grossPrice": "1845", "invoiceProductId": 179 } ], "additionalDetails": "", "correctionReason": "", "payments": { "isPaid": false, "paymentMethod": "TRANSFER", "dueDate": "2022-10-25", "bankAccountNumber": "10 1010 1062 5565 1561 5615 1516", "isSplitPayment": false } } ], "properties": { "override": { "type": "boolean", "default": false, "description": "Defines whether we wish to override split payments warning, in Machine-machine integrations should be set to `true`" }, "sendToKSEF": { "type": "boolean", "description": "Request immediate KSeF submission after saving an eligible ISSUED or SENT invoice. Defaults to false; false does not disable normal automatic KSeF processing. Requires KSeF and outgoing submission enabled for the company and an eligible invoice. Does not issue a DRAFT or guarantee KSeF acceptance. Inspect data.ksefWarning, data.ksefErrorMessage and data.ksefReason even on HTTP 200, then check the saved invoice KSeF status. Not allowed for PRO_FORMA, ORDER or DEBIT_NOTE. See the endpoint guide for examples and retry handling.", "default": false }, "basicInformation": { "type": "object", "required": [ "invoiceType", "invoiceFormat", "saleDate", "issueDate", "priceTypeId" ], "properties": { "invoiceId": { "type": "integer", "description": "Invoice identificator, used for updating documents" }, "invoiceType": { "type": "string", "enum": [ "SALES", "PRO_FORMA", "INTERIM", "INTERIM_FINAL", "CORRECTION" ], "example": "SALES", "description": "The type of invoice we wish to create" }, "invoiceFormat": { "type": "string", "example": "%N/%M/%Y", "description": "Defines the Invoice numbering format that will be used; Altera providesa set of pre-defined formats right after company creation. They can be reviewed in the UI" }, "saleDate": { "type": "string", "format": "date", "description": "Sale date as a calendar date in YYYY-MM-DD format, without a time or time zone. Do not convert it to a UTC timestamp.", "example": "2026-09-14" }, "issueDate": { "type": "string", "format": "date", "description": "Issue date as a calendar date in YYYY-MM-DD format, without a time or time zone. Do not convert it to a UTC timestamp.", "example": "2026-09-14" }, "isReceipt": { "type": "boolean", "description": "Defines whether we are creating an invoice to an already issued receipt" }, "relatedInvoicesIds": { "type": "array", "description": "Identifiers of documents related to this invoice. For CORRECTION, the first referenced invoice supplies the baseline rows. To correct a previous correction, reference that correction and provide the new after-correction state. GET /sales/invoice with related prepares a starting payload from the referenced document.", "items": { "type": "object" } }, "priceTypeId": { "type": "string", "enum": [ "NET", "GROSS" ], "default": "NET", "example": "NET" }, "statusId": { "x-stoplight": { "id": "94k63xf3cdiyb" }, "example": "ISSUED", "enum": [ "DRAFT", "ISSUED" ], "default": "DRAFT" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "Invoice currency as a three-letter code, for example PLN, EUR or USD. Input is trimmed and converted to uppercase. If omitted, Altera uses contractor.defaultCurrency, then PLN. Resend it on update to retain the invoice currency." }, "language": { "type": "string", "enum": [ "pl", "en", "de", "es", "en_pl", "de_pl" ], "default": "pl", "example": "en", "description": "Language of the invoice document: Polish, English, German, Spanish, English/Polish or German/Polish. Independent of the email content language. If omitted, defaults to pl, including on update." } } }, "contractor": { "type": "object", "properties": { "contractorRegion": { "type": "string", "enum": [ "EU", "OUTSIDE_OF_EU", "POLAND" ], "example": "POLAND" }, "country": { "type": "string", "maxLength": 2, "example": "PL", "description": "ISO 3166-1 alfa-2 two letter country code" }, "contractorType": { "type": "string", "enum": [ "COMPANY", "PRIVATE_PERSON" ], "example": "COMPANY" }, "contractorName": { "type": "string" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "flatNumber": { "type": "string" }, "city": { "type": "string" }, "postCode": { "type": "string" }, "defaultCurrency": { "type": "string" }, "taxIdentificationNumber": { "type": "string", "maxLength": 45 }, "email": { "type": "string", "maxLength": 200, "description": "Comma delimited list of contractor e-mails" }, "areaNumber": { "type": "string", "maxLength": 5 }, "phoneNumber": { "type": "string", "maxLength": 45 } } }, "invoicePosition": { "type": "array", "items": { "type": "object", "properties": { "productPosition": { "type": "integer", "example": 0, "description": "Zero based position number in invoice" }, "productName": { "type": "string", "maxLength": 200 }, "positionType": { "type": "string", "enum": [ "PRODUCT", "SERVICE" ], "example": "SERVICE" }, "productCategory": { "type": "string", "description": "Allows grouping of similar products", "example": "Personalized" }, "quantity": { "type": "number", "example": 14, "description": "Positive on ordinary invoices. Zero is accepted only for CORRECTION with a source invoice in basicInformation.relatedInvoicesIds, for the state after correction. Negative quantities are rejected.", "minimum": 0 }, "unit": { "type": "string", "example": "pcs." }, "unitNetPrice": { "type": "number", "description": "Net price per item. Zero is accepted, including for the post-correction state of a fully returned line.", "example": 100, "minimum": 0 }, "unitGrossPrice": { "type": "number", "description": "Gross price per item. Zero is accepted, including for the post-correction state of a fully returned line.", "example": 123, "minimum": 0 }, "vat": { "type": "string", "enum": [ "23%", "8%", "5%", "0%", "np I", "np II", "np", "zw" ], "example": "23%", "description": "VAT rate for this invoice line. np I and np II are distinct supported values and map to separate KSeF summary fields P_13_8 and P_13_9. The generic np value is retained for legacy invoices and maps to np I; use an explicit np I or np II value for new invoices." }, "pkwiu": { "type": "string" }, "discount": { "type": "string", "example": "10%", "description": "Defines % discount on given product" }, "invoiceProductId": { "type": "integer" }, "gtu": { "type": [ "string", "null" ], "maxLength": 10, "example": "2", "description": "Optional GTU classification for this invoice line. Use a string from 1 to 13, for example \"2\"; zero-padded values such as \"02\" and KSeF values such as \"GTU_02\" are also supported. KSeF export converts the numeric value to GTU_01 through GTU_13. Omit, pass null or an empty string when no GTU applies." } } } }, "additionalDetails": { "type": "string", "description": "Describes extra information that we wish to present on the invoice" }, "correctionReason": { "type": "string", "description": "Additional information regarding the reason behing correcting your invoice" }, "vatExemptionReason": { "type": "string", "maxLength": 50, "enum": [ "Zwolnienie podmiotowe z art. 113 ust. 1 i 9", "Zwolnienie przedmiotowe z art. 43 ust. 1", "Zwolnienie przedmiotowe z art. 82 ust. 3" ], "description": "Legal basis for a zw line. Required before issuing a sales invoice unless a nonempty company default supplies the basis. Drafts may omit it. Missing basis returns validation code KSEF_VAT_EXEMPTION_LEGAL_BASIS_REQUIRED, which override cannot bypass. New XML uses P_19A. Submission also checks stored XML for P_19=1, exactly one nonempty P_19A/B/C, and no P_19N." }, "vatExemptionReasonDetailed": { "type": "string", "maxLength": 500, "description": "Optional detailed wording shown on the invoice below vatExemptionReason. It does not replace the required vatExemptionReason value." }, "payments": { "type": "object", "properties": { "isPaid": { "type": "boolean" }, "paymentMethod": { "type": "string", "enum": [ "TRANSFER", "CASH", "CARD" ], "example": "TRANSFER" }, "dueDate": { "type": "string", "format": "date", "description": "Payment due date as a calendar date in YYYY-MM-DD format, without a time or time zone. Do not convert it to a UTC timestamp.", "example": "2026-09-28" }, "bankAccountNumber": { "type": "string", "description": "Defines the bank account no. we wish to receive funds to" }, "isSplitPayment": { "type": "boolean", "description": "Required whenever payments is provided. Pass false when split payment does not apply." }, "paymentDate": { "type": "string", "format": "date", "description": "Payment date (optional) as a calendar date in YYYY-MM-DD format, without a time or time zone. Do not convert it to a UTC timestamp.", "example": "2026-09-14" } }, "required": [ "paymentMethod", "dueDate", "isSplitPayment", "isPaid" ], "description": "Required when statusId is not DRAFT. Whenever this object is supplied, include paymentMethod, dueDate, isSplitPayment and isPaid, including explicit false values for the booleans." }, "additionalParties": { "type": "array", "description": "Additional parties, including a separate recipient (Podmiot3). Each entry is a snapshot; contractor continues to identify the buyer.", "items": { "$ref": "#/components/schemas/InvoiceAdditionalParty" } }, "project": { "description": "Single project assigned to the invoice. Pass an existing project from the same company, including tagId, name, enabled and color. Assignment is persisted by tagId; saving an invoice does not create a project. On update, resend project to retain the assignment; omitting it removes the assignment. The header project is propagated to sales line items. Use project, not projects.", "allOf": [ { "$ref": "#/components/schemas/InvoiceTag" }, { "type": "object", "required": [ "tagId", "name", "enabled", "color" ], "properties": { "tagId": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1 }, "color": { "type": "number", "minimum": 4278190080, "maximum": 4294967295 } } } ], "example": { "tagId": 161, "name": "Website implementation", "enabled": true, "color": 4286963618 } } }, "description": "" }, "InvoiceAdditionalParty": { "type": "object", "description": "Snapshot of an additional invoice party (Podmiot3). The buyer remains in contractor. Provide the party name, role, address and applicable tax identity for invoicing and KSeF export.", "properties": { "semanticRole": { "type": "string", "enum": [ "FACTOR", "RECIPIENT", "BRANCH", "ORIGINAL_ENTITY", "ADDITIONAL_BUYER", "ISSUER", "PAYEE", "JST_ISSUER", "JST_RECIPIENT", "VAT_GROUP_ISSUER", "VAT_GROUP_RECIPIENT", "EMPLOYEE", "OTHER" ], "description": "Role of this additional party (Podmiot3). Use RECIPIENT for a separate invoice recipient. JST_RECIPIENT has distinct KSeF semantics; do not select it solely because the recipient is a school." }, "internalId": { "type": "string", "nullable": true, "pattern": "^[0-9]{5}$", "description": "Optional five-digit suffix, preserving leading zeros. KSeF export requires a Polish 10-digit NIP and Polish country and emits IDWew as NIP-internalId, for example 5260250274-00123." }, "contractorType": { "type": "string", "enum": [ "COMPANY", "PRIVATE_PERSON" ] }, "contractorRegion": { "type": "string", "enum": [ "POLAND", "EU", "OUTSIDE_OF_EU" ] }, "contractorName": { "type": "string", "maxLength": 255 }, "taxIdentificationNumber": { "type": "string", "maxLength": 45 }, "city": { "type": "string", "maxLength": 100 }, "street": { "type": "string", "maxLength": 100 }, "houseNumber": { "type": "string", "maxLength": 20 }, "flatNumber": { "type": "string", "maxLength": 20 }, "postCode": { "type": "string", "maxLength": 10 }, "email": { "type": "string", "maxLength": 500 }, "phoneNumber": { "type": "string", "maxLength": 45 }, "areaNumber": { "type": "string", "maxLength": 5 }, "roleOther": { "type": "string", "maxLength": 255, "description": "Description of the role when semanticRole is OTHER; exported as OpisRoli with RolaInna=1." }, "extraInfo": { "type": "string", "maxLength": 255 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "tinCountry": { "type": "string", "minLength": 2, "maxLength": 2 }, "defaultCurrency": { "type": "string", "minLength": 3, "maxLength": 3 }, "partyOrder": { "type": "integer", "minimum": 0, "description": "Optional display order; defaults to the zero-based position in additionalParties." }, "sharePercent": { "type": "number", "minimum": 0, "maximum": 100, "description": "Optional share percentage for the additional party." } } }, "InvoiceProduct": { "x-examples": { "Example 1": { "productId": 7638, "itemType": "PRODUCT", "productName": "Accurate made letter", "unit": "m2", "price": "98.00", "vatPerc": "23%", "pkwiu": "3.2.7", "gtu": "04", "category": 15465, "favourite": false, "enabled": false } }, "type": "object", "examples": [ { "productId": 7638, "itemType": "PRODUCT", "productName": "Accurate made letter", "unit": "m2", "price": "98.00", "vatPerc": "23%", "pkwiu": "3.2.7", "gtu": "04", "category": 15465, "favourite": false, "enabled": false } ], "properties": { "productId": { "type": "integer" }, "itemType": { "type": "string", "enum": [ "PRODUCT", "SERVICE" ] }, "productName": { "type": "string" }, "unit": { "type": "string" }, "price": { "type": "string" }, "vatPerc": { "type": "string" }, "pkwiu": { "type": "string" }, "gtu": { "type": "string" }, "category": { "type": "integer" }, "favourite": { "type": "boolean" }, "enabled": { "type": "boolean" } } }, "SuccessResponse": { "title": "SuccessResponse", "x-stoplight": { "id": "yqo2bqzd7zztg" }, "type": "object", "properties": { "result": { "type": "string", "x-stoplight": { "id": "22hlosab8poxg" }, "default": "OK", "example": "OK", "enum": [ "OK" ] }, "data": { "type": "object", "x-stoplight": { "id": "i58aambagr5xn" } } }, "examples": [ { "result": "OK", "data": { "invoiceId": 12413 } } ], "description": "Regular format of success response in Altera API\nRetrieved information will always be stored in the 'data' node" }, "InvoiceTag": { "type": "object", "properties": { "tagId": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "color": { "type": "integer" } }, "x-examples": { "Example 1": { "tagId": 1, "name": "Marketing", "enabled": false, "color": 4286963618 } }, "examples": [ { "tagId": 1, "name": "Marketing", "enabled": false, "color": 4286963618 } ], "title": "", "description": "" } }, "securitySchemes": { "Authorization": { "name": "Authorization", "type": "apiKey", "in": "header", "description": "OpenApi Key created within Altera.app for a certain company" } } }, "security": [ { "Authorization": [] } ], "tags": [ { "name": "Configuration" }, { "name": "Data export" }, { "name": "Expenses" }, { "name": "Sales" } ] }