The fiscal receipt is a document confirming the purchase and contains, among other things, the seller's details, information about the price of the product and the input tax on goods and services (VAT)

Table of contents Glossary POST - add fiscal receipt DELETE single fiscal receipt POST - Initialise file uploading for fiscal receipt POST - Complete file uploading for fiscal receipt GET single fiscal receipt GET fiscal receipt status (amount paid and if it's fully paid)PUT - set fiscal receipt status (amount paid and if it's fully paid)

Glossary

Name	Explanation
`amountPaid`	number, Gross value, determines whether the fiscal recipts has been fully paid
`createDateTime`
`notes`	fiscal recipts notes
`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
`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 fiscal recipts) <uuid> for example - 00e9e304-e5df-450a-a861-0211c471096b
`number`	fiscal recipts number
`receiptPrintoutNumber`	receipt number to which the fiscal recipts relates
`isPaid`	whether the fiscal recipts has been paid (true or false)
`customerPurchaseNumbers`	the customer order number to which the fiscal recipts 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 fiscal recipts: 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 fiscal receipt

In order to add fiscal receipt to ONe platform use POST /api/v1/invoices/integrations/auth-required/fiscal-receipt-corrections. 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/fiscal-receipts" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-H "Content-Type: application/json" 
-d "{
  "amountPaid": 5555,
  "createDateTime": "2022-12-24T20:00:00Z",
  "notes": [
    "example notes"
  ],
  "clientData": {  -- required
    "clientId": "org:838bed9a-8063-4e4c-93c3-f74b59fcaa5a",
    "tin": "PL8943138124",
    "clientType": "ORGANIZATION",  -- required
    "addressData": {  -- required
      "city": "Międzyleska",  -- required
      "country": "Poslka",  -- required
      "name": "One Company",  -- required
      "postalCode": "55-555",  -- required
      "street": "Wrocław"  -- required
    },
    "phone": "11111111",
    "invoiceEmail": "b2b@b2b.one"
  },
  "payerData": {
    "clientId": "org:838bed9a-8063-4e4c-93c3-f74b59fcaa5a",
    "addressData": {
      "city": "Międzyleska",
      "country": "Polska",
      "name": "One Company",
      "postalCode": "55-555",
      "street": "Wrocław"
    },
    "tin": "PL8943138124",
    "phone": "11111111111"
  },
  "tenantData": {  -- required
    "addressData": {  -- required
      "city": "Międzyleska",  -- required
      "country": "Poslka",  -- required
      "name": "One Company",  -- required
      "postalCode": "55-555",  -- required
      "street": "Wrocław"  -- required
    },
    "tin": "11111"  -- required
  },
  "operatorData": {
    "id": "a11efeb9-4e8b-4430-aca0-e361f5c63e43",
    "name": "Mateusz"
  },
  "number": "121/12/2022",  -- required
  "receiptPrintoutNumber": "123/12/20222",
  "isPaid": true,
  "customerPurchaseNumbers": [  -- required
    "ON/0/12/2022"
  ],
  "documentDate": "2022-12-24",  -- required
  "totalPrices": {  -- required
    "netPrice": 100,  -- required
    "grossPrice": 123,  -- required
    "taxValue": 23  -- required
  },
  "paymentDate": "2022-12-24",  -- required
  "saleDate": "2022-12-24",  -- required
  "currencyCode": "PLN",  -- required
  "bankAccountNumber": "12313123123",
  "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,
    "itemBasePrices": {
      "netPrice": 5, 
      "grossPrice": 15, 
      "taxValue": 5 
    },
    "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": " ON/0/12/2022",
    "orderReferenceLineNumber": 1,
    "goodsIssuedNoteNumber": "71/06/2022",
    "goodsIssuedNoteLineNumber": 1
  }
],
  "paymentMethodData": {  -- required
    "id": "0091900e-3e87-4eef-8df7-e6edbedb80ce",  -- required
    "name": "Gotówka przy odbiorze"  -- required
  }
}"

DELETE single fiscal receipt

In order to delete fiscal receipt in ONe platform use Delete /api/v1/invoces/integrations/auth-required/fiscal-receipts using specific number of fiscal receipts. The sequence diagram below shows the dependency of communicating with the API:

Use the parameter below to finalize file uploading:

