The invoice is a sales document confirming the transaction between two contractors. By issuing and forwarding an invoice, a tax obligation arises. The invoice must have the necessary data elements to be considered an invoice. The invoice must have detailed information about the transaction:
  • data identifying the document: number, date of issue,
  • buying and selling sides: seller and buyer,
  • specification of the subject of the transaction: name of goods or services, number, price, value,
  • data for the settlement of applicable taxes,
  • summary of the total amount due,
  • information on the agreed terms and form of payment.

Table of contents

Glossary

Name
Explanation
amountPaid
number, Gross value, determines whether the invoice has been fully paid
clientData: clientId tin clientType phone invoiceEmail
Buyer's data: Identifier number of buyer Type of buyer ("INDIVIDUAL" "ORGANIZATION”)
clientData β†’ addressData city country name postalCode street
Address of buyer
notes
invoice notes
payerData: clientId tin phone
payer data: Identifier number of payer
payerData→ addressData city country name postalCode street
address of payer
tenantData: tin
seller details:
tenantData β†’ addressData city country name postalCode street
address of seller
operatorData id name
operator assigned to the customer (this information is not displayed on the invoice) <uuid> for example - 00e9e304-e5df-450a-a861-0211c471096b
number
invoice number
receiptReferenceNumber
receipt number to which the invoice relates
splitPayment
Polish mpp - split payment mechanism (true or false)
isPaid
whether the invoice has been paid (true or false)
customerPurchaseNumbers
the customer order number to which the invoice relates
totalPrices: netPrice grossPrice taxValue
number number number
paymentDate
payment deadline
saleDate
sale date
currencyCode
possible to choose: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHF" "CLF" "CLP" "CNY" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "USS" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XFU" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW”
bankAccountNumber
Bank account number
items→ linePrices: netPrice grossPrice taxValue
Information on payments for a particular product line on the invoice: number number number
items→ taxRate: name value
Tax information: Ex. 5%, NP etc. number, Tax rate in percentage value without symbol, ex. 5 instead of 5%. It could be also a floating point value
items→ itemPrices: netPrice grossPrice taxValue
Information about price for products number number number
items→ additionalCosts type
Information about additional costs for products type of additional costs
additionalCosts β†’ itemPrices: netPrice grossPrice taxValue
Information about additional costs for products
additionalCosts β†’ linePrices: netPrice grossPrice taxValue
information on additional costs for product lines
paymentMethodData id name
payment method information Identifier number of payment name of information method

POST - add invoice

