Reference

Taxpayers and premises

The taxpayer and business-premise identifiers every fiscal request carries. They are created in the portal; the API reads them.

4 operations

List taxpayers

get/v1/taxpayers

Scope tenant:read

The taxpayers (legal entities) of the organization the credential belongs to, in the credential's environment only: a sandbox key sees sandbox taxpayers, a production key production ones.

Contract notes (OpenAPI)

Scoped to the caller's environment: a machine credential sees only the taxpayers of its own environment, a portal user sees both unless the organization hides its sandbox data.

Example

GET /v1/taxpayers

curl -X GET "https://api.bokapos.rs/v1/taxpayers" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

listTaxpayers: Responses
200 OK	Taxpayers`TaxpayerPage`
400 Bad Request	The command violates a Boka or fiscal rule`ErrorCode`

200 OK

{
  "items": [
    {
      "id": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "taxIdentifier": "115711881",
      "legalName": "BOKA GROUP DOO",
      "environment": "sandbox",
      "status": "active",
      "registrationNumber": "22196456",
      "address": "Roze Luksemburg 16",
      "city": "Beograd",
      "municipality": "Rakovica",
      "activityCode": "6201",
      "activityName": "Računarsko programiranje",
      "vatStatus": "in_vat",
      "createdAt": "2026-08-21T09:00:00.000Z",
      "updatedAt": "2026-08-21T09:00:00.000Z"
    }
  ]
}

Response: TaxpayerPage

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listTaxpayers: Response
Field	Type	Description
`items`required	array<Taxpayer>
`id`required	uuid
`taxIdentifier`required	string	pattern ^[0-9]{9}$
`legalName`required	string
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`status`required	string	`activesuspendedclosed`Values
`registrationNumber`optional	string\| null (nullable)	Serbian registration number (matični broj), usually prefilled from the company registry lookup. pattern ^[0-9]{8}$
`address`optional	string\| null (nullable)	max 300
`city`optional	string\| null (nullable)	max 100
`municipality`optional	string\| null (nullable)	max 100
`activityCode`optional	string\| null (nullable)	pattern ^[0-9]{4}$
`activityName`optional	string\| null (nullable)	max 150
`vatStatus`optional	string\| null (nullable)	Owner-declared VAT status. not_in_vat restricts every fiscal command to the non-VAT tax label (category N-TAX, label А in production); null means not declared and restricts nothing. `in_vatnot_in_vat`Values
`createdAt`required	date-time
`updatedAt`required	date-time

Read a taxpayer

get/v1/taxpayers/{taxpayerId}

Scope tenant:read

One taxpayer with PIB, status and VAT status.

Parameters

getTaxpayer: Parameters
Field	In	Type	Description
`taxpayerId`required	path	uuid

Example

GET /v1/taxpayers/{taxpayerId}

curl -X GET "https://api.bokapos.rs/v1/taxpayers/3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

getTaxpayer: Responses
200 OK	Taxpayer`Taxpayer`
404 Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

200 OK

{
  "id": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "taxIdentifier": "115711881",
  "legalName": "BOKA GROUP DOO",
  "environment": "sandbox",
  "status": "active",
  "registrationNumber": "22196456",
  "address": "Roze Luksemburg 16",
  "city": "Beograd",
  "municipality": "Rakovica",
  "activityCode": "6201",
  "activityName": "Računarsko programiranje",
  "vatStatus": "in_vat",
  "createdAt": "2026-08-21T09:00:00.000Z",
  "updatedAt": "2026-08-21T09:00:00.000Z"
}

Response: Taxpayer

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

