openapi: 3.0.0
info:
title: Xentral Account ProformaInvoice 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: ProformaInvoice
description: ProformaInvoice
paths:
/api/v3/proformaInvoices:
get:
tags:
- ProformaInvoice
summary: 🔒 List proforma invoices V3
description: 'This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.
This endpoint requires the following scopes: `proformaInvoice:read`.
Paginated list of proforma invoices.'
operationId: GET::api-v3-proformainvoices
parameters:
- name: filter
in: query
description: "The filter parameter is used to filter the results of the given endpoint. \n\n\n**Supported filter operators by key:** \n\n`id`: *equals*, *notEquals*, *in*, *notIn* \n\n`documentNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`writeProtection`: *equals*, *notEquals* \n\n`address.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`project.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`tags`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`tags.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`language`: *equals*, *notEquals*, *in*, *notIn* \n\n`bodyIntroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`bodyOutroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`project.abbreviation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`internalDesignation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`vatId`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`deliveryTerms`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`internalComment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`isDocumentSent`: *equals*, *notEquals* \n\n`editor.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`createdAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`updatedAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`documentAddress.name`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.title`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.contactPerson`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.department`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.subDepartment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.addressSupplement`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.street`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.zipCode`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.city`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.state`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.country`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.gln`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.email`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.phone`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`documentAddress.fax`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`financials.paymentMethod.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`financials.tax.disableTaxNotice`: *equals*, *notEquals* \n\n`financials.tax.taxRates.standard`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`financials.tax.taxRates.reduced`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`financials.tax.taxation`: *equals*, *notEquals*, *in*, *notIn* \n\n`totals.net.amount`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`totals.net.currency`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`financials.paymentTerms.paymentTargetDays`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`financials.paymentTerms.paymentTargetDiscount`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`financials.paymentTerms.paymentTargetDiscountDays`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals* \n\n`sales.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`salesOrder.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`lineItems.product.id`: *equals*, *notEquals*, *in*, *notIn* \n\n`lineItems.number`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith* \n\n`status`: *equals*, *notEquals*, *in*, *notIn*"
required: false
style: deepObject
schema:
type: array
items:
properties:
key:
type: string
enum:
- id
- documentNumber
- documentDate
- writeProtection
- address.id
- project.id
- tags
- tags.id
- language
- bodyIntroduction
- bodyOutroduction
- project.abbreviation
- internalDesignation
- vatId
- deliveryTerms
- internalComment
- isDocumentSent
- editor.id
- createdAt
- updatedAt
- documentAddress.name
- documentAddress.title
- documentAddress.contactPerson
- documentAddress.department
- documentAddress.subDepartment
- documentAddress.addressSupplement
- documentAddress.street
- documentAddress.zipCode
- documentAddress.city
- documentAddress.state
- documentAddress.country
- documentAddress.gln
- documentAddress.email
- documentAddress.phone
- documentAddress.fax
- financials.paymentMethod.id
- financials.tax.disableTaxNotice
- financials.tax.taxRates.standard
- financials.tax.taxRates.reduced
- financials.tax.taxation
- totals.net.amount
- totals.net.currency
- financials.paymentTerms.paymentTargetDays
- financials.paymentTerms.paymentTargetDiscount
- financials.paymentTerms.paymentTargetDiscountDays
- sales.id
- salesOrder.id
- lineItems.product.id
- lineItems.number
- status
op:
description: operator
type: string
enum:
- equals
- notEquals
- in
- notIn
- contains
- notContains
- startsWith
- endsWith
- lessThan
- lessThanOrEquals
- greaterThan
- greaterThanOrEquals
- isNull
- isNotNull
value:
description: The property value.
oneOf:
- title: String
type: string
- title: Array
type: array
items:
type: string
type: object
additionalProperties: false
examples:
Filter by document number:
summary: ''
value:
- key: documentNumber
op: equals
value: INV-12345
- name: sort
in: query
description: Sort via id, -id, documentNumber, -documentNumber, documentDate, -documentDate, customerNumber, -customerNumber, documentAddress.country, -documentAddress.country, project.id, -project.id, createdAt, -createdAt, updatedAt and -updatedAt. Default sort is id
required: false
style: form
explode: false
schema:
type: array
items:
enum:
- id
- -id
- documentNumber
- -documentNumber
- documentDate
- -documentDate
- customerNumber
- -customerNumber
- documentAddress.country
- -documentAddress.country
- project.id
- -project.id
- createdAt
- -createdAt
- updatedAt
- -updatedAt
- name: search
in: query
description: Full-text-style search across predefined columns.
required: false
schema:
type: string
- name: include
in: query
required: false
explode: false
schema:
type: array
items:
type: string
enum:
- address
- lineItems
- lineItems.customFields
- customFields
- lineItems.product
- project
- tags
- activity
- name: x-pagination
in: header
description: 'Controls the pagination format. Available types: simple, table, cursor. Defaults to ''simple'' if not specified.'
required: false
schema:
type: string
enum:
- simple
- table
- cursor
example: simple
- name: perPage
in: query
description: 'Number of items per page. Default: 15, Max: 1000'
required: false
schema:
type: integer
example: 15
- name: page
in: query
description: Page number. Only used with simple and table pagination.
required: false
schema:
type: integer
example: 1
- name: cursor
in: query
description: The cursor to use for the paginated call. Only used with cursor pagination. Not compatible with page parameter
required: false
schema:
type: string
example: eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
responses:
'200':
description: Paginated list of proforma invoices.
content:
application/json:
schema:
anyOf:
- title: 'Paginated Response: simple'
properties:
data:
type: array
items:
description: proforma invoice document
type: object
allOf:
- properties:
id:
description: ID of the document
type: string
example: '1'
documentNumber:
description: Document number. For drafts, this will be null.
type:
- string
- 'null'
example: I-12343
documentDate:
description: Main date of the document.
type:
- string
- 'null'
format: date
example: '2023-10-01'
writeProtection:
description: Indicates if the document is write protected.
type: boolean
example: false
customerNumber:
description: Customer number of the document.
type:
- string
- 'null'
example: CUST-54321
address:
description: Address entity of the document. By default, only the ID is returned. To get the full Address object, use the `include` parameter.
anyOf:
- required:
- id
- createdAt
- updatedAt
properties:
id:
type: string
example: '42'
isDeleted:
description: Flagged if the entry was deleted.
type: boolean
example: false
createdAt:
description: Creation timestamp
type: string
format: date-time
example: '2025-03-15T09:27:00+01:00'
updatedAt:
description: Last update timestamp
type: string
format: date-time
example: '2025-10-20T14:45:12+01:00'
type: object
additionalProperties: false
- properties:
id:
type: string
type: object
- type: 'null'
project:
description: Project entity of the document. By default, only the ID is returned. To get the full Project object, use the `include` parameter.
anyOf:
- required:
- id
- name
- abbreviation
properties:
id:
type: string
example: '54'
name:
type: string
example: Standard Project
abbreviation:
type: string
example: STANDARD
type: object
additionalProperties: false
- properties:
id:
type: string
type: object
- type: 'null'
tags:
description: Tags assigned to the document. This property is only returned if the `tags` include is used.
type: array
items:
properties:
id:
description: ID of the tag
type: string
example: '4'
title:
description: Title of the tag
type: string
example: important
type: object
documentAddress:
description: The recipients postal address of the document. This is is usually the postal address of the document's address entitiy, (e.g. customer), or is populated based on the preceding document. As this address is persisted on the document level, it can however be modified independently, and does not reflect changes that occurred since the document was created.
required:
- name
properties:
name:
description: 'Represents an address consisting of a physical address and contact information.
It is used in various documents, such as invoices, delivery notes, etc.'
type: string
example: John
type:
type:
- string
- 'null'
enum:
- mrs
- mr
- company
- other
example: mr
title:
type:
- string
- 'null'
example: Ms.
contactPerson:
type:
- string
- 'null'
example: Laura Schneider
department:
type:
- string
- 'null'
example: Research & Development
subDepartment:
type:
- string
- 'null'
example: AI Lab
addressSupplement:
type:
- string
- 'null'
example: Gebäude B, 4. Etage
street:
type:
- string
- 'null'
example: Fuggerstraße 11
zipCode:
type:
- string
- 'null'
example: '86150'
city:
type:
- string
- 'null'
example: Augsburg
state:
type:
- string
- 'null'
example: BY
country:
type:
- string
- 'null'
example: DE
salutation:
type:
- string
- 'null'
example: Sehr geehrte Damen und Herren
gln:
type:
- string
- 'null'
example: '1234567890123'
email:
type:
- string
- 'null'
example: laura.schneider@xentral.com
phone:
type:
- string
- 'null'
example: +1-234-567-8900
fax:
type:
- string
- 'null'
example: +1-234-567-8901
mobile:
type:
- string
- 'null'
example: +1-234-567-8902
type: object
example:
name: John
type: mr
title: Ms.
contactPerson: Laura Schneider
department: Research & Development
subDepartment: CAI Lab
addressSupplement: Gebäude B, 4. Etage
street: Fuggerstraße 11
zipCode: '86150'
city: Augsburg
state: BY
country: DE
salutation: Sehr geehrte Damen und Herren
gln: '1234567890123'
email: alice@example.com
phone: +1-234-567-8900
fax: +1-234-567-8901
mobile: +1-234-567-8902
additionalProperties: false
internalDesignation:
description: Internal designation, might be displayed in the letterhead.
type:
- string
- 'null'
example: FB-3860-L
isDocumentSent:
description: Indicates if the document has been sent to the recipient.
type: boolean
example: false
language:
description: ISO 639-1 Language of the document.
type: string
example: de
bodyIntroduction:
description: Text displayed on the document before the line items.
type:
- string
- 'null'
example: Dear customer, we are pleased to send you the following invoice.
bodyOutroduction:
description: Text displayed on the document after the line items.
type:
- string
- 'null'
example: Thank you for your business.
vatId:
description: VAT ID of the document.
type:
- string
- 'null'
example: DE123456789
deliveryTerms:
description: Delivery terms of the document.
type:
- string
- 'null'
example: DDP
internalComment:
description: Internal comment, does not show up on the document. Intended to be used for company-internal notes.
type:
- string
- 'null'
example: This is an internal comment.
editor:
properties:
id:
description: ID of the user who is responsible for the document.
type: string
example: '4'
type:
- object
- 'null'
printSettings:
properties:
withoutLetterhead:
description: For PDFs or physical documents, hide the letterhead
type: boolean
example: false
withoutProductText:
description: For PDFs or physical documents, hide the product text
type: boolean
example: false
type: object
activity:
description: Activity log entries associated with the document. To get activity object, use the `include` parameter.
type: array
items:
required:
- message
- causer
- causedAt
properties:
message:
type: string
example: Invoice released
causer:
type:
- string
- 'null'
example: John Doe
causedAt:
type: string
format: date-time
example: '2023-01-01T00:00:00Z'
type: object
additionalProperties: false
customFields:
description: Custom fields with their values and metadata
type: array
items:
properties:
key:
type: string
example: customField1
value:
type:
- string
- 'null'
example: prospect
label:
type: string
example: lifecycle
type: object
example:
- key: customer_category
value: Premium
label: Customer Category
- key: priority_level
value: High
label: Priority Level
updatedAt:
type: string
format: date-time
example: '2023-10-01T12:00:00Z'
createdAt:
type: string
format: date-time
example: '2023-10-01T12:00:00Z'
type: object
- properties:
financials:
description: Financials properties of the document
properties:
paymentMethod:
description: Payment method of the document. This is a reference to the payment method used for the document.
properties:
id:
type: string
example: '1'
type:
- object
- 'null'
paymentTerms:
description: Payment terms of the document
properties:
paymentTargetDays:
type: integer
example: 30
paymentTargetDiscount:
type: number
format: float
example: 2.5
paymentTargetDiscountDays:
type: integer
example: 10
type: object
tax:
description: Tax properties of the document
properties:
taxation:
description: Taxation of the document, e.g. "domestic" or "eu".
type: string
enum:
- domestic
- eu
- export
- exempt
example: domestic
disableTaxNotice:
description: Indicates if the tax notice should be disabled for this document.
type: boolean
example: false
taxRates:
description: Tax rates of the document. These values cannot be edited directly via the Xentral UI, and are set based on the tax settings and the delivery or billing region.
properties:
standard:
type: number
format: float
example: 19
# --- truncated at 32 KB (585 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-proformainvoice-api-openapi.yml