number

Example request:

json
curl -X DELETE
"https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/fiscal-receipts?number=1231%2F12%2F20222" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

POST - Initialise file uploading for fiscal receipt

On the ONe platform, it is possible to send a document in the form of a PDF file to a specific fiscal receiot. Use POST /api/v1/invoces/integrations/auth-required/fiscal-receipts/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/fiscal-receipts/file-upload-begin?fileExtension=PDF&number=121%2F12%2F2022" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response you will receive information needed to add documents to our server

uploadUrl

uploadId

Example request:

json
"uploadId": "bbb48e1d-5db4-4b21-b419-2cdece72bc52",
  "uploadUrl": "https://{link}"
}

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 fiscal receipt

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/invoces/integrations/auth-required/fiscal-receipts/file-upload-complete. The sequence diagram below shows the dependency of communicating with the API:

Use the parameter below to finalize file uploading:

uploadId

Example request:

json
curl -X POST
"https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/fiscal-receipts/file-upload-complete?uploadId=ab099b4c-a208-4b32-a536-700e24420fe1" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

GET single fiscal receipt

There is possible to get specific fiscal receipt. Use GET/api/v1/invoces/integrations/auth-required/fiscal-receiptd/single using specific number. The diagram below shows the dependence of communicating with the API:

Use the parameter in query below to get information about specific fiscal receipt:

number

Example request:

json
curl -X GET 
"https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/fiscal-receipts/single?number=121%2F12%2F2022" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response you will receive information about fiscal receipt:

Example response:

json
{
  "clientData": {
    "clientId": "org:838bed9a-8063-4e4c-93c3-f74b59fcaa5a",
    "clientType": "ORGANIZATION",
    "addressData": {
      "city": "Międzyleska",
      "country": "Poslka",
      "name": "One Company",
      "postalCode": "55-555",
      "street": "Wrocław"
    },
    "tin": "PL8943138124",
    "phone": "11111111",
    "invoiceEmail": "b2b@b2b.one"
  },
  "payerData": {
    "clientId": "org:838bed9a-8063-4e4c-93c3-f74b59fcaa5a",
    "addressData": {
      "city": "Międzyleska",
      "country": "Polska",
      "name": "One Company",
      "postalCode": "55-555",
      "street": "Wrocław"
    },
    "tin": "PL8943138124",
    "phone": "11111111111"
  },
  "tenantData": {
    "addressData": {
      "city": "Międzyleska",
      "country": "Poslka",
      "name": "One Company",
      "postalCode": "55-555",
      "street": "Wrocław"
    },
    "tin": "11111"
  },
  "operatorData": {
    "id": "a11efeb9-4e8b-4430-aca0-e361f5c63e43",
    "name": "Mateusz"
  },
  "fileData": {
    "url": "https://eu-west-1-preprod-invoices-bucket.s3.eu-west-1.amazonaws.com/files/klient/bbb48e1d5db44b21b4192cdece72bc52-121-12-2022.pdf?X-Amz-Security-Token=IQoJb3JpZ2luX2VjELD%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJGMEQCIFVo0%2BlZoLG80evBXdV1bsISA%2BBp5KpUKg7pR3Sf4%2B%2BHAiAV5lp%2F9xLz3%2BYarEb%2B7tnPJjxzNWGJk4GMs0fWqMSoRyqaBAi5%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDAzNDY3NTc4ODA4NyIMM5g2rtDFsSy5jXKoKu4DqO7ltK8f3xiGa7VZX%2FkhDxMf5k7IYzEjq1G4UBriFJuX%2BXCR0ccE9944Jw0TtbeVU8uBdKw1hJq7qzyFL9Ekxy9hc0PxU%2FfPJRFK3uUDPNl9Y8HzM%2BXbzjVl7LDkjcHGQ3FT2hAWyNFpylrnH5MllgpEocDANCyFzYXl4DoV7yYzgxisIlFvrjh7aiFDAaKh2xTud5Zv5rL9SZKfKg3SDSv%2FMnV%2FwyqIzW1XuEQZYhf5b0LEE7ISv14piYM77RYoelSC%2Ftvii9bfvgtXlPPTVUEdMHyVPMqfvBFYYWCpBCleprwdyw7OeDWxQo8t7K8wIMS7i%2B3blLF4bvZE7I5rgdnFNBONBAOUWFCjQYgqN6JF84kEbR0mtXFf9mh5HocND96s1MBLNJn0E2QBBihpev0%2FXHuFQT1wwdVvEEA2NUel14YVYq4sO7x2%2F6Y%2Bfr1%2FK%2BmxEZDxnm31SeOSocwtaDs7H0I2Ya4eoGeNxIuXD58PR6EJyY2Sx%2By0SLc%2FZ8nd0MFl8xTy0a6CYmh%2B9KwXCQUgX8eby%2BHargaBKHWx1l5pFlodiznsD6e4uMr11WqbUj9mMCY%2FWdOvv%2FfnbDoUH2MR2w9l4pqj9xH45dquhbg9L%2B6iDV%2F%2Fkhv3cLJ2LYW9%2BaOzf7wS66y%2BdEJaYuowwJT3mwY6pwHbueuaS%2BcVJloa%2ByxasxILBmprAzdmOUbi87Iz3oIcFD5n65jgq4gjW7pXtBa5e6LqtSUZygV%2FwcsAj03X0iW8LjaKn12UNzLjGO5%2FSc%2F7lQOJKHXyrkoa0mWKFY0ihczzLEgDZLkRdeOsO2%2FjirN9Kl7JHrNLb4cEdpt7iZyoBU1x8nFr9ODmyzorRIRgC6sUw%2Flrm56wyTF2fX5zcKDcktxJtW7OkQ%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221123T095434Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAQQEWWRE3ZT6EIVM4%2F20221123%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=a215e78ab6a98d34003288211b2e5267d61fe5ab91b3b66898489e4b98d77fd4",
    "extension": "pdf"
  },
  "number": "121/12/2022",
  "receiptPrintoutNumber": "123/12/20222",
  "amountPaid": 5555,
  "isPaid": true,
  "customerPurchaseNumbers": [
    "ON/0/12/2022"
  ],
  "documentDate": "2022-12-24",
  "totalPrices": {
    "netPrice": 100,
    "grossPrice": 123,
    "taxValue": 23
  },
  "paymentDate": "2022-12-24",
  "saleDate": "2022-12-24",
  "currencyCode": "PLN",
  "bankAccountNumber": "12313123123",
  "notes": [
    "example notes"
  ],
  "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": " ON/0/12/2022",
      "orderReferenceLineNumber": 1,
      "goodsIssuedNoteNumber": "71/06/2022",
      "goodsIssuedNoteLineNumber": 1
    }
  ],
  "paymentMethodData": {
    "id": "0091900e-3e87-4eef-8df7-e6edbedb80ce",
    "name": "Gotówka przy odbiorze"
  },
  "fiscalReceiptCorrectionReferenceNumbers": [],
  "orderReferenceNumbers": [
    " ON/0/12/2022"
  ],
  "goodsIssuedNoteReferenceNumbers": [
    "71/06/2022"
  ],
  "goodsReceivedNoteReferenceNumbers": []
}

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

In order to get status of fiscal receipt in ONe platform use GET/api/v1/invoces/integrations/auth-required/fiscal-receipts/status. The sequence diagram below shows the process:

Use the parameter in query below to get goods issued note events:

number

Example request:

json
curl -X GET 
"https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/fiscal-receipts/status?number=121%2F12%2F2022" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response you will receive information about amount paid and it’s fully paid

Example response:

json
{
  "amountPaid": 5555,
  "isPaid": true
}

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

In order to set status of fiscal receipt in ONe platform use PUT/api/v1/invoces/integrations/auth-required/fiscal-receipts/status. It is possible to enter the value paid for the fiscal receipt and information whether the fiscal receipt has been paid. The sequence diagram below shows the process:

Use the parameter in query below to set fiscal receipt status:

number

Example request:

json
curl -X PUT
"https://api-preprod.one.unity.pl/api/v1/invoices/integrations/auth-required/fiscal-receipts/status?number=121%2F12%2F2022" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

Fiscal Recipts

Table of contents

Glossary

POST - add fiscal receipt

DELETE single fiscal receipt

POST - Initialise file uploading for fiscal receipt

POST - Complete file uploading for fiscal receipt

GET single fiscal receipt

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

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