In order to add invoice to ONe platform use POST /api/v1/invoices/integrations/auth-required/invoices. The diagram below shows the dependency of communicating with the API:
Image without caption
Example request:
json
curl -X POST "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}" -H "Content-Type: application/json" -d " { "amountPaid": 1000, "clientData": { -- required "clientId": "org:e8104641-f655-42c0-9ed0-176a4fe8e604", -- required "tin": "11111111", "clientType": "ORGANIZATION", -- required "addressData": { -- required "city": "Wroclaw", -- required "country": "Poland", -- required "name": "Warehouse", -- required "postalCode": "55-555", -- required "street": "Leska" -- required }, "phone": "11111111", "invoiceEmail": "example@b2b.one" }, "notes": [ -- Required, but could be empty "example note" ], "payerData": { "clientId": "org:e8104641-f655-42c0-9ed0-176a4fe8e604", "addressData": { -- required if payerDatais using "city": "Wroclaw", -- required if addressData is using "country": "Poland", -- required if addressData is using "name": "Warehouse", -- required if addressData is using "postalCode": "55-555", -- required if addressData is using "street": "Leska" -- required if addressData is using }, "tin": "11111111111", "phone": "1111111111" }, "tenantData": { -- required "addressData": { -- required "city": "wroclaw", -- required "country": "Polska", -- required "name": "ONe Company", -- required "postalCode": "55-342", -- required "street": "Miedzyleska" -- required }, "tin": "11111111" -- required }, "operatorData": { "id": "86b86ebc-ba2f-4f47-bd46-e25803d81a0d", -- required if operatorData is using "name": "Kacper Kacprowicz" -- required if operatorData is using }, "number": "9999/06/2022", -- required "receiptReferenceNumber": "P92/06/2022", "splitPayment": true, "isPaid": true, "customerPurchaseNumbers": [ -- required "100/d" ], "documentDate": "2022-12-12", -- required "totalPrices": { -- required "netPrice": 110, -- required "grossPrice": 10, -- required "taxValue": 40 -- required }, "paymentDate": "2022-12-12", -- required "saleDate": "2022-12-12", -- required "currencyCode": "PLN", -- required "bankAccountNumber": "21434235231234", "items": [ -- required { "lineNumber": 1, -- required "splitPayment": true, "type": "PRODUCT", -- required "itemName": "Programowany, bezprzewodowy regulator temperatury", -- required "gtin": "534634523522", "sku": "091FLRFV2", -- required "series": "SALUS", "manufacturer": "SALUS LIMITED", "notes": [ -- required "example note" ], "linePrices": { -- required "netPrice": 550, -- required "grossPrice": 30, -- required "taxValue": 20 -- required }, "pkwiu": "58.13.10.0", "taxRate": { -- required "name": "Tax", "value": 0.23 }, "itemPrices": { -- required "netPrice": 990, -- required "grossPrice": 90, -- required "taxValue": 50 -- required }, "discount": 10, -- required "itemBasePrices": { "netPrice": 5, -- required if itemBasePrices is using "grossPrice": 15, -- required if itemBasePrices is using "taxValue": 5 -- required if itemBasePrices is using }, "additionalCosts": [ -- required { "type": "KGO", -- required "itemPrices": { -- required "netPrice": 8, -- required "grossPrice": 9, -- required "taxValue": 1 -- required }, "linePrices": { -- required "netPrice": 40, -- required "grossPrice": 80, -- required "taxValue": 0.23 -- required } } ], "quantity": 5, -- required "unit": "szt.", -- required "orderReferenceNumber": "100/d", "orderReferenceLineNumber": 1, "goodsIssuedNoteNumber": "71/06/2022", "goodsIssuedNoteLineNumber": 1 } ], "paymentMethodData": { -- required "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", -- required "name": "example payment name" -- required } }

DELETE single invoice

Use Delete /api/v1/invoices/integrations/auth-required/invoices to delete existing single invoice.
The sequence diagram below shows the dependency of communicating with the API:
Image without caption
Use the parameter below to delete invoice:
  • number - invoice number
Example request:
json
curl -X DELETE DELETE "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices?number=9999%2F06%2F2022" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"

POST - Initialise file uploading for invoice

On the ONe platform, it is possible to send a document in the form of a PDF file to a specific invocie. Use POST /api/v1/invoices/integrations/auth-required/invoices/file-upload-begin to receive parameters on the basis of which it will be possible to add a document to our server.
⚠️
To add the document to our server, use an external tool. For example Talend Api Tester. At the end of the description, we will show an example of this tool how to add a file to our server.
The sequence diagram below shows the dependency of communicating with the API:
Image without caption
Use the parameter to initialise file uploading for a specific document:
  • fileExtension
  • number
Example request:
json
curl -X POST "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices/file-upload-begin?fileExtension=pdf&number=9999%2F06%2F2022" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"
In response you will receive information about client blockade with the following data:
  • uploadUrl
  • uploadId
Example request:
json
{ "uploadUrl": "https://{link}", "uploadId": "d497a40c-1eaf-4e7e-9ce2-aff19f1cc650" }
When we get uploadUrland uploadId we can use tool to add documents to our server. Below we present how to do it using an Talend API Tester. 1 - method - PUT 2 - in headers - content-Type and choose application/pdf 3 - paste the link received in resonse to the request 4 - add file 5- press send
Image without caption
The document has been added to the server.

POST - Complete file uploading for invoice

