{
"openapi": "3.0.0",
"info": {
"title": "Xentral API",
"version": "v0.1",
"description": "Xentral is an ERP platform.",
"contact": {
"name": "Xentral",
"url": "https://xentral.com",
"email": "api@xentral.com"
}
},
"tags": [
{
"name": "Accounting Export",
"description": "Accounting Export endpoints"
},
{
"name": "Analytics",
"description": "Everything that is powered by the Xentral Analytics Platform."
},
{
"name": "App",
"description": "App represents information about apps available in the appstore."
},
{
"name": "AuthPlatform",
"description": "AuthPlatform represents the oauth login for Xentral"
},
{
"name": "Collection",
"description": "Create and manage collections for your reports."
},
{
"name": "Contact",
"description": "Contacts represents the individual or company information."
},
{
"name": "Credit",
"description": "Get information about your current current and monthly credits regarding Report usage."
},
{
"name": "Credit Note",
"description": "A credit note is a document you send to your customer to correct a mistake on an order or an invoice, or to refund an amount paid for products or services."
},
{
"name": "Credit Note Tag",
"description": "Credit Note resource tags management."
},
{
"name": "Customer",
"description": "Customer represents an information related to company, or individual person."
},
{
"name": "Customer - Contact Person",
"description": "Contact person information related to a specific customer"
},
{
"name": "Customer Tag",
"description": "Customer resource tags management."
},
{
"name": "Delivery Note",
"description": "Delivery notes."
},
{
"name": "Delivery Note Tag",
"description": "Delivery notes tags."
},
{
"name": "Delivery",
"description": "Delivery information."
},
{
"name": "Delivery Terms",
"description": "Delivery Terms"
},
{
"name": "Device Gateway",
"description": "Device Gateway"
},
{
"name": "Documentation",
"description": "Get documentation about our data catalog, tables and columns."
},
{
"name": "Email",
"description": "Email related operations"
},
{
"name": "Email Account",
"description": "Email accounts that are available for sending/receiving emails in Xentral."
},
{
"name": "Employee",
"description": "Employees"
},
{
"name": "Exchange Rates",
"description": "Exchange rates provided by EXR Service."
},
{
"name": "External Reference",
"description": "External shop references that are linked to a product."
},
{
"name": "External Reference Target",
"description": "All external shops that exists within Xentral"
},
{
"name": "Goods Receipt",
"description": "Goods Receipt for physical incoming goods."
},
{
"name": "Inventory",
"description": "Inventory run management."
},
{
"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."
},
{
"name": "Invoice Tag",
"description": "Invoice resource tags management."
},
{
"name": "License",
"description": "License and app subscription management"
},
{
"name": "Liability",
"description": "Returns a collection with all liabilities."
},
{
"name": "Matrixproduct",
"description": "Manage options for products."
},
{
"name": "Mobile Picking Tote",
"description": "A picking tote resource."
},
{
"name": "Oauth",
"description": "Oauth tokens for external providers."
},
{
"name": "Payment Methods",
"description": "Payment Methods resource"
},
{
"name": "Payment Terms Group",
"description": "PaymentTermsGroups can be used to group customers with identical payment terms such as different discounts, payment targets, and free postage options."
},
{
"name": "Password Reset",
"description": "Password Reset represents an one-time access key to change the password of the connected User."
},
{
"name": "Personal Access Token",
"description": "Personal access token which are used to authenticate against API v3."
},
{
"name": "Picking Run",
"description": "A picking run contains instructions how to retrieve stock for fulfilling a single or a set of orders"
},
{
"name": "Pick List",
"description": "A picking list contains instructions how to retrieve stock for fulfilling a single or a set of orders"
},
{
"name": "Point Of Sale",
"description": "Point Of Sale (POS) endpoints."
},
{
"name": "Printer",
"description": "An entity represent the physical printer connected to the instance."
},
{
"name": "Printer Setup",
"description": "A printer setup for the wizard."
},
{
"name": "Product",
"description": "Product represents the services or things given company sells in the business."
},
{
"name": "Product Category",
"description": "Product Category represents the Product Category Tree that can be used to categorise products."
},
{
"name": "Product Free Field",
"description": "40 product free fields can be used and individually labeled."
},
{
"name": "Product Import",
"description": "Management of various ways of importing products into the system."
},
{
"name": "Product Media",
"description": "Images of a product"
},
{
"name": "Product Tag",
"description": "Product resource tags management."
},
{
"name": "Product Property",
"description": "Product properties describe its physical traits."
},
{
"name": "Product Merchandise Group",
"description": "Product merchandise groups."
},
{
"name": "Production",
"description": "Production resource management"
},
{
"name": "Project",
"description": "Project resource."
},
{
"name": "Provisional Return",
"description": "Provisional Return resource."
},
{
"name": "Purchase Order",
"description": "Purchase Orders made at a supplier."
},
{
"name": "Purchase Price",
"description": "PurchasePrices determine the prices used for the purchasing of products."
},
{
"name": "Query",
"description": "Create, manage and export reports and report results based on SQL queries against your data."
},
{
"name": "Report",
"description": "Create, manage and export reports and report results based on SQL queries against your data."
},
{
"name": "Report Usage",
"description": "Provide information about your usage in terms of credits spent."
},
{
"name": "Return",
"description": "Return represents incoming shipments from customer to supplier"
},
{
"name": "Return Reason",
"description": "Return reason describes why an item is being returned"
},
{
"name": "Ruleset",
"description": "Provide information about the accessible Analytics Platform features based on the package the license is on."
},
{
"name": "Sales Channel",
"description": "SalesChannel are the configured Shops/Marketplaces."
},
{
"name": "Sales Channels Product Settings",
"description": "Sales Channel Settings inside a product."
},
{
"name": "Sales Price",
"description": "SalesPrices determine the prices used in sales to customers."
},
{
"name": "Sales Order",
"description": "SalesOrders are an outbound orders, meaning that someone has bought from you."
},
{
"name": "Setting",
"description": "Settings represents the application's configurations."
},
{
"name": "Setting Item",
"description": "SettingItems represents settings menu."
},
{
"name": "Shipping Methods",
"description": "Shipping methods"
},
{
"name": "Stock Movement Types",
"description": "Stock movement type"
},
{
"name": "Supplier",
"description": "Suppliers represents an information related to providers of goods the company is managing."
},
{
"name": "Supplier Tag",
"description": "Supplier resource tags management."
},
{
"name": "System Health",
"description": "System Health"
},
{
"name": "Tax Rates",
"description": "Tax Rates resource"
},
{
"name": "Token",
"description": "Valid tokens grant access to API endpoints. You can exchange credentials in POST endpoint to create one."
},
{
"name": "Ticket",
"description": "Tickets (currently only ticket /queues)"
},
{
"name": "UI Analytics",
"description": "Information about instance statistics and insights."
},
{
"name": "UI Bookmark",
"description": "Bookmarks allow saving external resources for a quick access."
},
{
"name": "UI Calendar",
"description": "Calendar hosts resources related to the events scheduled in the company."
},
{
"name": "UI Query",
"description": "Collection of endpoints which return data for BI features in the front end."
},
{
"name": "UI Search",
"description": "Search allows to look for information matching given query and interact with it."
},
{
"name": "UI SystemMessage",
"description": "SystemMessage is an automated status check verifying correct behavior of one of the many modules."
},
{
"name": "User",
"description": "User represents a Xentral account used to access other parts of the system."
},
{
"name": "User Invitation",
"description": "Invites created for new users."
},
{
"name": "User Email Verification",
"description": "User Email Verification"
},
{
"name": "Storage Location",
"description": "Represents the spaces within a warehouse"
},
{
"name": "Storage Item",
"description": "Represent a storage item in a storage location"
},
{
"name": "Warehouse",
"description": "Represents a location with storage space"
},
{
"name": "Webhook",
"description": "Manage webhooks."
},
{
"name": "Tax Rate",
"description": "Represents a tax rate for a product on given day and for given country"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Bearer token obtained in POST /tokens endpoint or pregenerated in the system."
}
}
},
"security": [
{
"BearerAuth": []
}
],
"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"
}
}
}
],
"x-readme": {
"samples-languages": []
},
"paths": {
"/api/analytics/report": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.list",
"summary": "Get list of reports.",
"description": "Returns a list of reports (official Xentral reports and custom reports)",
"responses": {
"200": {
"description": "Report response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Report"
],
"operationId": "analytics.report.create",
"summary": "Create report",
"description": "Creates a new report and returns the new record",
"requestBody": {
"description": "Create report request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"report"
],
"example": {
"report": {
"title": "My report",
"description": "This is my report",
"userId": 1,
"sqlString": "SELECT * FROM users",
"isFavorite": true,
"isReadOnly": false,
"collectionId": 1,
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
},
"properties": {
"report": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"collectionId"
],
"properties": {
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"type": "boolean",
"description": "Is report read-only",
"example": false
},
"collectionId": {
"type": "number",
"description": "ID of the collection the report belongs to",
"example": 1
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
}
}
}
}
},
"examples": {
"example": {
"summary": "Example report payload",
"value": {
"report": {
"title": "My report",
"description": "This is my report",
"userId": 1,
"sqlString": "SELECT * FROM users",
"isFavorite": true,
"isReadOnly": false,
"collectionId": 1,
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Report response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/analytics/report/{id}": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.get",
"summary": "Get report by ID.",
"description": "Returns a single report by ID",
"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": "Report response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"patch": {
"tags": [
"Report"
],
"operationId": "analytics.report.update",
"summary": "Update a report",
"description": "Updates an existing report specified by its ID and returns the new record",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Create report request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"report"
],
"example": {
"report": {
"title": "My report",
"description": "This is my report",
"userId": 1,
"sqlString": "SELECT * FROM users",
"isFavorite": true,
"isReadOnly": false,
"collectionId": 1,
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
},
"properties": {
"report": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"collectionId"
],
"properties": {
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"type": "boolean",
"description": "Is report read-only",
"example": false
},
"collectionId": {
"type": "number",
"description": "ID of the collection the report belongs to",
"example": 1
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
}
}
}
}
},
"examples": {
"example": {
"summary": "Example report payload",
"value": {
"report": {
"title": "My report",
"description": "This is my report",
"userId": 1,
"sqlString": "SELECT * FROM users",
"isFavorite": true,
"isReadOnly": false,
"collectionId": 1,
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Report response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
},
"delete": {
"tags": [
"Report"
],
"operationId": "analytics.report.delete",
"summary": "Delete a report.",
"description": "Deletes an existing report specified by its ID and returns the deleted record",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/report/{id}/export": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.export.list",
"summary": "List all recent exports for that report",
"description": "List all exports for that report",
"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": "Query execution response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
},
"description": "Details of the query execution"
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Report"
],
"operationId": "analytics.report.export.create",
"summary": "Create an export for given report",
"description": "Create an export for given report based on the SQL statement that is stored with the report",
"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": "Query execution response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
},
"description": "Details of the query execution"
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"402": {
"description": "Resource can not be accessed because you exceeded the credit limit."
},
"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."
}
}
}
},
"/api/analytics/report/{id}/permalink": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.permalink.get",
"summary": "Get permalink for report",
"description": "Get permanent download link for downloading report results",
"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": "Report permalink response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"reportId": {
"example": 1,
"type": "number",
"description": "ID of the report"
},
"validUntil": {
"example": "2023-01-01",
"type": "string",
"format": "date",
"description": "Date until the permalink is valid"
},
"format": {
"example": "csv",
"type": "string",
"description": "Export format"
},
"token": {
"example": "TCWfnii9zACLsCZBKSOkx7uyKyPNE8yIxvTmnGTNeoOxI39hCU6d3kQ3sYL8W8qcsI4tM8Eqxv1nPsdZfOjObbOeHSRmprh2rbQ9w8HzwQR6qzPBDVQDamJkU7FaPPxfhGKzVfM7FCapYCE3EZQt5JJUEQ6jFbmzEpIPBaMBtONw4rx2Rt0nijhyeaU5omzSl6Vdm8TsNakkynalV36SnZuneuw9OB4RULEXHs2SeqhLt7BI61JpL4jxfeX5b6lI",
"type": "string",
"description": "Random string token"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Report"
],
"operationId": "analytics.report.permalink.create",
"summary": "Get permalink for report",
"description": "Create permanent download link for downloading report results\"",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Payload for creating permalink for report",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"permalink"
],
"example": {
"permalink": {
"validUntil": "2023-01-01",
"format": "csv"
}
},
"properties": {
"permalink": {
"type": "object",
"additionalProperties": false,
"properties": {
"validUntil": {
"example": "2023-01-01",
"type": "string",
"format": "date",
"description": "Date until the permalink is valid"
},
"format": {
"example": "csv",
"type": "string",
"description": "Export format"
}
}
}
}
},
"examples": {
"example": {
"summary": "Example of a report permalink",
"value": {
"permalink": {
"validUntil": "2023-01-01",
"format": "csv"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Report permalink response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"reportId": {
"example": 1,
"type": "number",
"description": "ID of the report"
},
"validUntil": {
"example": "2023-01-01",
"type": "string",
"format": "date",
"description": "Date until the permalink is valid"
},
"format": {
"example": "csv",
"type": "string",
"description": "Export format"
},
"token": {
"example": "TCWfnii9zACLsCZBKSOkx7uyKyPNE8yIxvTmnGTNeoOxI39hCU6d3kQ3sYL8W8qcsI4tM8Eqxv1nPsdZfOjObbOeHSRmprh2rbQ9w8HzwQR6qzPBDVQDamJkU7FaPPxfhGKzVfM7FCapYCE3EZQt5JJUEQ6jFbmzEpIPBaMBtONw4rx2Rt0nijhyeaU5omzSl6Vdm8TsNakkynalV36SnZuneuw9OB4RULEXHs2SeqhLt7BI61JpL4jxfeX5b6lI",
"type": "string",
"description": "Random string token"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"delete": {
"tags": [
"Report"
],
"operationId": "analytics.report.permalink.delete",
"summary": "Invalidate permalink for report",
"description": "Invalidate permanent download link for downloading report results",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/report/{id}/permalink/{token}": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.permalink.download",
"summary": "Download report via permalink",
"description": "Download latest report export result via permalink. Using a permalink will allow anyone with the link to view the report. We recommend to use other export features for exporting data.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"in": "path",
"name": "token",
"required": true,
"description": "A randomly generated, 256 characters long, alphanumeric string.",
"schema": {
"type": "string",
"example": "TCWfnii9zACLsCZBKSOkx7uyKyPNE8yIxvTmnGTNeoOxI39hCU6d3kQ3sYL8W8qcsI4tM8Eqxv1nPsdZfOjObbOeHSRmprh2rbQ9w8HzwQR6qzPBDVQDamJkU7FaPPxfhGKzVfM7FCapYCE3EZQt5JJUEQ6jFbmzEpIPBaMBtONw4rx2Rt0nijhyeaU5omzSl6Vdm8TsNakkynalV36SnZuneuw9OB4RULEXHs2SeqhLt7BI61JpL4jxfeX5b6lI",
"description": "Random string token."
}
}
],
"responses": {
"202": {
"description": "Request accepted. URL token is valid. No data can be provided yet, but data processing got triggered.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"301": {
"description": "Permanent redirect response",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "https://example.xentral.biz/api/users/17"
},
"description": "URI of the location you are redirected to"
}
},
"content": {
"text/html": {
"schema": {
"type": "string",
"enum": [
""
],
"nullable": true
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"402": {
"description": "Resource can not be accessed because you exceeded the credit limit."
},
"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."
}
}
}
},
"/api/analytics/report/{id}/schedule": {
"get": {
"tags": [
"Report"
],
"operationId": "analytics.report.schedule.list",
"summary": "List schedules for report",
"description": "List all scheduled report exports",
"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": "Report schedule response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"reportId",
"uuid",
"crontab",
"exportType",
"createdAt",
"updatedAt"
],
"properties": {
"reportId": {
"example": 1,
"type": "number",
"description": "ID of the report"
},
"crontab": {
"example": "0 0 * * *",
"type": "string",
"description": "Crontab expression for scheduling the report"
},
"exportType": {
"example": "csv",
"type": "string",
"description": "Export type"
},
"uuid": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "UUID of the report schedule"
},
"lastExecution": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Last execution time"
},
"nextExecution": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Next execution time"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Report"
],
"operationId": "analytics.report.schedule.create",
"summary": "Create schedule for report",
"description": "Create scheduled export for report",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Payload for creating report schedule",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"schedule"
],
"properties": {
"schedule": {
"type": "object",
"additionalProperties": false,
"required": [
"crontab",
"exportType"
],
"properties": {
"crontab": {
"example": "0 0 * * *",
"type": "string",
"description": "Crontab expression for scheduling the report"
},
"exportType": {
"example": "email",
"type": "string",
"description": "Export type"
},
"format": {
"example": "csv",
"type": "string",
"description": "Export format"
}
}
}
}
},
"examples": {
"example": {
"summary": "Example of a report schedule",
"value": {
"schedule": {
"crontab": "0 0 * * *",
"exportType": "email",
"format": "csv"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Report schedule response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"reportId",
"uuid",
"crontab",
"exportType",
"createdAt",
"updatedAt"
],
"properties": {
"reportId": {
"example": 1,
"type": "number",
"description": "ID of the report"
},
"crontab": {
"example": "0 0 * * *",
"type": "string",
"description": "Crontab expression for scheduling the report"
},
"exportType": {
"example": "csv",
"type": "string",
"description": "Export type"
},
"uuid": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "UUID of the report schedule"
},
"lastExecution": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Last execution time"
},
"nextExecution": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Next execution time"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/report/{id}/schedule/{uuid}": {
"delete": {
"tags": [
"Report"
],
"operationId": "analytics.report.schedule.delete",
"summary": "Delete schedule for report",
"description": "Delete scheduled report export",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"in": "path",
"name": "uuid",
"required": true,
"description": "The resource's UUID identifier.",
"schema": {
"description": "UUID identifier of the resource.",
"type": "string",
"pattern": "^$|^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$",
"example": "a00fd11e-3a67-433b-83c0-4e815fd4a0e1"
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/collection": {
"get": {
"tags": [
"Collection"
],
"operationId": "analytics.collection.get",
"summary": "Get list of collections",
"description": "Returns a list of report collections (official Xentral collections and custom collections).",
"responses": {
"200": {
"description": "Collection response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"example": 1,
"type": "number",
"description": "Collection ID"
},
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
},
"reports": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Collection"
],
"operationId": "analytics.collection.create",
"summary": "Create collection",
"description": "Creates a new collection and returns the new record",
"requestBody": {
"description": "Create collection request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"collection"
],
"example": {
"collection": {
"name": "My collection",
"description": "This is a collection"
}
},
"properties": {
"collection": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"example": {
"name": "My collection",
"description": "This is a collection"
},
"properties": {
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
}
}
}
}
},
"examples": {
"example": {
"summary": "Example of creating a collection",
"value": {
"collection": {
"name": "My collection",
"description": "This is a collection"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Collection response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"example": 1,
"type": "number",
"description": "Collection ID"
},
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
},
"reports": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/analytics/collection/{id}": {
"get": {
"tags": [
"Collection"
],
"operationId": "analytics.collection.list",
"summary": "Get a collection",
"description": "Returns a single collections by ID.",
"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": "Collection response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"example": 1,
"type": "number",
"description": "Collection ID"
},
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
},
"reports": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"patch": {
"tags": [
"Collection"
],
"operationId": "analytics.collection.update",
"summary": "Update a collection",
"description": "Updates an existing collection specified by its ID and returns the new record",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Update collection request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"collection"
],
"example": {
"collection": {
"name": "My collection",
"description": "This is a collection"
}
},
"properties": {
"collection": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"example": {
"name": "My collection",
"description": "This is a collection"
},
"properties": {
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
}
}
}
}
},
"examples": {
"example": {
"summary": "Example of updating a collection",
"value": {
"collection": {
"name": "My collection",
"description": "This is a collection"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Collection response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"example": 1,
"type": "number",
"description": "Collection ID"
},
"name": {
"example": "My collection",
"type": "string",
"description": "Collection name"
},
"description": {
"example": "This is a collection",
"type": "string",
"description": "Collection description"
},
"reports": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"sqlString",
"collectionId"
],
"properties": {
"id": {
"type": "number",
"description": "Report ID",
"example": 1
},
"title": {
"type": "string",
"description": "Report title",
"example": "My report"
},
"description": {
"type": "string",
"description": "Report description",
"example": "This is my report"
},
"userId": {
"type": "number",
"description": "User ID of the report creator",
"example": 1
},
"sqlString": {
"type": "string",
"description": "SQL query string",
"example": "SELECT * FROM users"
},
"isFavorite": {
"type": "boolean",
"description": "Is report marked as favorite",
"example": true
},
"isReadOnly": {
"example": false,
"type": "boolean",
"description": "Is report read-only"
},
"collectionId": {
"example": 1,
"type": "number",
"description": "ID of the collection the report belongs to"
},
"lastEditedBy": {
"example": "John Doe",
"type": "string",
"description": "User who last edited the report"
},
"tags": {
"type": "array",
"example": [
"tag1",
"tag2"
],
"items": {
"type": "string",
"description": "Tag name"
}
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
},
"delete": {
"tags": [
"Collection"
],
"operationId": "analytics.collection.delete",
"summary": "Delete a collection.",
"description": "Deletes an existing collection specified by its ID and returns the deleted record",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/documentation": {
"get": {
"tags": [
"Documentation"
],
"operationId": "analytics.documentation.list",
"summary": "Get list of documentation",
"description": "Returns a list of table documentation for each queryable table in the report builder",
"responses": {
"200": {
"description": "Documentation response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"label",
"shortDescription",
"longDescription",
"owners",
"columns"
],
"properties": {
"label": {
"example": "users",
"type": "string",
"description": "Table name"
},
"shortDescription": {
"example": "Users table",
"type": "string",
"description": "Short description of the table"
},
"longDescription": {
"example": "This table contains information about users",
"type": "string",
"description": "Long description of the table"
},
"owners": {
"type": "array",
"items": {
"example": "john.doe@xentral.com",
"type": "string",
"description": "Owner name or email"
}
},
"columns": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"example": "id",
"type": "string",
"description": "Column name"
},
"description": {
"example": "Unique identifier",
"type": "string",
"description": "Column description"
},
"type": {
"example": "integer",
"type": "string",
"description": "Column type"
},
"source": {
"example": "users.id",
"type": "string",
"description": "Column source"
}
}
}
},
"sources": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Source name"
}
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/analytics/query": {
"post": {
"tags": [
"Query"
],
"operationId": "analytics.query",
"summary": "Execute a query synchronously",
"description": "Execute a query synchronously on the Analytics platform and get result table (Redshift dialect) with limited amount of records",
"requestBody": {
"description": "Query payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"query"
],
"example": {
"query": "SELECT * FROM users",
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
},
"properties": {
"query": {
"type": "string",
"description": "SQL query to execute",
"example": "SELECT * FROM users"
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
}
}
},
"examples": {
"example": {
"summary": "Example SQL query payload",
"value": {
"query": "SELECT * FROM users",
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
}
}
}
}
},
"parameters": [
{
"name": "preview",
"in": "query",
"style": "deepObject",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"preview": {
"type": "boolean",
"example": false,
"default": false,
"description": "If true, only a limited amount of records will be returned, but the request does not cost any credits. If true, all results are returned up to a max number of 500 rows."
}
}
}
}
],
"responses": {
"200": {
"description": "Query response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"meta"
],
"properties": {
"data": {
"description": "Generic result response for a query in a table-like structure.",
"type": "object",
"nullable": true,
"additionalProperties": false,
"required": [
"header",
"rows"
],
"properties": {
"header": {
"type": "array",
"items": {
"type": "string"
}
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"header": [
"id",
"name"
],
"rows": [
[
"1",
"Alice"
],
[
"2",
"Bob"
]
]
}
},
"meta": {
"description": "Query meta information.",
"type": "object",
"additionalProperties": false,
"nullable": true,
"example": {
"query": "SELECT * FROM users",
"executionTime": 0.123,
"totalResults": 2,
"columnTypes": [
"integer",
"string"
]
},
"properties": {
"columnTypes": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Derived column types for each column in the result table.",
"example": [
"integer",
"string"
]
},
"executionTime": {
"description": "Execution time of the query in seconds.",
"example": 0.123,
"type": "number",
"nullable": true
},
"query": {
"description": "SQL query that was executed.",
"type": "string",
"nullable": false,
"example": "SELECT * FROM users"
},
"totalResults": {
"description": "Total number of rows og the result (the returned result is always limited).",
"type": "number",
"nullable": true,
"example": 2
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"402": {
"description": "Resource can not be accessed because you exceeded the credit limit."
},
"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."
}
}
}
},
"/api/analytics/query/export": {
"post": {
"tags": [
"Query"
],
"operationId": "analytics.query.export.create",
"summary": "Create a query execution job on the Analytics platform",
"description": "Create a query execution job on the Analytics platform and get the respective query ID",
"requestBody": {
"description": "Query payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"query"
],
"example": {
"query": "SELECT * FROM users",
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
},
"properties": {
"query": {
"type": "string",
"description": "SQL query to execute",
"example": "SELECT * FROM users"
},
"parameters": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type",
"defaultValue"
],
"example": {
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
},
"properties": {
"name": {
"type": "string",
"description": "Parameter name",
"example": "date"
},
"type": {
"type": "string",
"description": "Parameter type",
"example": "string"
},
"defaultValue": {
"type": "string",
"description": "Default value for parameter you want to store",
"example": "2021-01-01"
}
}
}
}
}
},
"examples": {
"example": {
"summary": "Example SQL query payload",
"value": {
"query": "SELECT * FROM users",
"parameters": [
{
"name": "date",
"type": "string",
"defaultValue": "2021-01-01"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Query execution response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
},
"description": "Details of the query execution"
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"402": {
"description": "Resource can not be accessed because you exceeded the credit limit."
},
"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": [
"Query"
],
"operationId": "analytics.query.export.list",
"summary": "Get a list of recent queries",
"description": "Get a list of recent queries and their status",
"responses": {
"200": {
"description": "Query execution response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
},
"description": "Details of the query execution"
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/analytics/query/export/{uuid}": {
"get": {
"tags": [
"Query"
],
"operationId": "analytics.query.export.getById",
"summary": "Get specific query result status by ID",
"description": "Get specific query result status by ID which (if completed successfully) contains a download link to a file in CSV format",
"parameters": [
{
"in": "path",
"name": "uuid",
"required": true,
"description": "The resource's UUID identifier.",
"schema": {
"description": "UUID identifier of the resource.",
"type": "string",
"pattern": "^$|^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$",
"example": "a00fd11e-3a67-433b-83c0-4e815fd4a0e1"
}
}
],
"responses": {
"200": {
"description": "Query execution response",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"query",
"url",
"error",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"example": "123e4567-e89b-12d3-a456-426614174000",
"type": "string",
"format": "uuid",
"description": "Query execution ID"
},
"status": {
"example": "pending",
"type": "string",
"description": "Query execution status"
},
"query": {
"example": "SELECT * FROM users",
"type": "string",
"description": "SQL query"
},
"url": {
"example": "https://example.com",
"type": "string",
"description": "URL to download the result"
},
"error": {
"example": "SQL statement is invalid",
"type": "string",
"description": "Error message"
},
"createdAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Creation time"
},
"updatedAt": {
"example": "2023-01-01T00:00:00+00:00",
"type": "string",
"format": "date-time",
"description": "Last update time"
}
}
},
"description": "Details of the query execution"
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/analytics/credit": {
"get": {
"tags": [
"Credit"
],
"operationId": "analytics.credit.get",
"summary": "Get credit information",
"description": "Get credit information regarding Report module usage.",
"responses": {
"200": {
"description": "Shows the amount of used credits for this month as well as the total amount of credits available",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"example": {
"data": [
{
"totalCredits": 30,
"usedCredits": 5
}
]
},
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"usedCredits",
"totalCredits"
],
"properties": {
"totalCredits": {
"type": "number",
"example": 1,
"description": "Total amount of credits available"
},
"usedCredits": {
"type": "number",
"example": 1,
"description": "Amount of used credits for this month"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request due to malformed payload or SQL statement",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"description": "Error message",
"type": "string",
"example": "SQL statement is invalid"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/analytics/reportUsage": {
"get": {
"tags": [
"Report Usage"
],
"operationId": "analytics.reportUsage.get",
"summary": "Get report usage",
"description": "Get report usage which shows the history of chargeable requests made within the given timeframe",
"parameters": [
{
"in": "query",
"name": "filter",
"style": "deepObject",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "string",
"format": "date",
"description": "Start date of the usage records",
"example": "2024-01-01"
},
"end": {
"type": "string",
"format": "date",
"description": "End date of the usage records",
"example": "2024-01-31"
}
}
}
}
],
"responses": {
"200": {
"description": "Shows all records of chargeable requests made within the given timeframe",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"example": {
"data": [
{
"id": 1,
"endpoint": "report/123/export",
"timestamp": "2024-01-01T00:00:00+00:00",
"identifier": "My Report",
"query": "SELECT * FROM table"
}
]
},
"properties": {
"data": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"endpoint",
"timestamp",
"identifier",
"query"
],
"properties": {
"id": {
"type": "number",
"example": 1,
"description": "Unique identifier of the record"
},
"endpoint": {
"type": "string",
"example": "report/123/export",
"description": "Endpoint of the request"
},
"timestamp": {
"type": "string",
"example": "2024-01-01T00:00:00+00:00",
"format": "date-time",
"description": "Timestamp of the request"
},
"identifier": {
"type": "string",
"example": "My Report",
"description": "Identifier of the item, which is the report name or 'Custom Query' for queries"
},
"query": {
"type": "string",
"example": "SELECT * FROM table",
"description": "SQL query that was executed"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"415": {
"description": "Resource representation send in the request is not supported."
}
}
}
},
"/api/creditNotes": {
"post": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.create",
"summary": "Create credit note",
"description": "Creates a credit note",
"requestBody": {
"description": "[EARLY ACCESS] Create a credit note object",
"content": {
"application/vnd.xentral.minimal.v1-beta+json": {
"schema": {
"type": "object",
"required": [
"invoice"
],
"additionalProperties": false,
"properties": {
"invoice": {
"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": {
"type": "string",
"minLength": 1,
"maxLength": 35
}
}
},
"examples": {
"Create credit not from an invoice": {
"value": {
"invoice": {
"id": "1337"
}
}
},
"Create credit not from an invoice with a document number": {
"value": {
"invoice": {
"id": "1337"
},
"documentNumber": "415263"
}
}
}
},
"application/vnd.xentral.fromreturn.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"return": {
"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"
}
},
"isApproved": {
"type": "boolean",
"default": false
},
"isPaid": {
"type": "boolean",
"default": false
}
}
},
"examples": {
"return": {
"value": {
"return": {
"id": "1337"
},
"isApproved": true,
"isPaid": false
}
}
}
}
}
},
"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 7807 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",
"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": {
"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": [
"Credit Note"
],
"operationId": "creditNote.list",
"summary": "List credit notes",
"description": "Returns a collection with all credit notes.",
"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": [
"search",
"id",
"creditNote",
"date",
"status",
"customerName",
"customerNumber",
"country",
"projectId",
"projectName",
"projectAbbr",
"paymentMethod",
"paymentStatus",
"amount",
"currency"
]
},
"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",
"creditNote",
"date",
"customerName",
"customerNumber",
"country",
"project",
"paymentMethod",
"amount",
"currency",
"paymentStatus",
"status"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Operation completed successfully.",
"content": {
"application/vnd.xentral.minimal.v1+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": "2024-900000"
},
"date": {
"x-description-missing": true,
"type": "string",
"format": "date",
"example": "2024-05-29"
},
"status": {
"x-description-missing": true,
"type": "string",
"enum": [
"approved",
"sent",
"created",
"closed",
"canceled"
],
"example": "created"
},
"amount": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"nullable": false,
"required": [
"amount",
"currencyCode"
],
"properties": {
"amount": {
"type": "string"
},
"currencyCode": {
"type": "string"
}
},
"example": {
"amount": "142.78",
"currencyCode": "EUR"
}
},
"invoice": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"number"
],
"properties": {
"number": {
"type": "string"
}
},
"example": {
"number": "2022-400085"
}
},
"address": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id",
"name",
"customerNumber",
"country"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"customerNumber": {
"type": "string"
},
"country": {
"type": "string"
}
},
"example": {
"id": "18",
"name": "Richard E.",
"customerNumber": "10011",
"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": "5",
"name": "Amazon FBM",
"abbreviation": "FBM"
}
},
"payment": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"method",
"status"
],
"properties": {
"method": {
"type": "string"
},
"status": {
"type": "string"
}
},
"example": {
"method": "shopify_payments",
"status": "offen"
}
},
"paymentTransaction": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id",
"paymentStatus"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"paymentStatus": {
"type": "string"
}
},
"example": {
"id": "2",
"paymentStatus": "recorded"
}
},
"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": "2021-12-15T11:31:44+01:00"
},
"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."
}
}
}
}
}
}
},
"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
}
}
}
}
}
},
"application/vnd.xentral.default.v1+csv": {
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/creditNotes/{id}": {
"get": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.view",
"summary": "[ALPHA] View credit note",
"description": "Returns details of a single credit note.",
"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/vnd.xentral.default.v1-beta+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."
},
"number": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "9000000"
},
"date": {
"x-description-missing": true,
"type": "string",
"format": "date",
"example": "2021-11-08"
},
"createdAt": {
"x-description-missing": true,
"type": "string",
"format": "date-time",
"example": "2021-12-09T10:16:07+01:00"
},
"createdBy": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
}
},
"example": {
"name": "Administrator"
}
},
"sentAt": {
"x-description-missing": true,
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2021-12-09T10:19:18+01:00"
},
"sentBy": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
}
},
"example": {
"name": "Administrator"
}
},
"updatedAt": {
"x-description-missing": true,
"type": "string",
"format": "date-time",
"example": "2023-01-13T10:43:58+01:00"
},
"grossValue": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"netValue": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"costCenter": {
"x-description-missing": true,
"type": "string",
"example": "41000"
},
"status": {
"x-description-missing": true,
"type": "string",
"enum": [
"approved",
"sent",
"created",
"closed",
"canceled"
],
"example": "sent"
},
"project": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"example": {
"id": "2",
"name": "B2C"
}
},
"customer": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"example": {
"id": "1",
"name": "John Doe"
}
},
"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."
}
}
}
},
"externalOrderReference": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "1005"
},
"devCustomer": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "dev"
},
"billingAddress": {
"type": "object",
"description": "Billing address of the customer.",
"additionalProperties": false,
"required": [
"name",
"contactPerson",
"department",
"subdivision",
"street",
"additionalDetails",
"city",
"zipCode",
"country"
],
"nullable": true,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"contactPerson": {
"type": "string"
},
"department": {
"type": "string",
"nullable": true
},
"subdivision": {
"type": "string",
"nullable": true
},
"street": {
"type": "string"
},
"additionalDetails": {
"type": "string",
"nullable": true
},
"city": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "[A-Z]{2}"
},
"email": {
"type": "string",
"nullable": true
}
},
"example": {
"id": "1",
"name": "John Doe",
"contactPerson": "",
"department": "",
"subdivision": "",
"street": "Street 10",
"additionalDetails": "",
"city": "Berlin",
"zipCode": "10101",
"country": "DE"
}
},
"paymentMethodName": {
"x-description-missing": true,
"type": "string",
"example": "invoice"
},
"paymentStatus": {
"type": "string",
"description": "Status of the payment. Value `unknown` is displayed when a status from database cannot be identified. Value `unknown` cannot be used when creating or updating statuses (POST or PATCH endpoints)",
"enum": [
"pending",
"paid",
"partlyPaid",
"canceled",
"partialCancellation",
"badDebt",
"debited",
"unknown"
],
"example": "pending"
},
"gln": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "12345"
},
"taxation": {
"x-description-missing": true,
"type": "number",
"example": 0
},
"positions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "number"
},
"position": {
"type": "number"
},
"salesOrderPosition": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"productId": {
"type": "number"
},
"productNumber": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"price": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"vatCategory": {
"type": "string"
},
"taxRate": {
"type": "number",
"format": "float"
},
"discount": {
"type": "number",
"format": "float",
"nullable": true
}
}
}
}
},
"example": {
"id": "125",
"number": "9000110",
"date": "2022-02-03",
"createdAt": "2022-02-03T10:18:40+01:00",
"createdBy": {
"name": "John Doe"
},
"sentAt": "2022-02-03T10:19:31+01:00",
"sentBy": {
"name": "John Doe"
},
"updatedAt": "2022-02-03T10:19:34+01:00",
"grossValue": {
"amount": "50.00",
"currency": "EUR"
},
"netValue": {
"amount": "42.02",
"currency": "EUR"
},
"costCenter": "",
"status": "sent",
"tags": [],
"project": {
"id": "6",
"name": "Shopware"
},
"customer": {
"id": "3632",
"name": "John Doe"
},
"externalOrderReference": "62720",
"devCustomer": "",
"billingAddress": {
"id": "1",
"name": "John Doe",
"contactPerson": "",
"department": "",
"subdivision": "",
"street": "Street 10",
"additionalDetails": "",
"city": "Berlin",
"zipCode": "10101",
"country": "DE"
},
"paymentMethodName": "invoice",
"paymentStatus": "pending",
"gln": "12345",
"taxation": 0,
"positions": [
{
"id": 418,
"position": 1,
"salesOrderPosition": {
"id": "16216"
},
"createdAt": "2022-02-03T10:18:40+01:00",
"productId": 1689,
"productNumber": "FR5248977",
"description": "Article 1",
"quantity": 1,
"price": {
"amount": "47.05",
"currency": "EUR"
},
"vatCategory": "normal",
"taxRate": 0,
"discount": 0
}
]
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"delete": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.delete",
"summary": "[ALPHA] Delete single credit note",
"description": "Deletes a single credit note resource identified by its URI",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"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."
}
}
},
"patch": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.update",
"summary": "[EARLY ACCESS] Update single credit note",
"description": "[EARLY ACCESS] Update single credit note",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "[EARLY ACCESS] Update single credit note",
"content": {
"application/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"date",
"costCenter",
"project",
"customer",
"tags",
"externalOrderReference",
"devCustomer",
"billingAddress",
"paymentMethodName",
"gln",
"taxation"
],
"properties": {
"date": {
"type": "string",
"format": "date"
},
"costCenter": {
"type": "string"
},
"project": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"customer": {
"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"
}
},
"tags": {
"type": "array",
"items": {
"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"
}
}
},
"externalOrderReference": {
"type": "string",
"nullable": true
},
"devCustomer": {
"type": "string",
"nullable": true
},
"billingAddress": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"contactPerson",
"department",
"subdivision",
"street",
"additionalDetails",
"city",
"zipCode",
"country"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
},
"contactPerson": {
"type": "string"
},
"department": {
"type": "string",
"nullable": true
},
"subdivision": {
"type": "string",
"nullable": true
},
"street": {
"type": "string"
},
"additionalDetails": {
"type": "string",
"nullable": true
},
"city": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "[A-Z]{2}"
}
}
},
"paymentMethodName": {
"type": "string"
},
"gln": {
"type": "string",
"nullable": true
},
"taxation": {
"type": "string",
"pattern": "\\d+"
}
}
},
"examples": {
"update CreditNote": {
"value": {
"date": "2023-01-01",
"costCenter": "center",
"project": {
"id": "32"
},
"customer": {
"id": "64"
},
"tags": [
{
"id": "128"
}
],
"externalOrderReference": "ref",
"devCustomer": "dev",
"billingAddress": null,
"paymentMethodName": "method",
"gln": null,
"taxation": "7"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/creditNotes/{id}/balance": {
"get": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.balance",
"summary": "View Credit Note Balance",
"description": "Returns balance information (documents, payments) for a single credit note",
"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/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"documents": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"invoices": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
},
"creditNotes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"example": {
"invoices": [
{
"id": "1",
"amount": {
"amount": "13.37",
"currency": "EUR"
},
"date": "2023-08-13T14:45:36+02:00"
}
],
"creditNotes": [
{
"id": "1",
"amount": {
"amount": "13.37",
"currency": "EUR"
},
"date": "2023-08-13T14:45:36+02:00"
}
]
}
},
"payments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"reference": {
"type": "object",
"additionalProperties": false,
"description": "Only one of the actually referenced object.",
"properties": {
"invoice": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"creditNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"type": "string",
"enum": [
"incoming",
"outgoing"
],
"nullable": false
},
"statementId": {
"type": "string"
},
"accountName": {
"type": "string"
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
},
"example": {
"documents": {
"invoices": [
{
"id": "87",
"amount": {
"amount": "1483.63",
"currency": "EUR"
},
"date": "2024-03-08T00:00:00+01:00"
}
],
"creditNotes": [
{
"id": "2",
"amount": {
"amount": "24.99",
"currency": "EUR"
},
"date": "2024-06-17T00:00:00+02:00"
}
]
},
"payments": []
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"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/creditNotes/{id}/documents": {
"get": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.documents.view",
"summary": "[EARLY ACCESS] View related documents for credit note",
"description": "Returns details for related documents of a single credit note.",
"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/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"salesOrder": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"number": {
"type": "string"
},
"url": {
"type": "string"
},
"date": {
"type": "string",
"format": "date"
}
}
}
},
"deliveryNotes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"number": {
"type": "string"
},
"url": {
"type": "string"
},
"date": {
"type": "string",
"format": "date"
}
}
}
},
"invoices": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"number": {
"type": "string"
},
"url": {
"type": "string"
},
"date": {
"type": "string",
"format": "date"
}
}
}
},
"pdfArchives": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"url": {
"type": "string"
},
"date": {
"type": "string",
"format": "datetime"
},
"name": {
"type": "string"
},
"createdBy": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
},
"example": {
"salesOrder": [
{
"id": "1011",
"status": "completed",
"number": "200735",
"url": "https://example.xentral.biz?module=auftrag&action=pdf&id=1011",
"date": "2022-01-23"
}
],
"deliveryNotes": [
{
"id": "729",
"status": "sent",
"number": "300704",
"url": "https://example.xentral.biz?module=lieferschein&action=pdf&id=729",
"date": "2022-01-24"
}
],
"invoices": [
{
"id": "125",
"status": "canceled",
"number": "1200712",
"url": "https://example.xentral.biz?module=rechnung&action=pdf&id=125",
"date": "2022-01-24"
}
],
"pdfArchives": [
{
"id": "8571",
"name": "125_20220203_GS9000110.pdf",
"createdBy": {
"name": "John Doe"
},
"url": "https://example.xentral.biz?module=gutschrift&action=pdffromarchive&id=8571",
"date": "2022-02-03 10:19:27"
}
]
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/creditNotes/{id}/positions": {
"post": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.createPositions",
"summary": "[ALPHA] Create Positions for Credit note",
"description": "[ALPHA] Adds credit note positions",
"requestBody": {
"description": "[ALPHA] Create credit note positions object",
"content": {
"application/vnd.xentral.default.v1-alpha+json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"product",
"quantity",
"price",
"vatCategory",
"taxRate"
],
"properties": {
"salesOrderPosition": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"product": {
"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"
}
},
"quantity": {
"description": "The quantity for the position",
"type": "number",
"format": "double",
"example": 2
},
"price": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"vatCategory": {
"description": "The VAT category that applies to the position",
"type": "string",
"example": "reduced"
},
"taxRate": {
"description": "The VAT rate that applied to the position",
"type": "number",
"format": "float",
"example": 38.45
},
"discounts": {
"description": "Discounts applied to position",
"type": "object",
"additionalProperties": false,
"properties": {
"totalPercent": {
"description": "The percentage discount applied to position",
"type": "number",
"format": "float",
"nullable": true,
"example": 38.45
}
},
"example": {
"totalPercent": 38.45
}
}
}
}
},
"examples": {
"create CreditNote positions": {
"value": [
{
"product": {
"id": "16"
},
"quantity": 32.64,
"price": {
"currency": "EUR",
"amount": "16.8"
},
"vatCategory": "cat",
"taxRate": 16
}
]
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"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 7807 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",
"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": {
"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."
}
}
},
"patch": {
"tags": [
"Credit Note"
],
"operationId": "creditNote.updatePositions",
"summary": "[ALPHA] Update Positions for Credit Note",
"description": "[ALPHA] Updates credit note positions",
"requestBody": {
"description": "[ALPHA] Update credit note positions object",
"content": {
"application/vnd.xentral.default.v1-alpha+json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"product",
"quantity",
"price",
"vatCategory",
"taxRate"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"salesOrderPosition": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"product": {
"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"
}
},
"quantity": {
"x-description-missing": true,
"type": "number",
"format": "double",
"example": 1
},
"price": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"vatCategory": {
"x-description-missing": true,
"type": "string",
"example": "normal"
},
"taxRate": {
"x-description-missing": true,
"type": "number",
"format": "float",
"example": 19
},
"discounts": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"totalPercent": {
"x-description-missing": true,
"type": "number",
"format": "float",
"nullable": true,
"example": 15.5
}
},
"example": {
"totalPercent": 15.5
}
}
}
}
},
"examples": {
"update CreditNote positions": {
"value": [
{
"id": "1337",
"product": {
"id": "42"
},
"quantity": 12.24,
"price": {
"currency": "EUR",
"amount": "1024.0"
},
"vatCategory": "cat",
"taxRate": 16
}
]
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/creditNotes/{id}/positions/{positionId}": {
"delete": {
"operationId": "creditNote.deletePosition",
"summary": "[ALPHA] Delete Position from Credit Note",
"description": "[ALPHA] Delete single credit note position",
"tags": [
"Credit Note"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"name": "positionId",
"in": "path",
"description": "Credit note position ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"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."
}
}
}
},
"/api/creditNotesTags": {
"get": {
"tags": [
"Credit Note Tag"
],
"operationId": "creditNoteTag.list",
"summary": "List Credit Notes tags",
"description": "Returns a collection with all credit notes tags.",
"responses": {
"200": {
"description": "Operation completed successfully.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"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."
}
}
}
}
}
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/customers": {
"post": {
"tags": [
"Customer"
],
"operationId": "customer.create",
"summary": "Create customer",
"description": "Creates a new customer. If you provide a specific project then it must be existing otherwise you get 400 HTTP status.",
"requestBody": {
"description": "Create a customer object",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"general"
],
"properties": {
"type": {
"type": "string",
"enum": [
"company",
"person"
]
},
"general": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"title": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"birthday": {
"type": "string",
"format": "date"
},
"address": {
"type": "object",
"additionalProperties": false,
"required": [
"street",
"zip",
"city",
"state",
"country",
"note"
],
"properties": {
"street": {
"type": "string"
},
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
}
},
"contact": {
"type": "object",
"additionalProperties": false,
"properties": {
"phone": {
"type": "string",
"nullable": true
},
"fax": {
"type": "string",
"nullable": true
},
"mobile": {
"type": "string",
"nullable": true
},
"email": {
"type": "string"
},
"website": {
"type": "string",
"nullable": true
},
"marketingMails": {
"type": "boolean"
},
"trackingMails": {
"type": "boolean"
}
}
},
"bankAccount": {
"type": "object",
"additionalProperties": false,
"properties": {
"holder": {
"type": "string"
},
"iban": {
"type": "string"
},
"bic": {
"type": "string"
},
"sepa": {
"type": "boolean"
}
}
},
"project": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
}
},
"tags": {
"type": "array",
"items": {
"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"
}
}
}
}
},
"examples": {
"create customer": {
"value": {
"type": "company",
"general": {
"title": "Doktor",
"name": "Tom Schneider",
"birthday": "1980-04-30",
"address": {
"note": "Erster Stock",
"street": "Musterstrasse 20",
"zip": "12345",
"city": "Musterstadt",
"state": "Bayern",
"country": "Deutschland"
}
},
"contact": {
"email": "xentral@xentral.com",
"marketingMails": false,
"trackingMails": false
},
"bankAccount": {
"holder": "Tom",
"iban": "DE46500105171867232974",
"bic": "DE",
"sepa": false
},
"project": {
"id": "1"
},
"tags": [
{
"id": "1"
},
{
"id": "2"
}
]
}
}
}
}
}
},
"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 7807 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",
"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": {
"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": [
"Customer"
],
"operationId": "customer.list",
"summary": "List customer",
"description": "Lists an existing customer",
"parameters": [
{
"name": "filter",
"in": "query",
"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": [
"search",
"id",
"name",
"number",
"country",
"zip",
"city",
"project",
"projectName",
"phone",
"fax",
"mobile",
"email",
"addressNote",
"department",
"subdivision",
"vatNumber",
"taxNumber",
"gln",
"tag",
"tagName",
"street"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"in",
"notIn",
"exactlyIn",
"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",
"name",
"number",
"country",
"zip",
"city",
"project",
"projectName",
"telephone",
"fax",
"mobile",
"email",
"addressNote",
"department",
"subdivision",
"vatNumber",
"taxNumber",
"gln"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Customer list.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"general"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"x-description-missing": true,
"type": "string",
"example": "company"
},
"project": {
"description": "An optional object with id and name",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name"
],
"nullable": true,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"example": {
"id": "1337",
"name": "Diamond"
}
},
"general": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"name",
"address"
],
"properties": {
"number": {
"type": "string"
},
"fax": {
"type": "string",
"nullable": true
},
"mobile": {
"type": "string",
"nullable": true
},
"department": {
"type": "string"
},
"subdivision": {
"type": "string"
},
"vatNumber": {
"type": "string"
},
"taxNumber": {
"type": "string",
"nullable": true
},
"gln": {
"type": "string"
},
"employeeNumber": {
"type": "string"
},
"honorific": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"birthday": {
"type": "string",
"nullable": true,
"format": "date"
},
"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."
}
}
}
},
"customerNumber": {
"type": "string"
},
"phone": {
"type": "string",
"nullable": true
},
"email": {
"type": "string"
},
"address": {
"type": "object",
"additionalProperties": false,
"required": [
"street",
"zip",
"city",
"state",
"country",
"note"
],
"properties": {
"street": {
"type": "string"
},
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
},
"example": {
"number": "1201",
"fax": "123456",
"mobile": "123456",
"department": "IT",
"subdivision": "Development",
"vatNumber": "DE123456789",
"taxNumber": "123456",
"gln": "123456",
"employeeNumber": "123456",
"honorific": "Herr",
"title": "Dr.",
"name": "Tom Schneider",
"birthday": "1980-04-30",
"tags": [
{
"id": "1101",
"name": "Tag#1",
"color": "FF0000"
},
{
"id": "1102",
"name": "Tag#2",
"color": "0000FF"
}
],
"customerNumber": "123456",
"phone": "123456",
"email": "max@musterman.com",
"address": {
"note": "Erster Stock",
"street": "Musterstrasse 20",
"zip": "12345",
"city": "Musterstadt",
"state": "Bayern",
"country": "Deutschland"
}
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"description": "Either ID or name and key."
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string",
"pattern": "[a-fA-F0-9]{6}",
"example": "ff0000",
"description": "Hexadecimal color value in 6-digit format without the leading # character."
}
}
}
},
"freeFields": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"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
}
}
}
}
}
},
"application/vnd.xentral.default.v1+csv": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"patch": {
"tags": [
"Customer"
],
"operationId": "customer.updateMultiple",
"summary": "Update multiple customers tags",
"description": "Updates tags for multiple customers",
"requestBody": {
"description": "Customer update multiple request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tags": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"description": "Either ID or name and key.",
"example": "1101"
},
"key": {
"x-description-missing": true,
"type": "string",
"example": "Tag3"
},
"name": {
"x-description-missing": true,
"type": "string",
"example": "Tag#3"
},
"color": {
"type": "string",
"pattern": "[a-fA-F0-9]{6}",
"example": "ff0000",
"description": "Hexadecimal color value in 6-digit format without the leading # character."
}
}
}
}
}
}
},
"examples": {
"patch multiple customers": {
"value": [
{
"id": "1201",
"tags": [
{
"id": "1101"
},
{
"key": "Tag3",
"name": "Tag#3",
"color": "FF0000"
},
{
"key": "Tag4",
"name": "Tag#4",
"color": "0000FF"
}
]
},
{
"id": "1202",
"tags": [
{
"id": "1101"
},
{
"key": "Tag3",
"name": "Tag#3",
"color": "FF0000"
},
{
"key": "Tag4",
"name": "Tag#4",
"color": "0000FF"
}
]
}
]
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
}
}
}
},
"/api/v1/customers": {
"get": {
"tags": [
"Customer"
],
"operationId": "customer.list.v1",
"summary": "List customer",
"description": "Lists an existing customer",
"parameters": [
{
"name": "filter",
"in": "query",
"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": [
"search",
"id",
"name",
"number",
"country",
"zip",
"city",
"project",
"projectName",
"phone",
"fax",
"mobile",
"email",
"addressNote",
"department",
"subdivision",
"vatNumber",
"taxNumber",
"gln",
"tag",
"tagName",
"street"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"in",
"notIn",
"exactlyIn",
"allIn",
"allNotIn",
"contains",
"notContains",
"startsWith",
"endsWith",
"greaterThan",
"lessThan"
]
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
}
}
]
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"nextCursor": {
"type": "string",
"description": "nextCursor should be base64 encoded string returned from api"
},
"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",
"name",
"number",
"country",
"zip",
"city",
"project",
"projectName",
"telephone",
"fax",
"mobile",
"email",
"addressNote",
"department",
"subdivision",
"vatNumber",
"taxNumber",
"gln"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Customer list.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"general"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"x-description-missing": true,
"type": "string",
"example": "company"
},
"project": {
"description": "An optional object with id and name",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name"
],
"nullable": true,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"example": {
"id": "1337",
"name": "Diamond"
}
},
"general": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"name",
"address"
],
"properties": {
"number": {
"type": "string"
},
"fax": {
"type": "string",
"nullable": true
},
"mobile": {
"type": "string",
"nullable": true
},
"department": {
"type": "string"
},
"subdivision": {
"type": "string"
},
"vatNumber": {
"type": "string"
},
"taxNumber": {
"type": "string",
"nullable": true
},
"gln": {
"type": "string"
},
"employeeNumber": {
"type": "string"
},
"honorific": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"birthday": {
"type": "string",
"nullable": true,
"format": "date"
},
"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."
}
}
}
},
"customerNumber": {
"type": "string"
},
"phone": {
"type": "string",
"nullable": true
},
"email": {
"type": "string"
},
"address": {
"type": "object",
"additionalProperties": false,
"required": [
"street",
"zip",
"city",
"state",
"country",
"note"
],
"properties": {
"street": {
"type": "string"
},
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
},
"example": {
"number": "1201",
"fax": "123456",
"mobile": "123456",
"department": "IT",
"subdivision": "Development",
"vatNumber": "DE123456789",
"taxNumber": "123456",
"gln": "123456",
"employeeNumber": "123456",
"honorific": "Herr",
"title": "Dr.",
"name": "Tom Schneider",
"birthday": "1980-04-30",
"tags": [
{
"id": "1101",
"name": "Tag#1",
"color": "FF0000"
},
{
"id": "1102",
"name": "Tag#2",
"color": "0000FF"
}
],
"customerNumber": "123456",
"phone": "123456",
"email": "max@musterman.com",
"address": {
"note": "Erster Stock",
"street": "Musterstrasse 20",
"zip": "12345",
"city": "Musterstadt",
"state": "Bayern",
"country": "Deutschland"
}
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"description": "Either ID or name and key."
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string",
"pattern": "[a-fA-F0-9]{6}",
"example": "ff0000",
"description": "Hexadecimal color value in 6-digit format without the leading # character."
}
}
}
},
"freeFields": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"extra": {
"type": "object",
"required": [
"totalCount",
"cursor"
],
"additionalProperties": false,
"x-description-ignore": true,
"properties": {
"totalCount": {
"description": "the total count of all items",
"type": "integer",
"example": 1
},
"cursor": {
"description": "The pagination object containing the current page number and size",
"type": "object",
"required": [
"nextCursor",
"size"
],
"additionalProperties": false,
"properties": {
"nextCursor": {
"description": "Cursoer to use for next page request",
"type": "string",
"example": "NDI="
},
"size": {
"description": "The size of the pages",
"type": "integer",
"example": 10
}
},
"example": {
"nextCursor": "MTA=",
"size": 10
}
}
},
"example": {
"totalCount": 100,
"cursor": {
"nextCursor": "MTA=",
"size": 10
}
}
}
}
}
},
"application/vnd.xentral.default.v1+csv": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/customers/{id}": {
"get": {
"tags": [
"Customer"
],
"operationId": "customer.view",
"summary": "View customer",
"description": "Shows an existing customer details",
"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": "Customer view.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"general"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"x-description-missing": true,
"type": "string",
"example": "company"
},
"number": {
"x-description-missing": true,
"type": "string",
"example": "1201"
},
"general": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"name",
"address"
],
"properties": {
"honorific": {
"type": "string"
},
"title": {
"type": "string"
},
"name": {
"type": "string"
},
"birthday": {
"type": "string",
"format": "date"
},
"address": {
"type": "object",
"additionalProperties": false,
"required": [
"street",
"zip",
"city",
"state",
"country",
"note"
],
"properties": {
"street": {
"type": "string"
},
"zip": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
},
"example": {
"honorific": "Herr",
"title": "Dr.",
"name": "Tom Schneider",
"birthday": "1980-04-30",
"address": {
"note": "Erster Stock",
"street": "Musterstrasse 20",
"zip": "12345",
"city": "Musterstadt",
"state": "Bayern",
"country": "Deutschland"
}
}
},
"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."
}
}
}
}
},
"example": {
"id": "1201",
"type": "company",
"number": "1201",
"general": {
"honorific": "Herr",
"title": "Dr.",
"name": "Tom Schneider",
"birthday": "1980-04-30",
"address": {
"note": "Erster Stock",
"street": "Musterstrasse 20",
"zip": "12345",
"city": "Musterstadt",
"state": "Bayern",
"country": "Deutschland"
}
},
"tags": [
{
"id": "1101",
"name": "Tag#1",
"color": "FF0000"
},
{
"id": "1102",
"name": "Tag#2",
"color": "0000FF"
}
]
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"patch": {
"tags": [
"Customer"
],
"operationId": "customer.update",
"summary": "Update single customer tags",
"description": "Updates tags of a single customer",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Customer update request payload",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"description": "Either ID or name and key."
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string",
"pattern": "[a-fA-F0-9]{6}",
"example": "ff0000",
"description": "Hexadecimal color value in 6-digit format without the leading # character."
}
}
}
}
}
},
"examples": {
"update customer": {
"value": {
"tags": [
{
"id": "1101"
},
{
"key": "Tag3",
"name": "Tag#3",
"color": "FF0000"
},
{
"key": "Tag4",
"name": "Tag#4",
"color": "0000FF"
}
]
}
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"404": {
"description": "Resource was not found or not enough access privileges"
}
}
},
"delete": {
"tags": [
"Customer"
],
"operationId": "customer.delete",
"summary": "Delete customer",
"description": "Delete existing customer",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/customers/{id}/contactPerson": {
"get": {
"tags": [
"Customer - Contact Person"
],
"operationId": "customer.contactPerson.getList",
"summary": "Provides a list of contact persons belongs to a customer",
"description": "Provides a list of contact persons belongs to a customer related to given filters",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"name": "filter",
"in": "query",
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"type",
"name",
"title",
"birthday",
"birthdayShowInCalendar",
"sendBirthdayCard",
"marketingBan",
"department",
"subDepartment",
"position",
"street",
"additionalStreet",
"zip",
"city",
"state",
"country",
"phone",
"fax",
"mobile",
"salutation",
"email",
"group"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"contains",
"notContains",
"startsWith",
"endsWith",
"lessThan",
"greaterThan",
"in",
"notIn"
]
},
"value": {
"oneOf": [
{
"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",
"name",
"customerId",
"type",
"title",
"birthday",
"birthdayShowInCalendar",
"sendBirthdayCard",
"marketingBan",
"department",
"subDepartment",
"position",
"street",
"additionalStreet",
"zip",
"city",
"state",
"country",
"phone",
"fax",
"mobile",
"salutation",
"email",
"others",
"comment"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "List of contact persons",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type"
],
"description": "Contact person object",
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"customer": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"description": "The customer this contact person belongs to",
"example": {
"id": "1234"
},
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
},
"type": {
"type": "string",
"enum": [
"company",
"mr",
"mrs",
"other"
],
"nullable": true,
"example": "mr",
"description": "Type of contact used later for salutations"
},
"name": {
"type": "string",
"nullable": false,
"example": "Firstname Surname",
"description": "Full name of the contact person"
},
"title": {
"type": "string",
"nullable": true,
"example": "Prof. Dr.",
"description": "Additional information used for salutations"
},
"birthday": {
"description": "Birthday of contact person in default format like 'YYYY-MM-DD",
"type": "string",
"format": "date",
"nullable": true,
"example": "2001-01-14"
},
"birthdayShowInCalendar": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to show in birthday calendar"
},
"sendBirthdayCard": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send birthday card via serial letter module"
},
"marketingBan": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send serial letters to this contact"
},
"department": {
"type": "string",
"nullable": true,
"example": "HR department",
"description": "Department of contact if necessary and available"
},
"subDepartment": {
"type": "string",
"nullable": true,
"example": "Sub department",
"description": "Sub-Department of contact if necessary and available"
},
"position": {
"type": "string",
"nullable": true,
"example": "head of purchasing",
"description": "Position or responsibility"
},
"address": {
"type": "object",
"additionalProperties": false,
"description": "Address information of the contact person",
"example": {
"street": "Example st. 13",
"additionalStreet": "6th floor",
"zip": "12345",
"city": "city",
"state": "Bayern",
"country": "Deutschland"
},
"properties": {
"street": {
"type": "string",
"nullable": true,
"example": "2176 example street",
"description": "Street + number of contact address"
},
"additionalStreet": {
"type": "string",
"nullable": true,
"example": "6th floor",
"description": "Address suffix"
},
"zip": {
"type": "string",
"nullable": true,
"example": "12345",
"description": "ZIP code of contact address"
},
"city": {
"type": "string",
"nullable": true,
"example": "city",
"description": "City of contact address"
},
"state": {
"type": "string",
"nullable": true,
"example": "Ohio",
"description": "Federal state / district of contact address"
},
"country": {
"type": "string",
"nullable": true,
"example": "DE",
"description": "ISO 3166-1 (Alpha 2) Code of contact address country"
}
}
},
"contact": {
"type": "object",
"additionalProperties": false,
"description": "Contact information of the contact person",
"example": {
"phone": "+49 555 12345667",
"fax": "+49 555 7654321",
"mobile": "+49 555 7654321",
"salutation": "Dear Dr. Smith, Friend and Supporter",
"email": "email@test.com"
},
"properties": {
"phone": {
"type": "string",
"nullable": true,
"example": "+49 330 12345667",
"description": "Phone number of contact address"
},
"fax": {
"type": "string",
"nullable": true,
"example": "+49 330 7654321",
"description": "Fax number of contact address"
},
"mobile": {
"type": "string",
"nullable": true,
"example": "+49 172 7654321",
"description": "Mobile number of contact address"
},
"salutation": {
"type": "string",
"nullable": true,
"example": "Dear Dr. Smith, Friend and Supporter",
"description": "Specifies dedicated salutation"
},
"email": {
"type": "string",
"format": "email",
"nullable": true,
"example": "contact-person@address-location.tld",
"description": "E-mail address"
}
}
},
"groups": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"description": "List of groups this contact person is belong to",
"example": [
"17",
"22"
]
},
"comment": {
"type": "string",
"nullable": true,
"example": "This is a internal comment",
"description": "Internal comment for this contact"
},
"others": {
"type": "string",
"nullable": true,
"example": "",
"description": "Every other information you deem relevant"
}
},
"example": {
"id": "12345",
"type": "mrs",
"name": "Kathleen Minority",
"title": "Prof. Dr. Dr.",
"birthday": "2001-02-02",
"birthdayShowInCalendar": false,
"sendBirthdayCard": true,
"marketingBan": false,
"department": "Finance",
"subDepartment": "Controlling",
"position": "Head of Controlling",
"address": {
"street": "11W 53rd St",
"additionalStreet": "6. Floor",
"zip": "10019",
"city": "New York",
"state": "NY",
"country": "US"
},
"contact": {
"phone": "+1 917 55512345",
"fax": "+1 917 55512345-1",
"mobile": "+1 800 55554321",
"salutation": "Dear Mrs. Minority, my most value customer",
"email": "k.m@ny.tld"
},
"groups": [
"1",
"23",
"34"
],
"comment": "This is a internal comment for employees eyes only",
"others": "some other things necessary to write down blong to this contact ..."
}
}
},
"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
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"post": {
"tags": [
"Customer - Contact Person"
],
"operationId": "customer.contactPerson.create",
"summary": "Create contact person related to specific customer",
"description": "Creates new contact person for given customer.",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "Create customer contact person object",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"company",
"mr",
"mrs",
"other"
],
"nullable": true,
"example": "mr",
"description": "Type of contact used later for salutations"
},
"name": {
"type": "string",
"nullable": false,
"example": "Firstname Surname",
"description": "Full name of the contact person"
},
"title": {
"type": "string",
"nullable": true,
"example": "Prof. Dr.",
"description": "Additional information used for salutations"
},
"birthday": {
"type": "string",
"format": "date",
"nullable": true,
"example": "2001-01-14"
},
"birthdayShowInCalendar": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to show in birthday calendar"
},
"sendBirthdayCard": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send birthday card via serial letter module"
},
"marketingBan": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send serial letters to this contact"
},
"department": {
"type": "string",
"nullable": true,
"example": "HR department",
"description": "Department of contact if necessary and available"
},
"subDepartment": {
"type": "string",
"nullable": true,
"example": "Sub department",
"description": "Sub-Department of contact if necessary and available"
},
"position": {
"type": "string",
"nullable": true,
"example": "",
"description": "Position or responsibility"
},
"address": {
"type": "object",
"additionalProperties": false,
"properties": {
"street": {
"type": "string",
"nullable": true,
"example": "2176 example street",
"description": "Street + number of contact address"
},
"additionalStreet": {
"type": "string",
"nullable": true,
"example": "6th floor",
"description": "Address suffix"
},
"zip": {
"type": "string",
"nullable": true,
"example": "12345",
"description": "ZIP code of contact address"
},
"city": {
"type": "string",
"nullable": true,
"example": "city",
"description": "City of contact address"
},
"state": {
"type": "string",
"nullable": true,
"example": "Ohio",
"description": "Federal state / district of contact address"
},
"country": {
"type": "string",
"nullable": true,
"example": "DE",
"description": "ISO 3166-1 (Alpha 2) Code of contact address country"
}
}
},
"contact": {
"type": "object",
"additionalProperties": false,
"properties": {
"phone": {
"type": "string",
"nullable": true,
"example": "+49 330 12345667",
"description": "Phone number of contact address"
},
"fax": {
"type": "string",
"nullable": true,
"example": "+49 330 7654321",
"description": "Fax number of contact address"
},
"mobile": {
"type": "string",
"nullable": true,
"example": "+49 172 7654321",
"description": "Mobile number of contact address"
},
"salutation": {
"type": "string",
"nullable": true,
"example": "Dear Dr. Smith, Friend and Supporter",
"description": "Specifies dedicated salutation"
},
"email": {
"type": "string",
"format": "email",
"nullable": true,
"example": "contact-person@address-location.tld",
"description": "E-mail address"
}
}
},
"groups": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"description": "List of groups this contact person is belong to",
"example": [
"17",
"22"
]
},
"comment": {
"type": "string",
"nullable": true,
"example": "This is a internal comment",
"description": "Internal comment for this contact"
},
"others": {
"type": "string",
"nullable": true,
"example": "",
"description": "Every other information you deem relevant"
}
}
},
"examples": {
"minimal": {
"value": {
"name": "Fullname of contact person"
}
},
"fullQualified": {
"value": {
"type": "mrs",
"name": "Kathleen Minority",
"title": "Prof. Dr. Dr.",
"birthday": "2001-02-02",
"birthdayShowInCalendar": false,
"sendBirthdayCard": true,
"marketingBan": false,
"department": "Finance",
"subDepartment": "Controlling",
"position": "Head of Controlling",
"address": {
"street": "11W 53rd St",
"additionalStreet": "6. Floor",
"zip": "10019",
"city": "New York",
"state": "NY",
"country": "US"
},
"contact": {
"phone": "+1 917 55512345",
"fax": "+1 917 55512345-1",
"mobile": "+1 800 55554321",
"salutation": "Dear Mrs. Minority, my most value customer",
"email": "k.m@ny.tld"
},
"groups": [
"1",
"23",
"34"
],
"comment": "This is a internal comment for employees eyes only",
"others": "some other things necessary to write down blong to this contact ..."
}
}
}
}
}
},
"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 7807 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",
"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": {
"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."
}
}
}
},
"/api/customers/{customerId}/contactPerson/{contactPersonId}": {
"patch": {
"tags": [
"Customer - Contact Person"
],
"operationId": "customer.contactPerson.update",
"summary": "Update contact person related to specific customer",
"description": "Updates new contact person for given customer.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"description": "The customer's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"name": "contactPersonId",
"in": "path",
"description": "Contact Person ID",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"description": "Update customer contact person object",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"company",
"mr",
"mrs",
"other"
],
"nullable": false,
"example": "mr",
"description": "Type of contact used later for salutations"
},
"name": {
"type": "string",
"minLength": 1,
"nullable": false,
"example": "Firstname Surname",
"description": "Full name of the contact person"
},
"title": {
"type": "string",
"nullable": true,
"example": "Prof. Dr.",
"description": "Additional information used for salutations"
},
"birthday": {
"type": "string",
"format": "date",
"nullable": true,
"example": "2001-01-14"
},
"birthdayShowInCalendar": {
"type": "boolean",
"nullable": false,
"example": true,
"description": "Decides wether or not to show in birthday calendar"
},
"sendBirthdayCard": {
"type": "boolean",
"nullable": false,
"example": true,
"description": "Decides wether or not to send birthday card via serial letter module"
},
"marketingBan": {
"type": "boolean",
"nullable": false,
"example": true,
"description": "Decides wether or not to send serial letters to this contact"
},
"department": {
"type": "string",
"nullable": true,
"example": "HR department",
"description": "Department of contact if necessary and available"
},
"subDepartment": {
"type": "string",
"nullable": true,
"example": "Sub department",
"description": "Sub-Department of contact if necessary and available"
},
"position": {
"type": "string",
"nullable": true,
"example": "",
"description": "Position or responsibility"
},
"address": {
"type": "object",
"additionalProperties": false,
"properties": {
"street": {
"type": "string",
"nullable": true,
"example": "2176 example street",
"description": "Street + number of contact address"
},
"additionalStreet": {
"type": "string",
"nullable": true,
"example": "6th floor",
"description": "Address suffix"
},
"zip": {
"type": "string",
"nullable": true,
"example": "12345",
"description": "ZIP code of contact address"
},
"city": {
"type": "string",
"nullable": true,
"example": "city",
"description": "City of contact address"
},
"state": {
"type": "string",
"nullable": true,
"example": "Ohio",
"description": "Federal state / district of contact address"
},
"country": {
"type": "string",
"nullable": true,
"example": "DE",
"description": "ISO 3166-1 (Alpha 2) Code of contact address country"
}
}
},
"contact": {
"type": "object",
"additionalProperties": false,
"properties": {
"phone": {
"type": "string",
"nullable": true,
"example": "+49 330 12345667",
"description": "Phone number of contact address"
},
"fax": {
"type": "string",
"nullable": true,
"example": "+49 330 7654321",
"description": "Fax number of contact address"
},
"mobile": {
"type": "string",
"nullable": true,
"example": "+49 172 7654321",
"description": "Mobile number of contact address"
},
"salutation": {
"type": "string",
"nullable": true,
"example": "Dear Dr. Smith, Friend and Supporter",
"description": "Specifies dedicated salutation"
},
"email": {
"type": "string",
"format": "email",
"nullable": true,
"example": "contact-person@address-location.tld",
"description": "E-mail address"
}
}
},
"groups": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"description": "List of groups this contact person is belong to",
"example": [
"17",
"22"
]
},
"comment": {
"type": "string",
"nullable": true,
"example": "This is a internal comment",
"description": "Internal comment for this contact"
},
"others": {
"type": "string",
"nullable": true,
"example": "",
"description": "Every other information you deem relevant"
}
}
},
"examples": {
"full": {
"value": {
"type": "mrs",
"name": "Kathleen Minority",
"title": "Prof. Dr. Dr.",
"birthday": "2001-02-02",
"birthdayShowInCalendar": false,
"sendBirthdayCard": true,
"marketingBan": false,
"department": "Finance",
"subDepartment": "Controlling",
"position": "Head of Controlling",
"address": {
"street": "11W 53rd St",
"additionalStreet": "6. Floor",
"zip": "10019",
"city": "New York",
"state": "NY",
"country": "US"
},
"contact": {
"phone": "+1 917 55512345",
"fax": "+1 917 55512345-1",
"mobile": "+1 800 55554321",
"salutation": "Dear Mrs. Minority, my most value customer",
"email": "k.m@ny.tld"
},
"groups": [
"1",
"23",
"34"
],
"comment": "This is a internal comment for employees eyes only",
"others": "some other things necessary to write down blong to this contact ..."
}
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"delete": {
"tags": [
"Customer - Contact Person"
],
"operationId": "customer.contactPerson.delete",
"summary": "Delete contact person related to specific customer",
"description": "Deletes a contact person for given customer.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"description": "The unique identifier of the customer",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"in": "path",
"name": "contactPersonId",
"required": true,
"description": "The unique identifier of the contact person",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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"
}
}
},
"get": {
"tags": [
"Customer - Contact Person"
],
"operationId": "customer.contactPerson.get",
"summary": "Get customer contact person by ID",
"description": "Gets a single contact person of given customer by ID.",
"parameters": [
{
"in": "path",
"name": "customerId",
"required": true,
"description": "The customer's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
{
"in": "path",
"name": "contactPersonId",
"required": true,
"description": "The contact person's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"200": {
"description": "Contact person object",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"type"
],
"description": "Contact person object",
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"customer": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"description": "The customer this contact person belongs to",
"example": {
"id": "1234"
},
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
},
"type": {
"type": "string",
"enum": [
"company",
"mr",
"mrs",
"other"
],
"nullable": true,
"example": "mr",
"description": "Type of contact used later for salutations"
},
"name": {
"type": "string",
"nullable": false,
"example": "Firstname Surname",
"description": "Full name of the contact person"
},
"title": {
"type": "string",
"nullable": true,
"example": "Prof. Dr.",
"description": "Additional information used for salutations"
},
"birthday": {
"description": "Birthday of contact person in default format like 'YYYY-MM-DD",
"type": "string",
"format": "date",
"nullable": true,
"example": "2001-01-14"
},
"birthdayShowInCalendar": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to show in birthday calendar"
},
"sendBirthdayCard": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send birthday card via serial letter module"
},
"marketingBan": {
"type": "boolean",
"nullable": true,
"example": true,
"description": "Decides wether or not to send serial letters to this contact"
},
"department": {
"type": "string",
"nullable": true,
"example": "HR department",
"description": "Department of contact if necessary and available"
},
"subDepartment": {
"type": "string",
"nullable": true,
"example": "Sub department",
"description": "Sub-Department of contact if necessary and available"
},
"position": {
"type": "string",
"nullable": true,
"example": "head of purchasing",
"description": "Position or responsibility"
},
"address": {
"type": "object",
"additionalProperties": false,
"description": "Address information of the contact person",
"example": {
"street": "Example st. 13",
"additionalStreet": "6th floor",
"zip": "12345",
"city": "city",
"state": "Bayern",
"country": "Deutschland"
},
"properties": {
"street": {
"type": "string",
"nullable": true,
"example": "2176 example street",
"description": "Street + number of contact address"
},
"additionalStreet": {
"type": "string",
"nullable": true,
"example": "6th floor",
"description": "Address suffix"
},
"zip": {
"type": "string",
"nullable": true,
"example": "12345",
"description": "ZIP code of contact address"
},
"city": {
"type": "string",
"nullable": true,
"example": "city",
"description": "City of contact address"
},
"state": {
"type": "string",
"nullable": true,
"example": "Ohio",
"description": "Federal state / district of contact address"
},
"country": {
"type": "string",
"nullable": true,
"example": "DE",
"description": "ISO 3166-1 (Alpha 2) Code of contact address country"
}
}
},
"contact": {
"type": "object",
"additionalProperties": false,
"description": "Contact information of the contact person",
"example": {
"phone": "+49 555 12345667",
"fax": "+49 555 7654321",
"mobile": "+49 555 7654321",
"salutation": "Dear Dr. Smith, Friend and Supporter",
"email": "email@test.com"
},
"properties": {
"phone": {
"type": "string",
"nullable": true,
"example": "+49 330 12345667",
"description": "Phone number of contact address"
},
"fax": {
"type": "string",
"nullable": true,
"example": "+49 330 7654321",
"description": "Fax number of contact address"
},
"mobile": {
"type": "string",
"nullable": true,
"example": "+49 172 7654321",
"description": "Mobile number of contact address"
},
"salutation": {
"type": "string",
"nullable": true,
"example": "Dear Dr. Smith, Friend and Supporter",
"description": "Specifies dedicated salutation"
},
"email": {
"type": "string",
"format": "email",
"nullable": true,
"example": "contact-person@address-location.tld",
"description": "E-mail address"
}
}
},
"groups": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"description": "List of groups this contact person is belong to",
"example": [
"17",
"22"
]
},
"comment": {
"type": "string",
"nullable": true,
"example": "This is a internal comment",
"description": "Internal comment for this contact"
},
"others": {
"type": "string",
"nullable": true,
"example": "",
"description": "Every other information you deem relevant"
}
},
"example": {
"id": "12345",
"type": "mrs",
"name": "Kathleen Minority",
"title": "Prof. Dr. Dr.",
"birthday": "2001-02-02",
"birthdayShowInCalendar": false,
"sendBirthdayCard": true,
"marketingBan": false,
"department": "Finance",
"subDepartment": "Controlling",
"position": "Head of Controlling",
"address": {
"street": "11W 53rd St",
"additionalStreet": "6. Floor",
"zip": "10019",
"city": "New York",
"state": "NY",
"country": "US"
},
"contact": {
"phone": "+1 917 55512345",
"fax": "+1 917 55512345-1",
"mobile": "+1 800 55554321",
"salutation": "Dear Mrs. Minority, my most value customer",
"email": "k.m@ny.tld"
},
"groups": [
"1",
"23",
"34"
],
"comment": "This is a internal comment for employees eyes only",
"others": "some other things necessary to write down blong to this contact ..."
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
}
},
"/api/customersTags": {
"get": {
"tags": [
"Customer Tag"
],
"operationId": "customerTag.list",
"summary": "List customers tags",
"description": "Returns a collection with all customers tags.",
"responses": {
"200": {
"description": "Operation completed successfully.",
"content": {
"application/vnd.xentral.default.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"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."
}
}
}
},
"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
}
}
}
}
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/v1/deliveries": {
"get": {
"tags": [
"Delivery"
],
"operationId": "deliveries.list",
"summary": "List deliveries",
"description": "Lists existing deliveries",
"parameters": [
{
"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": [
"salesOrderId"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
},
{
"name": "filter",
"in": "query",
"style": "deepObject",
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"salesOrderId"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"in"
]
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"description": "Used for the operations 'in'.",
"title": "Array",
"items": {
"type": "string"
}
}
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Delivery list",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder",
"shippingMethod"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
},
"link": {
"type": "string",
"description": "Carrier tracking link"
},
"carrier": {
"type": "string",
"description": "Carrier that shipping the delivery"
}
},
"description": "Tracking information for the delivery",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"shippingMethod": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"label": {
"type": "object",
"nullable": true,
"required": [
"fileType",
"fileContent"
],
"additionalProperties": false,
"properties": {
"fileType": {
"type": "string",
"description": "Label's file type",
"example": "image/gif"
},
"fileContent": {
"type": "string",
"description": "Base 64 encoded label",
"example": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Shipping label for the delivery",
"example": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
},
"example": {
"id": "DEL-12345",
"tracking": {
"number": "101010101010101",
"link": "https://carrier.example.com/track/101010101010101",
"carrier": "DHL"
},
"deliveryNote": {
"id": "DN-54321"
},
"salesOrder": {
"id": "SO-98765"
},
"shippingMethod": {
"id": "SM-12345"
},
"label": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Data representation of a single delivery aka shipment"
}
},
"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": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/v1/deliveries/{id}": {
"get": {
"tags": [
"Delivery"
],
"operationId": "delivery.view",
"summary": "[EARLY ACCESS] View delivery aka shipment",
"description": "Returns details of a delivery aka shipment",
"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,
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder",
"shippingMethod"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
},
"link": {
"type": "string",
"description": "Carrier tracking link"
},
"carrier": {
"type": "string",
"description": "Carrier that shipping the delivery"
}
},
"description": "Tracking information for the delivery",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"shippingMethod": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"label": {
"type": "object",
"nullable": true,
"required": [
"fileType",
"fileContent"
],
"additionalProperties": false,
"properties": {
"fileType": {
"type": "string",
"description": "Label's file type",
"example": "image/gif"
},
"fileContent": {
"type": "string",
"description": "Base 64 encoded label",
"example": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Shipping label for the delivery",
"example": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
},
"example": {
"id": "DEL-12345",
"tracking": {
"number": "101010101010101",
"link": "https://carrier.example.com/track/101010101010101",
"carrier": "DHL"
},
"deliveryNote": {
"id": "DN-54321"
},
"salesOrder": {
"id": "SO-98765"
},
"shippingMethod": {
"id": "SM-12345"
},
"label": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Data representation of a single delivery aka shipment"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/shipments/{id}": {
"get": {
"tags": [
"Delivery"
],
"operationId": "shipment.view",
"summary": "[EARLY ACCESS] View shipment aka delivery",
"description": "Returns details of a shipment aka delivery",
"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,
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder",
"shippingMethod"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
},
"link": {
"type": "string",
"description": "Carrier tracking link"
},
"carrier": {
"type": "string",
"description": "Carrier that shipping the delivery"
}
},
"description": "Tracking information for the delivery",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"shippingMethod": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"label": {
"type": "object",
"nullable": true,
"required": [
"fileType",
"fileContent"
],
"additionalProperties": false,
"properties": {
"fileType": {
"type": "string",
"description": "Label's file type",
"example": "image/gif"
},
"fileContent": {
"type": "string",
"description": "Base 64 encoded label",
"example": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Shipping label for the delivery",
"example": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
},
"example": {
"id": "DEL-12345",
"tracking": {
"number": "101010101010101",
"link": "https://carrier.example.com/track/101010101010101",
"carrier": "DHL"
},
"deliveryNote": {
"id": "DN-54321"
},
"salesOrder": {
"id": "SO-98765"
},
"shippingMethod": {
"id": "SM-12345"
},
"label": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Data representation of a single delivery aka shipment"
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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."
}
}
}
},
"/api/v1/provisionalReturns": {
"get": {
"tags": [
"Provisional Return"
],
"operationId": "provisionalReturns.list",
"summary": "List provisional returns",
"description": "Lists existing provisional returns",
"parameters": [
{
"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": [
"deliveryNoteId"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
},
{
"name": "filter",
"in": "query",
"style": "deepObject",
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"salesOrder"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"in"
]
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"description": "Used for the operations 'in'.",
"title": "Array",
"items": {
"type": "string"
}
}
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Provisional Return list",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
}
},
"description": "Tracking information for the provisional return",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
}
}
}
},
"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": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/v1/deliveryNotes": {
"get": {
"tags": [
"Delivery Note"
],
"operationId": "deliveryNote.list",
"summary": "[EARLY ACCESS] Delivery note list",
"description": "This endpoint is only available as beta version and will introduce breaking changes without further notice or versioning. Returns all delivery notes.",
"parameters": [
{
"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, deliveryNoteNumber"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
},
{
"name": "filter",
"in": "query",
"style": "deepObject",
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"documentDate",
"createdAt",
"status",
"salesOrderId",
"updatedAt",
"country",
"projectId"
]
},
"op": {
"type": "string",
"enum": [
"greaterThan",
"lessThan",
"equals",
"notEquals",
"in",
"notIn",
"contains",
"notContains",
"startsWith",
"endsWith"
]
},
"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"
}
}
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Operation completed successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"number": {
"type": "string",
"description": "Number of the document",
"example": "200001"
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "Creation date of the delivery note",
"example": "2024-01-01 00:00:00"
},
"updatedAt": {
"type": "string",
"format": "datetime",
"description": "Last update date of the delivery note",
"example": "2024-01-01 00:00:00"
},
"documentDate": {
"type": "string",
"format": "date",
"description": "Date of the document",
"example": "2024-01-01"
},
"receiver": {
"type": "object",
"nullable": true,
"required": [
"number",
"name"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string",
"nullable": true
},
"number": {
"type": "string",
"nullable": true
}
},
"description": "Receiver contact for the delivery",
"example": {
"name": "Mr. John Doe",
"number": "10"
}
},
"country": {
"type": "string",
"description": "Country code for the delivery",
"example": "DE"
},
"project": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"description": "Project to which the delivery note belongs to",
"example": {
"id": "1"
}
},
"shippingMethod": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"description": "Shipping method used for the delivery note",
"example": {
"id": "1"
}
},
"type": {
"type": "string",
"description": "Internal type of the delivery note",
"example": "type"
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"canceled",
"sent",
"unknown"
],
"description": "Status of the delivery note",
"example": "created"
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
}
}
}
},
"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
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/deliveryNotes/{id}": {
"get": {
"tags": [
"Delivery Note"
],
"operationId": "deliveryNote.view",
"summary": "[EARLY ACCESS] View delivery note",
"description": "Returns details of a delivery note",
"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,
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"documentNumber": {
"type": "string",
"description": "Internal identification for the delivery note",
"example": "200001"
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"transactionNumber": {
"type": "string",
"description": "Transaction number associated with a delivery note",
"example": "transaction1"
},
"customerOrderNumber": {
"type": "string",
"description": "Customer order associated with a delivery note",
"example": "customerOrder1",
"nullable": true
},
"salesChannel": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"bodyIntroduction": {
"type": "string",
"description": "Initial description message for delivery note",
"example": "Initial info"
},
"bodyOutroduction": {
"type": "string",
"description": "Ending description message for delivery note",
"example": "Additional info"
},
"internalDesignation": {
"type": "string",
"description": "Internal designation for delivery note",
"example": "InternalDN1"
},
"date": {
"type": "string",
"format": "date",
"description": "Date of creation of a delivery note",
"example": "2025-01-01"
},
"status": {
"type": "string",
"enum": [
"completed",
"created",
"released",
"canceled",
"unknown"
],
"description": "Status of the delivery note",
"example": "completed"
},
"customer": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"number": {
"type": "string",
"nullable": true
}
},
"description": "Customer linked to a Sales Order",
"example": {
"id": "1"
}
},
"comment": {
"type": "string",
"example": "A comment about this delivery note",
"description": "Comment included in the delivery note",
"nullable": true
},
"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"
}
},
"language": {
"type": "object",
"additionalProperties": false,
"required": [
"iso2"
],
"properties": {
"iso2": {
"type": "string",
"description": "ISO 639-1 Code",
"nullable": true
}
},
"description": "Language information for a Sales Order",
"example": {
"iso2": "DE"
}
},
"updatedAt": {
"type": "string",
"format": "datetime",
"nullable": true,
"description": "Update date",
"example": "2024-10-15 15:03:46"
},
"log": {
"type": "object",
"additionalProperties": false,
"description": "Log information",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Creation date"
},
"createdBy": {
"type": "object",
"additionalProperties": false,
"description": "Author",
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
}
}
}
},
"example": {
"createdAt": "2023-12-01 00:00:00",
"createdBy": {
"id": "1",
"name": "User 1"
}
}
},
"delivery": {
"allOf": [
{
"type": "object",
"properties": {
"autoShipping": {
"type": "boolean"
},
"fastLane": {
"type": "boolean"
},
"shippingCosts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"shippingCostProduct",
"quantity"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"quantity": {
"type": "number",
"format": "double"
},
"comment": {
"type": "string"
},
"shippingCostProduct": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"freeFields": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"value"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"value": {
"type": "string"
}
}
}
},
"number": {
"type": "string",
"nullable": true
}
}
},
"tax": {
"type": "object",
"required": [
"taxText"
],
"properties": {
"vatCategory": {
"type": "string",
"nullable": true,
"enum": [
"reduced",
"normal",
"exempt"
],
"description": "VAT category. When importing a position only one of `rate` or `vatCategory` must be used.",
"example": "reduced"
},
"rate": {
"type": "number",
"format": "float",
"example": 0.5,
"nullable": true,
"description": "VAT rate. When importing a position only one of `rate` or `vatCategory` must be used."
},
"taxText": {
"type": "string",
"example": "Tax Text",
"nullable": true,
"description": "Tax Text"
}
}
},
"price": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"type": "string",
"format": "float"
},
"currency": {
"type": "string",
"enum": [
"EUR",
"PLN",
"CHF",
"USD",
"GBP"
]
}
}
},
"discount": {
"type": "number",
"format": "float",
"description": "percentage discount to be applied to the position, expressed as a decimal value (0.15
= 15% discount)"
},
"webId": {
"type": "string",
"description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform"
}
}
}
},
"shippingAddress": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"city",
"country",
"zipCode",
"street"
],
"properties": {
"type": {
"type": "string",
"enum": [
"mr",
"mrs",
"company",
"other"
]
},
"name": {
"type": "string"
},
"department": {
"type": "string"
},
"contactPerson": {
"type": "string"
},
"subDepartment": {
"type": "string"
},
"street": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"addressSupplement": {
"type": "string"
},
"gln": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
}
}
}
}
},
{
"type": "object",
"required": [
"shippingMethod"
],
"properties": {
"shippingMethod": {
"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"
}
},
"deliveryTerms": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"email": {
"type": "string",
"format": "email"
},
"conditions": {
"type": "string"
}
}
}
],
"description": "Delivery information for the delivery note",
"example": {
"autoShipping": true,
"fastLane": true,
"shippingMethod": {
"id": "1"
},
"shippingCosts": [
{
"id": "1",
"quantity": 3,
"shippingCostProduct": {
"id": "1"
}
}
],
"email": "user.email@email.org",
"conditions": "none"
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
}
}
},
"description": "Tags associated with the delivery note",
"example": [
{
"id": "1"
}
]
},
"positions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"product",
"quantity"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"quantity": {
"type": "number",
"format": "double"
},
"comment": {
"type": "string"
},
"product": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"freeFields": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"value"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"value": {
"type": "string"
}
}
}
},
"number": {
"type": "string",
"nullable": true
}
}
},
"tax": {
"type": "object",
"required": [
"taxText"
],
"properties": {
"vatCategory": {
"type": "string",
"nullable": true,
"enum": [
"reduced",
"normal",
"exempt"
],
"description": "VAT category. When editing/creating a position only one of `rate` or `vatCategory` must be used.",
"example": "reduced"
},
"rate": {
"type": "number",
"format": "float",
"example": 0.5,
"nullable": true,
"description": "VAT rate. When editing/creating a position only one of `rate` or `vatCategory` must be used."
},
"taxText": {
"type": "string",
"example": "Tax Text",
"nullable": true,
"description": "Tax Text"
}
}
},
"price": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"type": "string",
"format": "float"
},
"currency": {
"type": "string",
"enum": [
"EUR",
"PLN",
"CHF",
"USD",
"GBP"
]
}
}
},
"discount": {
"type": "number",
"format": "float",
"description": "percentage discount to be applied to the position, expressed as a decimal value (0.15
= 15% discount)"
},
"webId": {
"type": "string",
"description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform"
}
}
},
"description": "Items included within the delivery note",
"example": [
{
"product": {
"id": "1"
},
"quantity": 5
}
]
}
},
"description": "Data representation of a single delivery note",
"example": {
"id": "1",
"documentNumber": "200001",
"salesOrder": {
"id": "1"
},
"transactionNumber": "transaction1",
"customerOrderNumber": "customerOrder1",
"salesChannel": {
"id": "1"
},
"bodyIntroduction": "Initial info",
"bodyOutroduction": "Additional info",
"internalDesignation": "internalDN1",
"date": "2025-01-01",
"status": "completed",
"customer": {
"id": "1"
},
"comment": "A comment about this delivery note",
"project": {
"id": "1"
},
"language": {
"iso2": "DE"
},
"log": {
"createdAt": "2023-12-01 00:00:00",
"createdBy": {
"id": "1",
"name": "User 1"
}
},
"delivery": {
"autoShipping": true,
"fastLane": true,
"shippingMethod": {
"id": "1"
},
"shippingCosts": [
{
"id": "1",
"quantity": 3,
"shippingCostProduct": {
"id": "1"
}
}
],
"email": "user.email@email.org",
"conditions": "none"
},
"tags": [
{
"id": "1"
}
],
"positions": [
{
"product": {
"id": "1"
},
"quantity": 5
}
]
}
}
}
}
}
}
},
"401": {
"description": "Unable to authenticate the client",
"content": {
"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"
}
}
}
},
"/api/v1/deliveryNotesTags": {
"get": {
"tags": [
"Delivery Note Tag"
],
"operationId": "deliveryNoteTag.list",
"summary": "List delivery notes tags",
"description": "Returns a collection with all delivery notes tags.",
"parameters": [
{
"name": "filter",
"in": "query",
"style": "deepObject",
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"name",
"id"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"in",
"notIn",
"exactlyIn",
"allIn",
"allNotIn",
"contains",
"notContains",
"startsWith",
"endsWith",
"greaterThan",
"lessThan",
"is"
]
},
"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",
"name"
]
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
}
}
}
],
"responses": {
"200": {
"description": "Operation completed successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"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."
}
}
}
},
"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
}
}
}
}
},
"examples": {
"Lists all delivery notes tags": {
"value": {
"data": [
{
"id": "1",
"name": "Done",
"color": "339966"
},
{
"id": "5",
"name": "Prio",
"color": "ff00ff"
}
],
"extra": {
"totalCount": 2,
"page": {
"number": 1,
"size": 10
}
}
}
}
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/v1/deliveryNotes/{id}/deliveries": {
"get": {
"tags": [
"Delivery Note"
],
"operationId": "deliveryNote.deliveries.list",
"description": "Details of delivery note",
"summary": "[EARLY ACCESS] View delivery note deliveries aka shipments",
"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": "Delivery list",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder",
"shippingMethod"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
},
"link": {
"type": "string",
"description": "Carrier tracking link"
},
"carrier": {
"type": "string",
"description": "Carrier that shipping the delivery"
}
},
"description": "Tracking information for the delivery",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"shippingMethod": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"label": {
"type": "object",
"nullable": true,
"required": [
"fileType",
"fileContent"
],
"additionalProperties": false,
"properties": {
"fileType": {
"type": "string",
"description": "Label's file type",
"example": "image/gif"
},
"fileContent": {
"type": "string",
"description": "Base 64 encoded label",
"example": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Shipping label for the delivery",
"example": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
},
"example": {
"id": "DEL-12345",
"tracking": {
"number": "101010101010101",
"link": "https://carrier.example.com/track/101010101010101",
"carrier": "DHL"
},
"deliveryNote": {
"id": "DN-54321"
},
"salesOrder": {
"id": "SO-98765"
},
"shippingMethod": {
"id": "SM-12345"
},
"label": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Data representation of a single delivery aka shipment"
}
},
"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
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/deliveryNotes/{id}/shipments": {
"get": {
"tags": [
"Delivery Note"
],
"operationId": "deliveryNote.shipments.list",
"description": "Details of delivery note shipments",
"summary": "[EARLY ACCESS] View delivery note shipments aka deliveries",
"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": "Delivery list",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"deliveryNote",
"tracking",
"salesOrder",
"shippingMethod"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"tracking": {
"type": "object",
"required": [
"number"
],
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"description": "The tracking number provided by the carrier."
},
"link": {
"type": "string",
"description": "Carrier tracking link"
},
"carrier": {
"type": "string",
"description": "Carrier that shipping the delivery"
}
},
"description": "Tracking information for the delivery",
"example": {
"number": "101010101010101"
}
},
"deliveryNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"salesOrder": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"shippingMethod": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"label": {
"type": "object",
"nullable": true,
"required": [
"fileType",
"fileContent"
],
"additionalProperties": false,
"properties": {
"fileType": {
"type": "string",
"description": "Label's file type",
"example": "image/gif"
},
"fileContent": {
"type": "string",
"description": "Base 64 encoded label",
"example": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Shipping label for the delivery",
"example": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
},
"example": {
"id": "DEL-12345",
"tracking": {
"number": "101010101010101",
"link": "https://carrier.example.com/track/101010101010101",
"carrier": "DHL"
},
"deliveryNote": {
"id": "DN-54321"
},
"salesOrder": {
"id": "SO-98765"
},
"shippingMethod": {
"id": "SM-12345"
},
"label": {
"fileType": "image/gif",
"fileContent": "R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
},
"description": "Data representation of a single delivery aka shipment"
}
},
"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
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/deliveryTerms": {
"get": {
"tags": [
"Delivery Terms"
],
"operationId": "DeliveryTerms.list",
"summary": "List Delivery Terms",
"description": "Lists existing Delivery Terms",
"parameters": [
{
"name": "filter",
"in": "query",
"style": "deepObject",
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"type": "string",
"enum": [
"id",
"designation"
]
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"in",
"notIn",
"exactlyIn",
"allIn",
"allNotIn",
"contains",
"notContains",
"startsWith",
"endsWith",
"greaterThan",
"lessThan",
"is"
]
},
"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."
}
}
}
}
],
"responses": {
"200": {
"description": "Delivery Terms list",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"extra"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"designation"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"uuid": {
"description": "UUID identifier of the resource.",
"type": "string",
"pattern": "^$|^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$",
"example": "a00fd11e-3a67-433b-83c0-4e815fd4a0e1"
},
"designation": {
"type": "string",
"description": "Designation of delivery term",
"example": "Term"
}
}
}
},
"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": {
"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/employees": {
"get": {
"tags": [
"Employee"
],
"operationId": "employee.list",
"summary": "List employees",
"description": "Lists existing employees",
"parameters": [
{
"name": "searchTerm",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Employee minimal list.",
"content": {
"application/vnd.xentral.minimal.v1+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": {
"description": "Employee Number",
"type": "string",
"example": "342442"
},
"name": {
"description": "Employee Name",
"type": "string",
"example": "John"
}
}
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"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."
}
}
}
},
"/api/v1/products/{id}/externalReferences": {
"get": {
"tags": [
"External Reference"
],
"operationId": "externalReference.list",
"summary": "[EARLY ACCESS] List external references for given Product",
"description": "Returns list of external references for given Product.",
"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,
"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",
"minLength": 1,
"example": "Shopify"
},
"number": {
"x-description-missing": true,
"type": "string",
"minLength": 1,
"example": "1234567"
},
"isActive": {
"x-description-missing": true,
"type": "boolean",
"example": true
},
"isScannable": {
"x-description-missing": true,
"type": "boolean",
"example": true
},
"target": {
"x-description-missing": true,
"type": "object",
"example": {
"id": "3543",
"name": "Shopware",
"isActive": true
},
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string",
"minLength": 1
},
"isActive": {
"type": "boolean"
}
}
}
}
}
},
"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
}
}
}
}
},
"examples": {
"Lists all external references of a single product": {
"value": {
"data": [
{
"id": "1",
"name": "SKU",
"number": "11111",
"isActive": true,
"isScannable": false,
"target": {
"id": "1",
"name": "Shopware"
}
},
{
"id": "3",
"name": "SKU Shop",
"number": "22222",
"isActive": true,
"isScannable": false,
"target": {
"id": "1",
"name": "Shopware"
}
}
]
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
},
"429": {
"description": "Too many API calls made."
}
}
},
"post": {
"tags": [
"External Reference"
],
"operationId": "externalReference.create",
"summary": "[EARLY ACCESS] Create new external references for a given Product",
"description": "Creates new external references for a given Product",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "ExternalReference create request payload",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"isActive": {
"description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'",
"example": "'true'",
"oneOf": [
{
"type": "boolean"
},
{
"type": "number",
"enum": [
0,
1
]
},
{
"type": "string",
"enum": [
"true",
"false",
"True",
"False",
"TRUE",
"FALSE"
]
}
]
},
"isScannable": {
"description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'",
"example": "'true'",
"oneOf": [
{
"type": "boolean"
},
{
"type": "number",
"enum": [
0,
1
]
},
{
"type": "string",
"enum": [
"true",
"false",
"True",
"False",
"TRUE",
"FALSE"
]
}
]
},
"target": {
"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"
}
}
}
},
"examples": {
"Create external reference": {
"value": {
"name": "Example external reference",
"number": "1234567",
"isActive": true,
"isScannable": true,
"target": {
"id": "3543"
}
}
}
}
}
}
},
"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 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"429": {
"description": "Too many API calls made."
}
}
},
"patch": {
"tags": [
"External Reference"
],
"operationId": "externalReference.updateMultiple",
"summary": "[EARLY ACCESS] Update external references for a given Product",
"description": "Updates external references for a given Product",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "ExternalReference update multiple request payload",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"x-description-missing": true,
"type": "string",
"example": "Shopify"
},
"number": {
"x-description-missing": true,
"type": "string",
"example": "1234567"
},
"isActive": {
"description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'",
"example": "'true'",
"oneOf": [
{
"type": "boolean"
},
{
"type": "number",
"enum": [
0,
1
]
},
{
"type": "string",
"enum": [
"true",
"false",
"True",
"False",
"TRUE",
"FALSE"
]
}
]
},
"isScannable": {
"description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'",
"example": "'true'",
"oneOf": [
{
"type": "boolean"
},
{
"type": "number",
"enum": [
0,
1
]
},
{
"type": "string",
"enum": [
"true",
"false",
"True",
"False",
"TRUE",
"FALSE"
]
}
]
},
"target": {
"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"
}
}
}
}
},
"examples": {
"Update external references": {
"value": [
{
"id": "123",
"isActive": false
},
{
"id": "456",
"isActive": false
}
]
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"429": {
"description": "Too many API calls made."
}
}
},
"delete": {
"tags": [
"External Reference"
],
"operationId": "externalReference.deleteMultiple",
"summary": "[EARLY ACCESS] Delete external references of a given Product",
"description": "Deletes external references of a given Product",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "ExternalReference delete multiple request payload",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"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"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/v1/externalReferenceTargets": {
"get": {
"tags": [
"External Reference Target"
],
"operationId": "externalReferenceTarget.list",
"summary": "[EARLY ACCESS] List External Reference Targets",
"description": "Returns a collection with all External Reference Targets.",
"responses": {
"200": {
"description": "ExternalReferenceTarget list",
"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": {
"description": "The name of the external reference target",
"type": "string",
"minLength": 1,
"example": "Shopware"
},
"isActive": {
"description": "A flag to determine whether an external reference target is active",
"type": "boolean",
"example": true
}
}
}
}
}
},
"examples": {
"Lists all external reference targets": {
"value": {
"data": [
{
"id": "1",
"name": "Shopware",
"isActive": true
}
]
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"406": {
"description": "Requested resource representation does not exist."
}
}
}
},
"/api/stockMovementTypes": {
"post": {
"tags": [
"Stock Movement Types"
],
"operationId": "stockMovementType.create",
"summary": "[EARLY ACCESS] Create a stockMovementType",
"description": "Creates a new stock movement type.",
"requestBody": {
"description": "Stock movement type creation request.",
"content": {
"application/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"direction",
"active"
],
"properties": {
"name": {
"type": "string",
"nullable": false,
"example": "TestName",
"description": "Name of stock movement type"
},
"direction": {
"type": "string",
"nullable": false,
"example": "relocation",
"description": "Direction of stock movement type"
},
"active": {
"type": "boolean",
"nullable": false,
"example": true,
"description": "Only active stock movement types can be used"
},
"doctypeReference": {
"type": "string",
"nullable": true,
"example": "salesOrder",
"description": "Related document type"
}
}
},
"examples": {
"Create an stock movement type": {
"value": {
"name": "Test stock movement type",
"direction": "inbound",
"active": true,
"doctypeReference": "salesOrder"
}
}
}
}
}
},
"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 7807 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",
"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": {
"text/html": {
"schema": {
"type": "string",
"example": "Unauthorized"
}
}
}
},
"403": {
"description": "Unable to authorize the client"
},
"415": {
"description": "Resource representation send in the request is not supported."
},
"429": {
"description": "Too many API calls made."
}
}
}
},
"/api/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.v1-beta+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 7807 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",
"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": {
"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:\n\n**id** (string): Invoice ID\n\n**invoice** (string): Invoice Number\n\n**date** (date): accepted format: Y-m-d, example `2024-10-15`\n\n**status** (string): `created` `released` `sent` `canceled` `completed` `partialCancellation`\n\n**customerName** (string): first and last name of the Customer\n\n**customerNumber** (string): Customer Number\n\n**country** (string): Country Codes Alpha-2\n\n**projectId** (string): Project ID\n\n**projectName** (string): Project Name\n\n**projectAbbr** (string): Project Abbreviation\n\n**paymentMethod** (string): Payment Method\n\n**paymentStatus** (string): `pending` `paid` `partlyPaid` `canceled` `partialCancellation` `badDebt` `debited`\n\n**debit** (numeric): Debit, example: `10.50`\n\n**balance** (numeric): Balance, example: `10.50`\n\n**currency** (string): Currency ISO 4217 format, example `EUR`\n\n**shippingMethod** (string): Shipping Method\n\n**amountNet** (numeric): net amount of the Invoice, example: `10.50`\n\n**salesOrder** (string): Sales Order ID",
"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"
],
"example": "date"
},
"op": {
"type": "string",
"enum": [
"equals",
"notEquals",
"in",
"notIn",
"exactlyIn",
"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",
"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.v1+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",
"PLN",
"CHF",
"USD",
"GBP"
],
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"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"
]
},
"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
}
}
}
}
}
},
"application/vnd.xentral.default.v1+csv": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/invoices/{id}": {
"get": {
"tags": [
"Invoice"
],
"operationId": "invoice.view",
"summary": "View invoice",
"description": "Returns details of a single invoice.",
"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/vnd.xentral.default.v1-beta+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."
},
"documentNumber": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "1200132"
},
"documentDate": {
"x-description-missing": true,
"type": "string",
"format": "date-time",
"example": "2022-01-07T00:00:00+01:00"
},
"log": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"createdAt",
"createdBy",
"sentAt",
"sentBy",
"updatedAt"
],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"example": "2022-01-07T13:43:12+01:00"
},
"createdBy": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
}
},
"example": {
"name": "John Doe"
}
},
"sentAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2022-01-07T13:43:12+01:00"
},
"sentBy": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
}
},
"example": {
"name": "John Doe"
}
},
"updatedAt": {
"type": "string",
"format": "date-time",
"example": "2022-03-31T00:16:03+02:00"
}
},
"example": {
"createdAt": "2022-01-07T13:43:12+01:00",
"sentAt": null,
"createdBy": {
"name": "John Doe"
},
"sentBy": {
"name": "John Doe"
},
"updatedAt": "2022-03-31T00:16:03+02:00"
}
},
"amountGross": {
"x-description-missing": true,
"type": "number",
"format": "float",
"example": 49.99
},
"amountNet": {
"x-description-missing": true,
"type": "number",
"format": "float",
"example": 42.01
},
"costCenter": {
"x-description-missing": true,
"type": "string",
"example": "3456"
},
"status": {
"x-description-missing": true,
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"partialCancellation",
"unknown"
],
"example": "sent"
},
"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": "6",
"name": "Shopware",
"abbreviation": "B2C-SW"
}
},
"customer": {
"description": "An optional object with id and name",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name"
],
"nullable": true,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
}
},
"example": {
"id": "1337",
"name": "Diamond"
}
},
"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."
}
}
}
},
"externalOrderReference": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "62720"
},
"devCustomer": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "dev"
},
"billingAddress": {
"type": "object",
"description": "Billing address of the customer.",
"additionalProperties": false,
"required": [
"name",
"contactPerson",
"department",
"subdivision",
"street",
"additionalDetails",
"city",
"zipCode",
"country"
],
"nullable": true,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"name": {
"type": "string"
},
"contactPerson": {
"type": "string"
},
"department": {
"type": "string",
"nullable": true
},
"subdivision": {
"type": "string",
"nullable": true
},
"street": {
"type": "string"
},
"additionalDetails": {
"type": "string",
"nullable": true
},
"city": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "[A-Z]{2}"
},
"email": {
"type": "string",
"nullable": true
}
},
"example": {
"id": "1",
"name": "John Doe",
"contactPerson": "",
"department": "",
"subdivision": "",
"street": "Street 10",
"additionalDetails": "",
"city": "Berlin",
"zipCode": "10101",
"country": "DE"
}
},
"paymentTerms": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"required": [
"dueDate",
"earlyPaymentDate",
"earlyPaymentDiscount"
],
"nullable": true,
"properties": {
"dueDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"earlyPaymentDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"earlyPaymentDiscount": {
"type": "number",
"format": "float"
}
},
"example": {
"earlyPaymentDiscount": 0.5,
"earlyPaymentDate": "2022-01-17T00:00:00+01:00",
"dueDate": "2022-02-06T00:00:00+01:00"
}
},
"paymentMethodName": {
"x-description-missing": true,
"type": "string",
"example": "paypal"
},
"paymentStatus": {
"type": "string",
"description": "Status of the payment. Value `unknown` is displayed when a status from database cannot be identified. Value `unknown` cannot be used when creating or updating statuses (POST or PATCH endpoints)",
"enum": [
"pending",
"paid",
"partlyPaid",
"canceled",
"partialCancellation",
"badDebt",
"debited",
"unknown"
],
"example": "pending"
},
"dunning": {
"description": "Deprecated: use `dunningSettings.level` field instead",
"type": "string",
"nullable": true,
"example": "zahlungserinnerung"
},
"dunningDate": {
"description": "Deprecated: use `dunningSettings.date` field instead",
"type": "string",
"format": "date",
"nullable": true,
"example": "2022-08-10"
},
"dunningSettings": {
"description": "Dunning setting for document",
"type": "object",
"additionalProperties": false,
"required": [
"level",
"date",
"comment",
"sent"
],
"nullable": true,
"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": "First reminder sent",
"sent": true
}
},
"dunningManualSettings": {
"description": "Expert mode: The payment settings can be set manually with this check mark. Note: This tick overrides the automatic calculation of the incoming payment. This means that the invoice is NOT included in the dunning process. If you use the incoming payment via the account statements, this checkmark should only be used for manual adjustments, because these settings are usually set automatically via the incoming payment.",
"type": "object",
"additionalProperties": false,
"required": [
"paymentStatus",
"paidAt",
"actualAmount",
"discountGiven"
],
"nullable": true,
"properties": {
"paymentStatus": {
"type": "string",
"description": "Status of the payment. Value `unknown` is displayed when a status from database cannot be identified. Value `unknown` cannot be used when creating or updating statuses (POST or PATCH endpoints)",
"enum": [
"pending",
"paid",
"partlyPaid",
"canceled",
"partialCancellation",
"badDebt",
"debited",
"unknown"
],
"example": "pending"
},
"paidAt": {
"description": "Date of the payment",
"type": "string",
"format": "date",
"nullable": true,
"example": "2022-08-10"
},
"actualAmount": {
"description": "Amount of the payment",
"type": "number",
"format": "float",
"example": 22.33
},
"discountGiven": {
"description": "Discount given for a payment",
"type": "number",
"format": "float",
"example": 22.33
}
},
"example": {
"paymentStatus": "paid",
"paidAt": "2022-08-10",
"actualAmount": 22.33,
"discountGiven": 2
}
},
"gln": {
"x-description-missing": true,
"type": "string",
"nullable": true,
"example": "12345"
},
"taxation": {
"x-description-missing": true,
"type": "number",
"example": 0
},
"positions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "number"
},
"position": {
"type": "number"
},
"saleOrderPositionId": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"productId": {
"type": "number"
},
"productNumber": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"price": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"vatCategory": {
"type": "string"
},
"taxRate": {
"type": "number",
"format": "float"
},
"discount": {
"type": "number",
"format": "float",
"nullable": true
}
},
"example": {
"id": 1,
"position": 1,
"saleOrderPositionId": 3,
"createdAt": "2022-08-10T10:14:26+02:00",
"productId": 1,
"productNumber": "100001",
"description": "Kaffee ganze Bohne 1kg",
"quantity": 1,
"price": {
"amount": "24.99",
"currency": "EUR"
},
"vatCategory": "normal",
"taxRate": 19,
"discount": 0
}
}
}
},
"example": {
"id": "142",
"documentNumber": "1200132",
"documentDate": "2022-01-07T00:00:00+01:00",
"log": {
"createdAt": "2022-01-07T13:43:12+01:00",
"sentAt": "2022-01-07T13:43:12+01:00",
"createdBy": {
"name": "John Doe"
},
"sentBy": {
"name": "John Doe"
},
"updatedAt": "2022-03-31T00:16:03+02:00"
},
"amountGross": 49.99,
"amountNet": 42.01,
"costCenter": "3456",
"status": "sent",
"project": {
"id": "6",
"name": "Shopware",
"abbreviation": "B2C-SW"
},
"customer": {
"id": "3099",
"name": "John Doe"
},
"externalOrderReference": "62720",
"devCustomer": "50161",
"billingAddress": {
"id": "1",
"name": "John Doe",
"contactPerson": "",
"department": "",
"subdivision": "",
"street": "Street 10",
"additionalDetails": "",
"city": "Berlin",
"zipCode": "10101",
"country": "DE",
"email": "john.doe@email.de"
},
"paymentMethodName": "paypal",
"paymentStatus": "pending",
"dunning": "zahlungserinnerung",
"dunningDate": null,
"gln": "12345",
"taxation": 0,
"tags": [],
"positions": [
{
"id": 421,
"position": 1,
"saleOrderPositionId": 13521,
"createdAt": "2022-01-07T13:43:12+01:00",
"productId": 864,
"productNumber": "FR5232501",
"description": "Example Product",
"quantity": 1,
"price": {
"amount": "49.99",
"currency": "EUR"
},
"vatCategory": "normal",
"taxRate": 0,
"discount": 0
}
],
"paymentTerms": {
"earlyPaymentDiscount": 0,
"earlyPaymentDate": "2022-01-17T00:00:00+01:00",
"dueDate": "2022-02-06T00:00:00+01:00"
}
}
}
}
}
},
"application/vnd.xentral.minimal.v1+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "3"
}
},
"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
}
}
}
}
}
},
"application/vnd.xentral.default.v1-beta+pdf": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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."
}
}
},
"delete": {
"tags": [
"Invoice"
],
"operationId": "invoice.delete",
"summary": "[ALPHA] Delete single invoice",
"description": "Delete a single invoice",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"403": {
"description": "Unable to authorize the client"
},
"404": {
"description": "Resource was not found or not enough access privileges"
},
"429": {
"description": "Too many API calls made."
}
}
},
"patch": {
"tags": [
"Invoice"
],
"operationId": "invoice.update",
"summary": "[EARLY ACCESS] Update single invoice",
"description": "Update a single invoice",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"requestBody": {
"description": "[EARLY ACCESS] Update single invoice",
"content": {
"application/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"date": {
"type": "string",
"format": "date"
},
"costCenter": {
"type": "string"
},
"project": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"customer": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"tags": {
"type": "array",
"items": {
"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"
}
}
},
"devCustomer": {
"type": "string",
"nullable": true
},
"billingAddress": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"contactPerson",
"department",
"subdivision",
"street",
"additionalDetails",
"city",
"zipCode",
"country"
],
"nullable": true,
"properties": {
"name": {
"type": "string"
},
"contactPerson": {
"type": "string"
},
"department": {
"type": "string",
"nullable": true
},
"subdivision": {
"type": "string",
"nullable": true
},
"street": {
"type": "string"
},
"additionalDetails": {
"type": "string",
"nullable": true
},
"city": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "[A-Z]{2}"
}
}
},
"paymentMethodName": {
"type": "string"
},
"gln": {
"type": "string",
"nullable": true
},
"taxation": {
"type": "string",
"pattern": "\\d+"
},
"dunningSettings": {
"description": "Dunning setting for document",
"type": "object",
"additionalProperties": false,
"required": [
"level",
"date",
"comment",
"sent"
],
"nullable": true,
"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": "First reminder sent",
"sent": true
}
},
"dunningManualSettings": {
"description": "Expert mode: The payment settings can be set manually with this check mark. Note: This tick overrides the automatic calculation of the incoming payment. This means that the invoice is NOT included in the dunning process. If you use the incoming payment via the account statements, this checkmark should only be used for manual adjustments, because these settings are usually set automatically via the incoming payment.",
"type": "object",
"additionalProperties": false,
"required": [
"paymentStatus",
"paidAt",
"actualAmount",
"discountGiven"
],
"nullable": true,
"properties": {
"paymentStatus": {
"type": "string",
"description": "Status of the payment. Value `unknown` is displayed when a status from database cannot be identified. Value `unknown` cannot be used when creating or updating statuses (POST or PATCH endpoints)",
"enum": [
"pending",
"paid",
"partlyPaid",
"canceled",
"partialCancellation",
"badDebt",
"debited",
"unknown"
],
"example": "pending"
},
"paidAt": {
"description": "Date of the payment",
"type": "string",
"format": "date",
"nullable": true,
"example": "2022-08-10"
},
"actualAmount": {
"description": "Amount of the payment",
"type": "number",
"format": "float",
"example": 22.33
},
"discountGiven": {
"description": "Discount given for a payment",
"type": "number",
"format": "float",
"example": 22.33
}
},
"example": {
"paymentStatus": "paid",
"paidAt": "2022-08-10",
"actualAmount": 22.33,
"discountGiven": 2
}
}
}
},
"examples": {
"Update invoice": {
"value": {
"date": "2020-01-01",
"costCenter": "3456",
"project": {
"id": "1"
},
"customer": {
"id": "12"
},
"tags": [
{
"id": "1"
},
{
"id": "2"
}
],
"devCustomer": "dev",
"billingAddress": {
"name": "John Doe",
"contactPerson": "John Doe",
"department": "Sales",
"subdivision": "Sales",
"street": "Main Street 1",
"additionalDetails": "1st floor",
"city": "New York",
"zipCode": "12345",
"country": "US"
},
"paymentMethodName": "invoice",
"gln": null,
"taxation": "0",
"dunningSettings": {
"level": "paymentReminder",
"date": "2022-08-10",
"comment": "This is a comment",
"sent": true
},
"dunningManualSettings": {
"paymentStatus": "pending",
"paidAt": "2022-08-10",
"actualAmount": 10.12,
"discountGiven": 1.12
}
}
}
}
}
}
},
"responses": {
"204": {
"description": "Operation completed successfully, no response body"
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/invoices/{id}/balance": {
"get": {
"tags": [
"Invoice"
],
"operationId": "invoice.balance",
"summary": "View Invoice Balance",
"description": "Returns balance information (documents, payments) for a single invoice",
"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/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"documents": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"invoices": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
},
"creditNotes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"example": {
"invoices": [
{
"id": "1",
"amount": {
"amount": "13.37",
"currency": "EUR"
},
"date": "2023-08-13T14:45:36+02:00"
}
],
"creditNotes": [
{
"id": "1",
"amount": {
"amount": "13.37",
"currency": "EUR"
},
"date": "2023-08-13T14:45:36+02:00"
}
]
}
},
"payments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"reference": {
"type": "object",
"additionalProperties": false,
"description": "Only one of the actually referenced object.",
"properties": {
"invoice": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"creditNote": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"type": {
"type": "string",
"enum": [
"incoming",
"outgoing"
],
"nullable": false
},
"statementId": {
"type": "string"
},
"accountName": {
"type": "string"
},
"amount": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"date": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
},
"example": {
"documents": {
"invoices": [
{
"id": "87",
"amount": {
"amount": "1483.63",
"currency": "EUR"
},
"date": "2024-03-08T00:00:00+01:00"
}
],
"creditNotes": [
{
"id": "2",
"amount": {
"amount": "24.99",
"currency": "EUR"
},
"date": "2024-06-17T00:00:00+02:00"
}
]
},
"payments": []
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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"
}
}
}
}
}
]
}
}
}
},
"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/invoices/{id}/documents": {
"get": {
"tags": [
"Invoice"
],
"operationId": "invoice.documents.view",
"summary": "[EARLY ACCESS] View related documents for invoice",
"description": "Returns details for related documents of a single invoice.",
"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/vnd.xentral.default.v1-beta+json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"x-description-missing": true,
"type": "object",
"additionalProperties": false,
"properties": {
"salesOrder": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"documentNumber": {
"type": "string"
},
"documentUrl": {
"type": "string"
},
"documentDate": {
"type": "string",
"format": "date"
}
}
}
},
"deliveryNotes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"documentNumber": {
"type": "string"
},
"documentUrl": {
"type": "string"
},
"documentDate": {
"type": "string",
"format": "date"
}
}
}
},
"creditNotes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"approved",
"canceled",
"completed",
"created",
"unknown"
]
},
"documentNumber": {
"type": "string"
},
"documentUrl": {
"type": "string"
},
"documentDate": {
"type": "string",
"format": "date"
}
}
}
},
"returns": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"status": {
"type": "string",
"enum": [
"created",
"released",
"sent",
"canceled",
"completed",
"unknown"
]
},
"documentNumber": {
"type": "string"
},
"documentUrl": {
"type": "string"
},
"documentDate": {
"type": "string",
"format": "date"
}
}
}
},
"pdfArchives": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
},
"documentUrl": {
"type": "string"
},
"documentDate": {
"type": "string",
"format": "datetime"
},
"documentName": {
"type": "string"
},
"createdBy": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
},
"example": {
"salesOrder": [
{
"id": "1",
"status": "completed",
"documentNumber": "2022-200000",
"documentUrl": "https://example.xentral.biz?module=auftrag&action=pdf&id=1",
"documentDate": "2024-02-22"
}
],
"deliveryNotes": [
{
"id": "3",
"status": "sent",
"documentNumber": "2022-300002",
"documentUrl": "https://example.xentral.biz?module=lieferschein&action=pdf&id=3",
"documentDate": "2023-08-06"
}
],
"creditNotes": [
{
"id": "19",
"status": "created",
"documentNumber": "2022-300002",
"documentUrl": "https://example.xentral.biz?module=rechnung&action=pdffromarchive&id=19",
"documentDate": "2022-08-10"
}
],
"returns": [
{
"id": "19",
"status": "created",
"documentNumber": "2022-300002",
"documentUrl": "https://example.xentral.biz?module=rechnung&action=pdffromarchive&id=19",
"documentDate": "2022-08-10"
}
],
"pdfArchives": [
{
"id": "19",
"documentName": "0be068caab8e89774948bbd719453e1b_3_20220810_RE2022-400002.pdf",
"createdBy": {
"name": "Administrator"
},
"documentUrl": "https://example.xentral.biz?module=rechnung&action=pdffromarchive&id=19",
"documentDate": "2022-08-10 10:41:17"
}
]
}
}
}
}
}
}
},
"400": {
"description": "IETF RFC 7807 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",
"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": {
"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/invoices/{id}/positions": {
"post": {
"tags": [
"Invoice"
],
"operationId": "invoice.createPositions",
"summary": "Create Positions for Invoice",
"description": "Adds invoice positions",
"requestBody": {
"description": "Invoice positions object\n\n The following payload structure is available:\n\nWhen a position has `salesOrderPosition.id` in the payload then product, quantity, price, vatCategory, taxRate, discounts are optional. The optional values override the values fetched from a sales order position\n\nWhen `salesOrderPosition.id` is not present in the payload or null, then product, quantity, price, vatCategory, taxRate, discounts are required",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"salesOrderPosition": {
"description": "Nullable reference to another resource",
"type": "object",
"additionalProperties": false,
"nullable": true,
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
},
"example": {
"id": "1337"
}
},
"product": {
"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"
}
},
"quantity": {
"description": "The quantity for the position",
"type": "string",
"format": "float",
"example": "2.0"
},
"price": {
"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",
"PLN",
"CHF",
"USD",
"GBP"
],
"description": "Currency matches one of currency values as specified in ISO-4217.",
"example": "PLN"
}
}
},
"deliveryDate": {
"description": "The VAT category that applies to the position",
"type": "string",
"format": "date",
"example": "2024-12-23"
},
"discounts": {
"description": "Discounts applied to position",
"type": "object",
"additionalProperties": false,
"properties": {
"totalPercent": {
"description": "The percentage discount applied to position",
"type": "string",
"format": "float",
"nullable": true,
"example": "38.45"
}
},
"example": {
"totalPercent": "38.45"
}
}
}
}
},
"examples": {
"Create invoice positions": {
"value": [
{
"product": {
"id": "1"
},
"quantity": "1.0",
"price": {
"amount": "100.00",
"currency": "EUR"
},
"deliveryDate": "2024-12-23"
},
{
"salesOrderPosition": {
"id": "2"
}
}
]
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The resource's identifier.",
"schema": {
"type": "string",
"pattern": "\\d+",
"example": "17",
"description": "Resource identifier."
}
}
],
"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 7807 Problem API compliant response",
"content": {
"application/problem+json": {
"schema": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"violations"
],
"properties": {
"type":