Business setup

Every request acts for one Business, the one your API key belongs to. Before your program creates documents, it reads what they must name of that Business: who it is, its currency, the VAT rates its documents offer and the bank accounts its Clients pay into.

The setup model

Properties

Name
business_id
Type
string
Description
The Business’s public id, a UUID that never changes. Every Webhook message about it carries it, so an OAuth app that hears several Businesses routes each message to the credential it holds for that one.
Name
is_test
Type
boolean
Description
Whether it is a Test business, for trying Essentio: it keeps no real books. Its documents are samples whose numbers carry TEST-, it exports no XML and issues no more Invoices a year than the Free plan.
Name
name
Type
string
Description
The name the Business trades under, as its documents print it.
Name
legal_name
Type
string or null
Description
Its registered legal name.
Name
address
Type
string or null
Description
The street address as its documents print it: one or more lines, separated by a line break.
Name
city, postal_code
Type
string or null
Description
As its documents print them.
Name
country
Type
string or null
Description
The country, as an ISO 3166-1 alpha-2 code: CY.
Name
vat_number
Type
string or null
Description
Its VAT number, as its documents print it. null while the Business is a Non-VAT Payer: it keeps the number it stored, prints none, and the number is back here when it is a VAT payer again. Its documents’ EN16931 XML carries none either.
Name
currency
Type
string
Description
The Business’s reporting currency, as an ISO 4217 code: EUR. Its reports are stated in it, and a Client created with no currency takes it.
Name
vat_rates
Type
array of VAT rates
Description
The Business’s active VAT rates, highest first. The first is the one Essentio starts a new Line and a new Product at.
Name
bank_accounts
Type
array of bank accounts
Description
The Business’s bank accounts, oldest first.

A VAT rate

Name
id
Type
integer
Description
The rate’s identifier.
Name
name
Type
string
Description
The Business’s name for it: Standard.
Name
rate
Type
string
Description
The rate in percent, as a decimal string: "19.00". A document Line’s vat_rate and a Product’s take it.
Name
vat_category
Type
string
Description
The VAT category a Line takes at this rate: Z at 0, S above it. Another value may be added within v1: keep one you do not know. See A Line’s VAT.

A bank account

Name
id
Type
integer
Description
The account’s identifier: what a document’s bank_account_ids and a Client’s preferred_bank_account_ids take.
Name
account_name
Type
string
Description
The Business’s name for the account.
Name
bank_name
Type
string
Description
The bank.
Name
account_number
Type
string or null
Description
The account number.
Name
iban
Type
string or null
Description
The IBAN.
Name
is_default
Type
boolean
Description
Whether it is the Business’s default account. A Business has at most one.

A Line’s VAT

Every Line of a document names its VAT twice: a vat_rate (a decimal string, "19.00") and a vat_category (EN16931’s code). The two must agree, or the document is refused:

At one of the Business’s rates, send the rate’s rate as vat_rate and its vat_category as vat_category: S (standard) for a rate above 0, Z (zero-rated) for 0. Neither needs an exemption code. This is what Essentio does when a Line is priced from a rate or a Product.
Exempt, reverse-charged, intra-community, exported or out of scope, the Line’s vat_rate is "0", its vat_category is E, AE, K, G or O, and it must carry a vat_exemption_code: one of the codes below, the one for its category. The Business decides which applies to its sale; the setup offers none.

S needs a rate above 0, and every category but S needs a rate of 0. A Product carries a rate and no category, so a Line billing it takes the category of its rate.

Exemption codes

The VATEX codes of EN16931 (BT-121) that Essentio takes, and the text a document prints for each:

Code	Category	Printed as
`VATEX-EU-AE`	`AE`	Reverse charge — VAT to be accounted for by the recipient (Art. 194–199a Directive 2006/112/EC)
`VATEX-EU-IC`	`K`	Intra-Community supply — exempt under Art. 138 Directive 2006/112/EC
`VATEX-EU-G`	`G`	Export outside the EU — exempt under Art. 146 Directive 2006/112/EC
`VATEX-EU-O`	`O`	Not subject to VAT
`VATEX-EU-79-C`	`E`	Exempt — Art. 79(c) Directive 2006/112/EC (disbursements)
`VATEX-EU-132`	`E`	Exempt — Art. 132 Directive 2006/112/EC (activities in the public interest)
`VATEX-EU-135`	`E`	Exempt — Art. 135 Directive 2006/112/EC (financial, insurance, property)
`VATEX-EU-143`	`E`	Exempt — Art. 143 Directive 2006/112/EC (importation)
`VATEX-EU-148`	`E`	Exempt — Art. 148 Directive 2006/112/EC (international transport)
`VATEX-EU-151`	`E`	Exempt — Art. 151 Directive 2006/112/EC (diplomatic, international bodies)
`VATEX-EU-309`	`E`	Exempt — Art. 309 Directive 2006/112/EC (travel agents)
`VATEX-EU-D`	`E`	Intra-Community acquisition from second-hand means of transport
`VATEX-EU-F`	`E`	Intra-Community acquisition of second-hand goods
`VATEX-EU-I`	`E`	Intra-Community acquisition of works of art
`VATEX-EU-J`	`E`	Intra-Community acquisition of collectors items and antiques

GET/v1/business

Retrieve the Business’s setup

The Business your key belongs to — as its documents print it — with its currency, VAT rates and bank accounts. Every Role may read it, a Viewer’s key included.

Answers

Name
200
Type
BusinessSetup
Description
The Business’s setup.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
The Role of the API key or Connected app may not do this.

Request

GET/v1/business

curl https://api.essentio.pro/v1/business \
  -H "Authorization: Bearer ess_your_api_key"

Response

{
  "business_id": "5c92e0ef-5111-492f-af6e-9dcbafc9587a",
  "is_test": false,
  "name": "Keyed",
  "legal_name": "Keyed Trading Ltd",
  "address": "1 Harbour Road\nSuite 4",
  "city": "Limassol",
  "postal_code": "3036",
  "country": "CY",
  "vat_number": "CY10311000X",
  "currency": "EUR",
  "vat_rates": [
    { "id": 1, "name": "Standard 19%", "rate": "19.00", "vat_category": "S" },
    { "id": 2, "name": "Reduced 9%", "rate": "9.00", "vat_category": "S" },
    { "id": 4, "name": "Zero 0%", "rate": "0.00", "vat_category": "Z" }
  ],
  "bank_accounts": [
    {
      "id": 3,
      "account_name": "Main account",
      "bank_name": "Bank of Cyprus",
      "account_number": "357012345678",
      "iban": "CY17002001280000001200527600",
      "is_default": true
    }
  ]
}