OpenAPI Specification
openapi: 3.0.0
info:
title: Xentral Account Point Of Sale API
version: v0.1
description: Xentral is an ERP platform.
contact:
name: Xentral
url: https://xentral.com
email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
description: Your Xentral Instance
variables:
xentralId:
default: xentral
- url: https://{domain}
description: Xentral at a custom domain
variables:
domain:
default: xentral.com
security:
- BearerAuth: []
tags:
- name: Point Of Sale
description: Point Of Sale (POS) endpoints.
paths:
/api/v1/cashiers:
get:
tags:
- Point Of Sale
operationId: cashier.list
summary: List cashiers
description: Lists all active cashiers.
parameters:
- name: project_id
in: query
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
data:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
name:
x-description-missing: true
type: string
nullable: true
example: Kassierer SW
number:
x-description-missing: true
type: string
nullable: true
example: '1001'
project:
description: Reference to another resource
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
example:
id: '1337'
permissionLevel:
x-description-missing: true
type: string
nullable: true
example: '0'
example:
id: '1'
name: Kassierer SW
number: '1001'
project:
id: '2'
permissionLevel: '0'
extra:
type: object
required:
- totalCount
- page
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
example: 1
page:
description: The pagination object containing the current page number and size
type: object
required:
- number
- size
additionalProperties: false
properties:
number:
description: The current page number
type: integer
example: 1
size:
description: The size of the pages
type: integer
example: 10
example:
number: 1
size: 10
example:
totalCount: 1
page:
number: 1
size: 10
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'406':
description: Requested resource representation does not exist.
'429':
description: Too many API calls made.
/api/v1/cashiers/{id}/pinCheck:
post:
tags:
- Point Of Sale
operationId: cashier.pinCheck
summary: Cashier PIN check
description: Checks a pin for cashier.
parameters:
- in: path
name: id
required: true
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
requestBody:
description: Verify PIN
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- pin
- project
properties:
pin:
type: string
nullable: false
pattern: \d{4}
project:
type: string
nullable: false
pattern: \d
examples:
Verify PIN:
value:
pin: '1234'
project: '5'
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
x-description-missing: true
type: object
additionalProperties: false
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
name:
x-description-missing: true
type: string
nullable: false
example: Kassierer SW
project:
description: Reference to another resource
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
example:
id: '1337'
permissionLevel:
x-description-missing: true
type: string
pattern: \d
nullable: false
example: '0'
example:
id: '1'
name: Kassierer SW
project:
id: '2'
permissionLevel: '0'
'400':
description: IETF RFC 9457 Problem API compliant response
content:
application/problem+json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- type
- title
- violations
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/request-validation
title:
type: string
minLength: 1
example: Request payload validation failed.
violations:
oneOf:
- type: array
items:
type: object
example:
username:
- This value should not be blank.
email:
- This value is not a valid email address.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
example:
_:
- This value should contain at most `9` elements.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflict
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- items
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflictItems
title:
type: string
minLength: 1
items:
type: array
items:
type: object
additionalProperties: false
required:
- id
- title
- messages
properties:
id:
type: integer
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- scopes
properties:
type:
type: string
enum:
- https://developer.xentral.com/reference/problems#token-scopes
title:
type: string
minLength: 1
scopes:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: object
additionalProperties:
type: array
items:
type: string
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'404':
description: Resource was not found or not enough access privileges
'406':
description: Requested resource representation does not exist.
'429':
description: Too many API calls made.
/api/v1/cashRegisters/{id}/balance:
get:
tags:
- Point Of Sale
operationId: cashRegister.balance
summary: View cash register balance
description: Retrieves the balance of a cash register.
parameters:
- in: path
name: id
required: true
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
x-description-missing: true
type: object
additionalProperties: false
properties:
openingBalance:
x-description-missing: true
type: string
nullable: false
example: 1,236.61
targetAmount:
x-description-missing: true
type: string
nullable: false
example: 1,236.61
example:
openingBalance: 1,236.61
targetAmount: 1,236.61
'400':
description: IETF RFC 9457 Problem API compliant response
content:
application/problem+json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- type
- title
- violations
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/request-validation
title:
type: string
minLength: 1
example: Request payload validation failed.
violations:
oneOf:
- type: array
items:
type: object
example:
username:
- This value should not be blank.
email:
- This value is not a valid email address.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
example:
_:
- This value should contain at most `9` elements.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflict
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- items
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflictItems
title:
type: string
minLength: 1
items:
type: array
items:
type: object
additionalProperties: false
required:
- id
- title
- messages
properties:
id:
type: integer
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- scopes
properties:
type:
type: string
enum:
- https://developer.xentral.com/reference/problems#token-scopes
title:
type: string
minLength: 1
scopes:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: object
additionalProperties:
type: array
items:
type: string
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'404':
description: Resource was not found or not enough access privileges
'406':
description: Requested resource representation does not exist.
'429':
description: Too many API calls made.
/api/v1/posJournals:
get:
tags:
- Point Of Sale
operationId: journal.list
summary: List POS journals
description: Lists all active POS journals.
parameters:
- name: filter
in: query
style: deepObject
schema:
oneOf:
- type: object
additionalProperties: false
properties:
id:
type: array
items:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
- type: array
items:
type: object
additionalProperties: false
properties:
key:
type: string
enum:
- id
- date
- customerId
- projectId
- salesOrderId
- externalOrderNumber
op:
type: string
enum:
- equals
- notEquals
- in
- notIn
- allIn
- allNotIn
- contains
- notContains
- startsWith
- endsWith
- greaterThan
- lessThan
value:
oneOf:
- type: string
- type: array
items:
type: string
- in: query
name: page
required: false
style: deepObject
schema:
type: object
additionalProperties: false
required:
- number
- size
properties:
number:
type: string
pattern: \d+
description: Page number should be an integer greater than or equal to 1
size:
type: string
pattern: \d+
description: Page size should usually be an integer between 10 and 50.
- name: order
in: query
style: deepObject
schema:
type: array
items:
type: object
additionalProperties: false
properties:
field:
type: string
enum:
- id
- date
- customerId
- projectId
dir:
type: string
enum:
- asc
- desc
responses:
'200':
description: Operation completed successfully.
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
data:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
date:
x-description-missing: true
type: string
format: date-time
nullable: true
example: '2020-09-23T14:20:08+02:00'
projectId:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
type:
x-description-missing: true
type: string
example: RE_Beleg
posFunction:
x-description-missing: true
type: string
example: TODO
doctype:
x-description-missing: true
type: string
example: rechnung
paymentType:
x-description-missing: true
type: string
example: eckarte
doctypeId:
x-description-missing: true
type: number
example: 10
documentNumber:
x-description-missing: true
type: string
example: '400009'
journalText:
x-description-missing: true
type: string
example: RE 400009 (POS)
revenueAccount:
x-description-missing: true
type: string
example: '4400'
currency:
x-description-missing: true
type: string
example: EUR
tax:
x-description-missing: true
type: number
format: float
example: 16
amountGross:
x-description-missing: true
type: number
format: float
example: 99
amountNet:
x-description-missing: true
type: number
format: float
example: 85.34
cashRegisterId:
x-description-missing: true
type: number
example: 5
customerId:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
createdAt:
x-description-missing: true
type: string
format: date-time
example: '2020-09-23T20:22:08+02:00'
createdBy:
x-description-missing: true
type: string
example: John Doe
businessTransactionType:
x-description-missing: true
type: string
nullable: true
example: TODO
qrString:
x-description-missing: true
type: string
nullable: true
example: null
fiscalDocumentReference:
description: This field represents an object with dynamic structure
type: object
additionalProperties: true
nullable: true
example: {}
salesOrder:
x-description-missing: true
type: object
additionalProperties: false
nullable: true
required:
- id
- number
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
number:
type: string
example: '200002'
externalOrderNumber:
type: string
example: '152'
example:
id: '5'
number: '200002'
externalOrderNumber: '152'
example:
id: '1'
date: '2020-09-23T14:20:08+02:00'
projectId: '6'
type: RE_Beleg
posFunction: ''
doctype: rechnung
paymentType: eckarte
doctypeId: 1
documentNumber: '400000'
journalText: RE 400000 (POS)
revenueAccount: '4400'
currency: EUR
tax: 16
amountGross: 98.99
amountNet: 85.34
cashRegisterId: 5
customerId: '36'
createdAt: '2020-09-23T14:20:08+02:00'
createdBy: John Doe
businessTransactionType: ''
salesOrder:
id: '4'
number: '200001'
externalOrderNumber: ''
qrString: null
extra:
type: object
required:
- totalCount
- page
additionalProperties: false
x-description-ignore: true
properties:
totalCount:
description: the total count of all items
type: integer
example: 1
page:
description: The pagination object containing the current page number and size
type: object
required:
- number
- size
additionalProperties: false
properties:
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-point-of-sale-api-openapi.yml