This endpoint is used to complete the process of adding a document to our server. Use this endpoint after physically adding documents to the server - POST /api/v1/invoices/integrations/auth-required/invoices/file-upload-complete.
The sequence diagram below shows the dependency of communicating with the API:
Image without caption
se the parameter below to finalize file uploading:
  • uploadId
⚠️
uploadId it is possible to get from this endpoint (POST - Initialise file uploading for invoice)
Example request:
json
curl -X POST "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices/file-upload-complete?uploadId=fbe457b2-c090-436e-8e80-3473e4404819" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"

GET single invoice

There is possible to get specific invoice. Use GET/api/v1/invoices/integrations/auth-required/invoices/single using specific ID. The diagram below shows the dependence of communicating with the API:
Image without caption
Use the parameter in query below to get information about specific invoice:
  • number
Example request:
json
curl -X GET "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoice-corrections/single?number=111%2Fkorekta" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"
In response you will receive information about specific invoice
Example response:
json
{ "clientData": { "clientId": "org:e8104641-f655-42c0-9ed0-176a4fe8e604", "clientType": "ORGANIZATION", "addressData": { "city": "Wroclaw", "country": "Poland", "name": "Warehouse", "postalCode": "55-555", "street": "Leska" }, "tin": "11111111", "phone": "11111111", "invoiceEmail": "example@b2b.one" }, "payerData": { "clientId": "org:e8104641-f655-42c0-9ed0-176a4fe8e604", "addressData": { "city": "Wroclaw", "country": "Poland", "name": "Warehouse", "postalCode": "55-555", "street": "Leska" }, "tin": "11111111111", "phone": "1111111111" }, "tenantData": { "addressData": { "city": "wroclaw", "country": "Polska", "name": "ONe Company", "postalCode": "55-342", "street": "Miedzyleska" }, "tin": "11111111" }, "operatorData": { "id": "86b86ebc-ba2f-4f47-bd46-e25803d81a0d", "name": "Kacper Kacprowicz" }, "fileData": { "url": "https://eu-west-1-preprod-invoices-bucket.s3.eu-west-1.amazonaws.com/files/klient/fbe457b2c090436e8e803473e4404819-9999-06-2022.pdf?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEEIaCWV1LXdlc3QtMSJHMEUCIA%2FQ9NmRAEb7lRhOe%2BDhoqC598rOIVY3%2FEITptM716%2BmAiEA5qHwsM6IOHeXe1Licr01Z0ZT8HhfSOl2LqBldcgzeqAqmgQIu%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgwwMzQ2NzU3ODgwODciDOLpzpOIVRvNT0tLIyruAzOVS7m6x5yBBgokSMUhvLCm%2FZTdJJVIlAaViWOyqzhUMuiBjZgiAHJs2A0%2FWhM7POYD99ShumQZMGqzcD91egMUSiwcpwDb8SRz7E%2FZU1YdiuxKDmC6bKFUAtfbKhoSDnOVIObl%2FcSFknTTH%2FvKQVwwdNXspQ3qYrxUeh3KeEEY%2F0O%2F7SRRfMH3qosd2%2F8keBMYsXRfFrHOyECwtatKRwImhJKJQoV2Kz1hw9Yjq4pbrdxiblZtG6etTyp3KAzy2ogW4DM5UY7%2FuJF8AT%2BsisKYGzsvn9XHOhWDbx%2FD0OjnIpjPuqn0N1v7PEgO7zjdtyg1%2BluNxSerRFQleS2Sc35RrNylwyfdDavuclvWk8OesAMqEXl2ADaWeU8JSt4nu4GOnyw%2BtMSIaILsJJ9GEmyAjpZx2zpV4k2uQlL%2FbJSVtzo3yiCwhevD3YxC1NvNyjFFHOnJVRlBq4av2KVH%2F7v8%2BCe75MNkA8kg8U19gz23vMuKZrtO0vVWHvSVK6u8D8%2F3wqsclRF1F6sLtL0xeCIX2R620vprcHf%2FDjQmRz8mROAANdtuqD0LgQGKPMJHvQUkmCIA5k5EKYBN6LMhK28CyaLb5Ay1ANblcqj2hyehBRH13sP8RMlYH4PKDyDjXQ1jyLmYA83u4VKlfR41MKyOnZgGOqYBZCi%2FFn4G3E2%2B2ZsD3gmk%2FQMQrIkE2exmtgY%2FHh%2B6mpSKDOHvc3aTd%2FWVPFyKAKeXCf1SAyoYDBOjQJAw3%2FocGu3ndw93oa8kABBd19aRx234tM6tWtSXBixThVNsXPf8jous%2FK%2BEpOFh1onq%2BXNV84lWbdIP%2BlWU9Mf51XHdFDj4oyuvoFKhEZsMQMDOvF66YKhx3mq3XswIWJzqKvxUIjprRIYZYA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220825T112128Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAQQEWWRE37NY2O7PB%2F20220825%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=f688fab496cdd890fe29b528a1ed93909080bf843eb7aeea570c0071ab6e18ee", "extension": "pdf" }, "number": "9999/06/2022", "receiptReferenceNumber": null, "splitPayment": true, "amountPaid": 1000, "isPaid": true, "customerPurchaseNumbers": [ "100/d" ], "documentDate": "2022-12-12", "totalPrices": { "netPrice": 110, "grossPrice": 10, "taxValue": 40 }, "paymentDate": "2022-12-12", "saleDate": "2022-12-12", "currencyCode": "PLN", "bankAccountNumber": "21434235231234", "notes": [ "example note" ], "items": [ { "lineNumber": 1, "type": "PRODUCT", "itemName": "Programowany, bezprzewodowy regulator temperatury", "gtin": "534634523522", "sku": "091FLRFV2", "series": "SALUS", "manufacturer": "SALUS LIMITED", "notes": [ "example note" ], "linePrices": { "netPrice": 550, "grossPrice": 30, "taxValue": 20 }, "pkwiu": "58.13.10.0", "taxRate": { "value": 0.23, "name": "Tax" }, "itemPrices": { "netPrice": 990, "grossPrice": 90, "taxValue": 50 }, "discount": 10, "itemBasePrices": { "netPrice": 5, "grossPrice": 15, "taxValue": 5 }, "additionalCosts": [ { "type": "KGO", "itemPrices": { "netPrice": 8, "grossPrice": 9, "taxValue": 1 }, "linePrices": { "netPrice": 40, "grossPrice": 80, "taxValue": 0.23 } } ], "quantity": 5, "unit": "szt.", "orderReferenceNumber": "100/d", "orderReferenceLineNumber": 1, "goodsIssuedNoteNumber": "71/06/2022", "goodsIssuedNoteLineNumber": 1, "splitPayment": true } ], "paymentMethodData": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "example payment name" }, "invoiceCorrectionsReferenceNumbers": [], "orderReferenceNumbers": [ "100/d" ], "goodsIssuedNoteReferenceNumbers": [ "71/06/2022" ], "goodsReceivedNoteReferenceNumbers": [] }

GET invoice status (amount paid and if it's fully paid)

There is possible to get status of specific invoice. Use GET/api/v1/invoices/integrations/auth-required/invoices/status using specific ID. The diagram below shows the dependence of communicating with the API:
Image without caption
Use the parameter in query below to get information about status (amount paid and if it's fully paid) of specific invoice :
  • number
Example request:
json
curl -X GET "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices/status?number=9999%2F06%2F2022" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"
In response you will receive information about invoice payment status:
Example response:
json
{ "amountPaid": 1000, "isPaid": true }

PUT - set invoice status (amount paid and if it's fully paid)

With this endpoint it is possible to set whether the invoice has been fully paid and what amount has been paid. To do this, use PUT/api/v1/invoices/integrations/auth-required/invoices/status. The sequence diagram below shows the process:
Image without caption
Use the parameter in query below to set invoice status (amount paid and if it's fully paid)
  • number
Example request:
json
curl -X PUT "https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/invoices/status?number=9999%2F06%2F2022" -H "accept: */*" -H "one-tenant: {tenant}" -H "ApiAuth: {apiKey}"