digi.costpocket.com data formats and specs

Return types

All values are returned as strings. Please view all key-value pairs in our documentation. Scroll to bottom and select DocumentResponse: https://digi.costpocket.com/docs/

Example JSON

Please keep in mind that the following data is made up, and therefore not gone through actual validation by robot.

JSON Display

{
  "documentId": "ATS-dd-233232",
  "documentType": "RECEIPT",
  "documentDirection": "DEBIT",
  "orderId": "OA123123",
  "country": "EE",
  "issued": "2022-01-23",
  "due": "2022-01-25",
  "currency": "EUR",
  "subtotal": "100.00",
  "linesRounding": "0.01",
  "VAT": "20",
  "total": "120.00",
  "refNumber": "123123321",
  "cardLast4": "1234",
  "suppliers": [
    {
      "name": "Circle K Eesti AS",
      "address": "A. H. Tammsaare tee 47",
      "postalCode": "10115",
      "entityId": "10180925",
      "vatId": "EE100305317",
      "phone": "511234567",
      "email": "[email protected]"
    },
    {
      "name": "Tallinna Kaubamaja Grupp AS",
      "address": "Kaubamaja tn 1",
      "postalCode": "10143",
      "entityId": "10223439",
      "vatId": "EE100050109"
    }
  ],
  "VATRows": [
    {
      "subtotal": "12.50",
      "VAT": "2.50",
      "total": "15.00",
      "VATRate": "20"
    },
    {
      "subtotal": "100.00",
      "VAT": "5.00",
      "total": "105.00",
      "VATRate": "5"
    }
  ],
  "lines": [
    {
      "code": "6959655469806",
      "comment": "235/40R19 SAIL IBlaz EVO Rehv 96T XL RP",
      "type": "product",
      "unit": "tk",
      "unitPrice": "3",
      "unitPriceWithVAT": "3.6",
      "amount": "10",
      "subtotal": "30",
      "VATRate": "20",
      "VAT": "6",
      "total": "36",
      "isDiscount": "false",
      "totalNoDiscount": "50",
      "orderId": "OA123444"
    },
    {
      "code": "235401902110843496",
      "comment": "Banana",
      "type": "product",
      "unit": "tk",
      "unitPrice": "3",
      "unitPriceWithVAT": "3.6",
      "amount": "10",
      "subtotal": "30",
      "VATRate": "20",
      "VAT": "6",
      "total": "36",
      "isDiscount": "false",
      "totalNoDiscount": "40",
      "orderId": "OA123444"
    },
    {
      "comment": "Discount",
      "type": "product",
      "unit": "tk",
      "unitPrice": "5",
      "unitPriceWithVAT": "5",
      "amount": "1",
      "subtotal": "5",
      "total": "5",
      "isDiscount": "true"
    }
  ],
  "bankAccounts": [
    "EE631010220007574011",
    "EE631010220007574012"
  ]
}

Explanations for fields

Fields can be modified in the self-serve portal at https://digi.costpocket.com/portal/#/login

For most cases, robot validates all fields with several checks and different subsystems (AI, machine learning, databases, language collections). Usually, post-processing by you is not necessary.

Here are some tips on how to make parsing the values most efficient:

Supplier

Supplier is returned as a list of all companies found on the document. This may also include the receiver company, banks, courts and else
The actual supplier is the first one in the list
The actual receiver is usually the second one in the list
To reduce errors, we recommend to filter out your own company from the list, and then take the first company
Company data is validated via the country's entity databases or EU databases

Grand total

Parsed straight from document (not by calculation)

VAT rows

If possible, values are taken straight from the document
Missing values are calculated by robot and validated with numbers present on the document and the grand total

Item lines

Item lines always add up to the grand total of the document.
If needed, robot is capable of adding discounts, or creating a line without description. This is added as the last line, and marked as "isDiscount" = "true"
There generally is no point to recalculate any fields that robot provides, as robot is very strict in it's calculations
The fields that robot calculates itself are rounded to 4 decimal places. You might need to round this value yourself, depending on your usage
Similarly to VAT rows, missing values are calculated by robot and validated with grand total and also VAT rows
"SumNoDiscount" is only returned if it it bigger than "Sum"

Lines Rounding

Sometimes it happens that different companies calculate item lines differently on their invoices. Some add up all lines, and then add VAT to the neto total. Others add VAT to each line and then sum up the lines. To account for this, our robot also returns linesRounding.
LinesRounding is the difference between the grand total and the number you get when adding up all item lines.
Simple formula: linesRounding = grand total - (line1 + line2 +...)

ID-s (document number, order number etc)

Cleaned from unnecessary characters, trimmed, prefixes added to number

Bank accounts

Robot follows official bank account formats
Robot digitises all bank accounts on the document as a list

Document type

Either "RECEIPT" or "INVOICE"

Document direction

Either "DEBIT" or "CREDIT"

Country code

2 letter ISO code