getTaxpayer: Response
Field	Type	Description
`id`required	uuid
`taxIdentifier`required	string	pattern ^[0-9]{9}$
`legalName`required	string
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`status`required	string	`activesuspendedclosed`Values
`registrationNumber`optional	string\| null (nullable)	Serbian registration number (matični broj), usually prefilled from the company registry lookup. pattern ^[0-9]{8}$
`address`optional	string\| null (nullable)	max 300
`city`optional	string\| null (nullable)	max 100
`municipality`optional	string\| null (nullable)	max 100
`activityCode`optional	string\| null (nullable)	pattern ^[0-9]{4}$
`activityName`optional	string\| null (nullable)	max 150
`vatStatus`optional	string\| null (nullable)	Owner-declared VAT status. not_in_vat restricts every fiscal command to the non-VAT tax label (category N-TAX, label А in production); null means not declared and restricts nothing. `in_vatnot_in_vat`Values
`createdAt`required	date-time
`updatedAt`required	date-time

List business premises

get/v1/taxpayers/{taxpayerId}/business-premises

Scope tenant:read

The taxpayer's premises (Tax Administration business premises). Each has its own security element and payment mode.

Parameters

listBusinessPremises: Parameters
Field	In	Type	Description
`taxpayerId`required	path	uuid

Example

GET /v1/taxpayers/{taxpayerId}/business-premises

curl -X GET "https://api.bokapos.rs/v1/taxpayers/3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11/business-premises" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

listBusinessPremises: Responses
200 OK	Premises`BusinessPremisePage`
400 Bad Request	The command violates a Boka or fiscal rule`ErrorCode`

200 OK

{
  "items": [
    {
      "id": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "puIdentifier": "1234567",
      "name": "Web shop",
      "commerceMode": "distance",
      "environment": "sandbox",
      "paymentMode": "all",
      "status": "active",
      "createdAt": "2026-08-21T09:05:00.000Z",
      "updatedAt": "2026-08-21T09:05:00.000Z"
    }
  ]
}

Response: BusinessPremisePage

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listBusinessPremises: Response
Field	Type	Description
`items`required	array<BusinessPremise>
`id`required	uuid
`taxpayerId`required	uuid
`puIdentifier`required	string
`name`required	string
`commerceMode`required	const "distance"
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`paymentMode`required	PremisePaymentMode	Per-premise payment mode. The official rule is that one installation works either with every payment type or only with the restricted set (OTHER, CASH, WIRE_TRANSFER, VOUCHER). A payment outside the premise's set is refused with 422 PAYMENT_TYPE_NOT_ALLOWED_ON_PREMISE before any fiscal reservation, on every kind and transaction type. `allrestricted`default "all"Values
`status`required	string	`activesuspendedclosed`Values
`createdAt`required	date-time
`updatedAt`required	date-time

Read a business premise

get/v1/taxpayers/{taxpayerId}/business-premises/{businessPremiseId}

Scope tenant:read

One premise with its PU identifier, payment mode and status.

Parameters

getBusinessPremise: Parameters
Field	In	Type	Description
`taxpayerId`required	path	uuid
`businessPremiseId`required	path	uuid

Example

GET /v1/taxpayers/{taxpayerId}/business-premises/{businessPremiseId}

curl -X GET "https://api.bokapos.rs/v1/taxpayers/3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11/business-premises/b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

getBusinessPremise: Responses
200 OK	Business premise`BusinessPremise`
404 Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

200 OK

{
  "id": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "puIdentifier": "1234567",
  "name": "Web shop",
  "commerceMode": "distance",
  "environment": "sandbox",
  "paymentMode": "all",
  "status": "active",
  "createdAt": "2026-08-21T09:05:00.000Z",
  "updatedAt": "2026-08-21T09:05:00.000Z"
}

Response: BusinessPremise

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

getBusinessPremise: Response
Field	Type	Description
`id`required	uuid
`taxpayerId`required	uuid
`puIdentifier`required	string
`name`required	string
`commerceMode`required	const "distance"
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`paymentMode`required	PremisePaymentMode	Per-premise payment mode. The official rule is that one installation works either with every payment type or only with the restricted set (OTHER, CASH, WIRE_TRANSFER, VOUCHER). A payment outside the premise's set is refused with 422 PAYMENT_TYPE_NOT_ALLOWED_ON_PREMISE before any fiscal reservation, on every kind and transaction type. `allrestricted`default "all"Values
`status`required	string	`activesuspendedclosed`Values
`createdAt`required	date-time
`updatedAt`required	date-time