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 PUT - Create or update invoive DELETE single invoice POST - Initialise file uploading for invoice POST - Complete file uploading for invoice GET single invoice GET invoice status (amount paid and if it's fully paid)PUT - set invoice status (amount paid and if it's fully paid)

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
`orderReferenceNumber`	order number
`goodsIssuedNoteNumber`	Goods issued note number

PUT - Create or update invoive

In order to add invoice to ONe platform use PUT /api/v1/invoices/integrations/auth-required/invoices. The diagram below shows the dependency of communicating with the API:

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:

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:

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

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:

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:

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:

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:

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}"

Invoices

Table of contents

Glossary

PUT - Create or update invoive

DELETE single invoice

POST - Initialise file uploading for invoice

POST - Complete file uploading for invoice

GET single invoice

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

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