Xentral Invoice API
An invoice is a commercial document issued by a seller to a buyer relating to a sale transaction and indicating the products, quantities, and agreed-upon prices for products or services the seller had provided the buyer.
OpenAPI Specification
openapi: 3.0.0
info:
title: Xentral Account Invoice 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: Invoice
description: An invoice is a commercial document issued by a seller to a buyer relating to a sale transaction and indicating the products, quantities, and agreed-upon prices for products or services the seller had provided the buyer.
paths:
/api/v1/invoices:
post:
tags:
- Invoice
operationId: invoice.create
summary: Create invoice
description: Creates a invoice
requestBody:
description: Create an invoice object from a sales order or an empty invoice
content:
application/vnd.xentral.minimal+json:
schema:
type: object
additionalProperties: false
properties:
salesOrder:
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'
documentNumber:
description: The `Invoice Number` that will be assigned to the invoice. It can be used when creating an invoice from sales order
type: string
minLength: 1
maxLength: 35
examples:
Create invoice from sales order:
value:
salesOrder:
id: '12'
Create invoice from sales order and assign a document number:
value:
salesOrder:
id: '12'
documentNumber: '415263'
Create `empty` invoice:
value: {}
responses:
'201':
description: Resource successfully created response
headers:
Location:
schema:
type: string
example: https://example.xentral.biz/api/users/17
description: URI of the created resource
content:
text/html:
schema:
type: string
enum:
- ''
nullable: true
'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
'415':
description: Resource representation send in the request is not supported.
'429':
description: Too many API calls made.
get:
tags:
- Invoice
operationId: invoice.list
summary: List invoices
description: Returns a collection with all invoices.
parameters:
- name: filter
in: query
style: deepObject
description: 'The following filter key values are available:
**id** (string): Invoice ID
**invoice** (string): Invoice Number
**date** (date): accepted format: Y-m-d, example `2024-10-15`
**status** (string): `created` `released` `sent` `canceled` `completed` `partialCancellation`
**customerName** (string): first and last name of the Customer
**customerNumber** (string): Customer Number
**country** (string): Country Codes Alpha-2
**projectId** (string): Project ID
**projectName** (string): Project Name
**projectAbbr** (string): Project Abbreviation
**paymentMethod** (string): Payment Method
**paymentStatus** (string): `pending` `paid` `partlyPaid` `canceled` `partialCancellation` `badDebt` `debited`
**debit** (numeric): Debit, example: `10.50`
**balance** (numeric): Balance, example: `10.50`
**currency** (string): Currency ISO 4217 format, example `EUR`
**shippingMethod** (string): Shipping Method
**amountNet** (numeric): net amount of the Invoice, example: `10.50`
**salesOrder** (string): Sales Order ID
**updatedAt** (string): format: date-time : Sales updatedat, example: `2022-09-13T12:41:18+02:00`'
schema:
type: array
items:
type: object
additionalProperties: false
properties:
key:
type: string
enum:
- search
- id
- invoice
- date
- status
- customerName
- customerNumber
- country
- projectId
- projectName
- projectAbbr
- paymentMethod
- paymentStatus
- debit
- balance
- currency
- shippingMethod
- amountNet
- salesOrder
- dunningLevel
- updatedAt
example: date
op:
type: string
enum:
- equals
- notEquals
- in
- notIn
- exactlyIn
- allIn
- allNotIn
- contains
- notContains
- startsWith
- endsWith
- greaterThan
- lessThan
- is
- lessThanOrEquals
- greaterThanOrEquals
value:
oneOf:
- type: string
description: Used for the operations 'equals', 'notEquals', 'contains', 'notContains', 'startsWith', 'endsWith' and 'is'.
title: String
- type: array
description: Used for the operations 'in', 'notIn', 'exactlyIn', 'allIn' and 'allNotIn'.
title: 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
- invoice
- date
- customerName
- customerNumber
- country
- project
- paymentMethod
- debit
- currency
- paymentStatus
- balance
- status
- shippingMethod
- amountNet
- dunningDate
dir:
type: string
enum:
- asc
- desc
responses:
'200':
description: Operation completed successfully.
content:
application/vnd.xentral.minimal+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.
number:
x-description-missing: true
type: string
nullable: true
example: 2022-400000
date:
x-description-missing: true
type: string
format: date-time
example: '2023-06-27T00:00:00+02:00'
status:
x-description-missing: true
type: string
enum:
- created
- released
- sent
- canceled
- completed
- partialCancellation
- unknown
example: sent
address:
x-description-missing: true
type: object
additionalProperties: false
required:
- name
- country
- customerNumber
properties:
name:
type: string
country:
type: string
customerNumber:
type: string
example:
name: Maximilian S.
customerNumber: '10002'
country: DE
project:
x-description-missing: true
type: object
additionalProperties: false
nullable: true
required:
- id
- name
- abbreviation
properties:
id:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
name:
type: string
abbreviation:
type: string
example:
id: '4'
name: Amazon FBA
abbreviation: FBA
payment:
x-description-missing: true
type: object
additionalProperties: false
required:
- method
- status
- debit
- balance
properties:
method:
type: string
status:
type: string
enum:
- pending
- paid
- partlyPaid
- canceled
- partialCancellation
- badDebt
- debited
- unknown
debit:
description: Money object with amount and currency
example:
amount: '13.37'
currency: EUR
type: object
additionalProperties: false
properties:
amount:
description: A string representing the amount
type: string
format: float
example: '24.99'
currency:
type: string
pattern: '[A-Z]{3}'
enum:
- EUR
- USD
- JPY
- BGN
- CZK
- DKK
- GBP
- HUF
- PLN
- RON
- SEK
- CHF
- ISK
- NOK
- HRK
- RUB
- TRY
- AUD
- BRL
- CAD
- CNY
- HKD
- IDR
- ILS
- INR
- KRW
- MXN
- MYR
- NZD
- PHP
- SGD
- THB
- ZAR
- ARS
- CLP
- SAR
- AED
- QAR
description: Currency matches one of currency values as specified in ISO-4217.
example: PLN
balance:
description: Money object with amount and currency
example:
amount: '13.37'
currency: EUR
type: object
additionalProperties: false
properties:
amount:
description: A string representing the amount
type: string
format: float
example: '24.99'
currency:
type: string
pattern: '[A-Z]{3}'
enum:
- EUR
- USD
- JPY
- BGN
- CZK
- DKK
- GBP
- HUF
- PLN
- RON
- SEK
- CHF
- ISK
- NOK
- HRK
- RUB
- TRY
- AUD
- BRL
- CAD
- CNY
- HKD
- IDR
- ILS
- INR
- KRW
- MXN
- MYR
- NZD
- PHP
- SGD
- THB
- ZAR
- ARS
- CLP
- SAR
- AED
- QAR
description: Currency matches one of currency values as specified in ISO-4217.
example: PLN
example:
method: Amazon pay
status: paid
debit:
amount: '24.99'
currency: EUR
balance:
amount: '0.00'
currency: EUR
additionalFields:
type: array
items:
type: object
additionalProperties: false
properties:
key:
type: string
enum:
- amountNet
- shippingMethod
- orderNumber
- internet
- contactPerson
- distribution
- email
value:
type: string
example:
- key: orderNumber
value: '2231654'
tags:
description: A list of tags
type: array
items:
type: object
additionalProperties: false
properties:
id:
description: The identifier of the tag
type: string
pattern: \d+
example: '1337'
name:
description: The name of the tag
type: string
example: Active
color:
type: string
pattern: '[a-fA-F0-9]{6}'
example: ff0000
description: 'Hexadecimal color value in 6-digit format without the leading # character.'
dunningSettings:
description: Dunning setting for document
type: object
additionalProperties: false
required:
- level
- date
- comment
- sent
nullable: false
properties:
level:
type: string
enum:
- noReminder
- paymentReminder
- reminder1
- reminder2
- reminder3
- debtCollection
- lossOfReceivables
example: paymentReminder
date:
format: date
example: '2022-08-10'
comment:
format: string
example: This is a comment
sent:
type: boolean
format: boolean
example: true
example:
level: paymentReminder
date: '2022-08-10'
comment: This is a comment
sent: true
updatedBy:
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'
updatedAt:
x-description-missing: true
type: string
format: date-time
example: '2022-09-13T12:41:18+02:00'
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
text/csv:
schema:
type: string
'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
# --- truncated at 32 KB (858 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-invoice-api-openapi.yml