{
"swagger": "2.0",
"info": {
"version": "0.9.7",
"description": "Webservice für den Briefversand. Ihre Briefe werden durch unser System ausgedruckt, kuvertiert, frankiert und zur Deutschen Post gebracht.\n\nFür eine detaillierte Beschreibung schauen Sie bitte in das Modell. Hinweis: Wenn Sie als Benutzer eingeloggt sind, laufen alle Anfragen gegen das Produktiv-System. Somit stornieren, löschen, ... oder versenden Sie Ihre Briefe wirklich! Falls Sie Zugriff auf unser Testsystem benötigen, stellen Sie gerne eine Anfrage an kontakt@binect.de.",
"title": "Binect API REST",
"termsOfService": "https://app.binect.de/downloadFile?fileId=2",
"contact": {
"name": "kontakt@binect.de"
}
},
"host": "",
"basePath": "/binectapi/v1",
"schemes": [
"https"
],
"securityDefinitions": {
"basicAuth": {
"type": "basic",
"description": "HTTP Basic Authentication."
}
},
"security": [
{
"basicAuth": []
}
],
"paths": {
"/documents": {
"post": {
"tags": [
"documents"
],
"description": "Uploads a new document. The document shall be a letter or a serial letter. \nThe letter contains a valid address in the proper print area and respects the exclusion areas. \nThe content must be base64 encoded.\nThe document will be validated. \nIf validation fails, an optional correction (transformation, cover page, address label) will be provided.\nThe response will contain a valid document (letter/serial letter) or an 'error' object.\n\nThe document is normalized with ghostscript, therefore we recommend a visible check of the document with GET /documents/{documentID}/pdf.\n\nThe document status can have the following codes:\n\n 2 (is shippable),\n \n 7 (is erroneous)\n \n",
"parameters": [
{
"name": "upload",
"in": "body",
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"$ref": "#/definitions/Content"
},
"options": {
"$ref": "#/definitions/Options"
},
"attributes": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
},
"splitParams": {
"description": "If the uploaded document is a serial letter, define how it shall be split. only one of the property 'splitToken' or 'splitAfterNumberOfPages' can be used.",
"type": "object",
"properties": {
"splitToken": {
"type": "string",
"description": "This token is used to split the serial letter."
},
"splitAfterNumberOfPages": {
"type": "integer",
"format": "int32",
"description": "Every N pages the serial letter is split."
}
},
"example": {
"splitToken": "Sehr geehrte"
}
},
"responseFormat": {
"$ref": "#/definitions/ResponseFormatEnum"
}
},
"example": {
"content": {
"filename": "test.pdf",
"content": "BASE64 encoded string"
},
"options": {
"simplex": false,
"color": false
}
}
}
}
],
"responses": {
"200": {
"description": "Document created, may be erroneous.",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"413": {
"description": "Request Entity Too Large, Limit is 12 MB"
}
}
},
"get": {
"tags": [
"documents"
],
"description": "Gets all uploaded letter references which are shippable.\n\nShippable documents can have the following status codes:\n\n 2 (is shippable)\n
\nOptional a filter on attributes can be defined.
\nattributes is a JSON-formated string.
\nThis object is an array of LetterAtributte\n",
"responses": {
"200": {
"description": "A list of all uploads which are shippable documents.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/documents/errors": {
"get": {
"tags": [
"documents"
],
"description": "Gets all uploaded letter references which are erroneous.\n\nErroneous documents can have the following status codes:\n\n 7 (erroneous)\n",
"responses": {
"200": {
"description": "A list of all uploaded erroneous documents. Please check the error message in the response and also have a look at the preview.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/documents/{documentID}": {
"get": {
"tags": [
"documents"
],
"description": "Gets the referenced document.\nThe document is a letter, a serial letter or an 'error' object.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Deletes the referenced document.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/findbyAttributes": {
"get": {
"tags": [
"documents"
],
"description": "Gets all uploaded letters which were marked with the given attributes.
\nThere must be at least one pair of the parameters key and value. Take care that of the order of the keys and values. \n",
"parameters": [
{
"name": "key",
"in": "query",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"allowEmptyValue": false,
"collectionFormat": "multi"
},
{
"name": "value",
"in": "query",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"allowEmptyValue": false,
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
}
}
}
},
"/documents/{documentID}/status": {
"get": {
"tags": [
"documents"
],
"description": "Gets status of a document\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/DocumentStatus"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/options": {
"get": {
"tags": [
"documents"
],
"description": "Gets document's options.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Options"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"put": {
"tags": [
"documents"
],
"description": "Updates document's options\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "options",
"in": "body",
"schema": {
"$ref": "#/definitions/Options"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Options"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/attributes": {
"get": {
"tags": [
"documents"
],
"description": "Gets document's attributes\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"post": {
"tags": [
"documents"
],
"description": "Marks the document with certain attributes.\n",
"parameters": [
{
"in": "path",
"name": "documentID",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "attributes",
"in": "body",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/attributes/{key}": {
"get": {
"tags": [
"documents"
],
"description": "Gets the document's attribute for a specified key.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/LetterAttribute"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"put": {
"tags": [
"documents"
],
"description": "Updates the document's attribute for a specified key.\n",
"consumes": [
"application/x-www-form-urlencoded"
],
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "value",
"in": "formData",
"required": true,
"type": "string",
"allowEmptyValue": false
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/LetterAttribute"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Removes an attribute from the document.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "key",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/pdf": {
"get": {
"tags": [
"documents"
],
"description": "Gets the referenced document as PDF preview.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "file"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
},
"406": {
"description": "Not Acceptable"
}
}
}
},
"/documents/{documentID}/png": {
"get": {
"tags": [
"documents"
],
"description": "Gets the referenced document as PNG preview.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "file"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
},
"406": {
"description": "Not Acceptable"
}
}
}
},
"/documents/{documentID}/transformations": {
"put": {
"tags": [
"documents"
],
"description": "Applies a transformation of the document's first page.
After transformation, the document is validated once more. Therefore, please check the document's status again after performing any transformations.
Every transformation is applied on the original version of the document.
\"offsetX\" and \"offsetY\" affect the horizontal and vertical position, moving the document along the x and y axis, using [mm] as a unit. Starting point is the upper left corner of the page.
Also scaleX and scaleY can be independently used for scaling. Factor 1 corresponds to 100%, so in order to shrink, use values smaller than 1. Scaling refers to the center of the page. \n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "transformation",
"in": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"scaleX": {
"type": "number",
"format": "double"
},
"scaleY": {
"type": "number",
"format": "double"
},
"offsetX": {
"type": "number",
"format": "double"
},
"offsetY": {
"type": "number",
"format": "double"
}
}
}
}
],
"responses": {
"200": {
"description": "Document updated",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Removes the performed transformation on the document and rolls back to the original version of the document\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/coverpage": {
"put": {
"tags": [
"documents"
],
"description": "Creates a cover page for the document, so a receiving address is obligatory.
The return address is optional, also the text on the coverpage below the address.\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "coverPage",
"in": "body",
"schema": {
"type": "object",
"required": [
"receivingAddress"
],
"properties": {
"receivingAddress": {
"$ref": "#/definitions/Address"
},
"returnAddress": {
"$ref": "#/definitions/Address"
},
"coverText": {
"description": "optional text on the cover page",
"type": "object",
"required": [
"text"
],
"properties": {
"subject": {
"description": "optional subject text on the cover page",
"type": "string"
},
"date": {
"description": "optional date on the cover page",
"type": "string",
"format": "date"
},
"text": {
"description": "Text on the cover page. Only plain text is supported. Start a new line with '\\n'.",
"type": "string"
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "Document updated",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
},
"406": {
"description": "Not Acceptable"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Removes the cover page from the document.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/attachments": {
"get": {
"tags": [
"documents"
],
"description": "Gets document's all attachments\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "List of attachments",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"post": {
"tags": [
"documents"
],
"description": "Append an Attachment to a document after already appended attachments. The list of all attachments of the document is returned\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "appendAttachment",
"in": "body",
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"$ref": "#/definitions/Content"
},
"newSheet": {
"description": "The Attachment will start on the front page of a sheet",
"type": "boolean",
"default": true
},
"remarks": {
"description": "Remarks to the attachment",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Attachment created",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document do not exist"
}
}
},
"patch": {
"tags": [
"documents"
],
"description": "Append a list of attachments to a document.Already appended attachments stay unchanged.The new attachments will be append at the end in order of list. If the order of the attachments is important take care of this.",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "attachmentIDs",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
}
}
],
"responses": {
"200": {
"description": "Append a list of attachments to a document",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document(s) do not exist"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Detach all attachments of the document\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/documents/{documentID}/attachments/{attachmentID}": {
"post": {
"tags": [
"documents"
],
"description": "Append an Attachment to a document after already appended attachments. The list of all attachments of the document is returned\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "attachmentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"delete": {
"tags": [
"documents"
],
"description": "Remove an attachment from the document\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "attachmentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Dcument not found"
}
}
}
},
"/sendings": {
"post": {
"tags": [
"sendings"
],
"description": "Announces a letter (its ID) or a list of letters (list of IDs) which are already uploaded for delivering.\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentIds",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
}
}
],
"responses": {
"200": {
"description": "Letter created, may be faulty.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document(s) do not exist"
}
}
},
"get": {
"tags": [
"sendings"
],
"description": "Gets all document references, which are prepared for delivering or are already delivered.\n\nSendings can have the following status codes:\n \n 3 (in production, waiting to be sent),\n \n 4 (in print process),\n \n 5 (is sent),\n \n 6 (is canceled),\n \n 7 (is erroneous)\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"403": {
"description": "Forbidden"
}
}
},
"put": {
"tags": [
"sendings"
],
"description": "Cancels the delivery of a list of letters (list of IDs). Only not shipped letters are canceled.\n .\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "documentIds",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
}
}
],
"responses": {
"200": {
"description": "List of document status (documentID and status). \n\n In case of a serial document, the status of the child documents are also listed",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentStatus"
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document(s) do not exist"
}
}
}
},
"/sendings/document": {
"post": {
"tags": [
"sendings"
],
"description": "Document is directly sent after upload, if it is successfully validated.\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "shipping",
"in": "body",
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"$ref": "#/definitions/Content"
},
"options": {
"$ref": "#/definitions/Options"
},
"attributes": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
},
"responseFormat": {
"$ref": "#/definitions/ResponseFormatEnum"
}
}
}
}
],
"responses": {
"200": {
"description": "Document created, may be faulty.",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
},
"413": {
"description": "Request Entity Too Large, Limit is 12 MB"
}
}
}
},
"/sendings/status": {
"get": {
"tags": [
"sendings"
],
"description": "Gets status of all documents, which are prepared for delivering or are already delivered.\n\n The Query can be optional narrowed with a list of DocumentIds.\n\n Sendings can have the following status codes:\n \n 3 (in production, waiting to be sent),\n \n 4 (in print process),\n \n 5 (is sent),\n \n 6 (is canceled),\n \n 7 (is erroneous)\n",
"parameters": [
{
"name": "documentIds",
"in": "query",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"collectionFormat": "multi",
"allowEmptyValue": false
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentStatus"
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/sendings/{documentID}/status": {
"get": {
"tags": [
"sendings"
],
"description": "Gets status of a document, which are prepared for delivering or are already delivered.\n\nSendings can have the following status codes:\n \n 3 (in production, waiting to be sent),\n \n 4 (in print process),\n \n 5 (is sent),\n \n 6 (is canceled),\n \n 7 (is erroneous)\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/DocumentStatus"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/sendings/{documentID}": {
"post": {
"tags": [
"sendings"
],
"description": "Announces the delivery of a letter, if it isn't yet shipped.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"get": {
"tags": [
"sendings"
],
"description": "Gets a referenced sending.\nThe sending is a letter, serial letter or an 'error' object.\n",
"parameters": [
{
"name": "documentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Document"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
},
"put": {
"tags": [
"sendings"
],
"description": "Cancels the delivery of a letter, if it isn't already shipped.\n",
"parameters": [
{
"in": "path",
"name": "documentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Status"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
},
"406": {
"description": "Not Acceptable"
}
}
},
"delete": {
"tags": [
"sendings"
],
"description": "Deletes a canceled or a delivered and sent document from the system.\n",
"parameters": [
{
"in": "path",
"name": "documentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document not found"
}
}
}
},
"/attachments": {
"post": {
"tags": [
"attachments"
],
"description": "Upload an attachment\n",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "attachmentData",
"in": "body",
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"$ref": "#/definitions/Content"
},
"newSheet": {
"description": "The Attachment will start on the front page of a sheet",
"type": "boolean",
"default": true
},
"remarks": {
"description": "Remarks to the attachment",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Attachment created.",
"schema": {
"$ref": "#/definitions/Attachment"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"413": {
"description": "Request Entity Too Large, Limit is 12 MB"
}
}
},
"get": {
"tags": [
"attachments"
],
"description": "Gets all attachment references.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/attachments/{attachmentID}": {
"get": {
"tags": [
"attachments"
],
"description": "Gets referenced attachment.\n",
"parameters": [
{
"in": "path",
"name": "attachmentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Attachment"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
}
}
},
"delete": {
"tags": [
"attachments"
],
"description": "Delete the referenced attachment.The attachment can only be deleted if it is not appended to a none sended document.",
"parameters": [
{
"in": "path",
"name": "attachmentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
},
"406": {
"description": "Not Acceptable"
}
}
}
},
"/attachments/{attachmentID}/pdf": {
"get": {
"tags": [
"attachments"
],
"description": "Gets the referenced attachment as PDF preview.\n",
"parameters": [
{
"name": "attachmentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "file"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
},
"406": {
"description": "Not Acceptable"
}
}
}
},
"/attachments/{attachmentID}/png": {
"get": {
"tags": [
"attachments"
],
"description": "Gets the referenced attachment as PNG preview of the first page.\n",
"parameters": [
{
"name": "attachmentID",
"in": "path",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "file"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
},
"406": {
"description": "Not Acceptable"
}
}
}
},
"/attachments/{attachmentID}/documents": {
"get": {
"tags": [
"attachments"
],
"description": "Gets all unsended documents to which this attachment is append.\n",
"parameters": [
{
"in": "path",
"name": "attachmentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
}
}
},
"patch": {
"tags": [
"attachments"
],
"description": "Append this attachment to all documents in the list.The attachement is append at end of the document after already exkisting attachment.\n",
"consumes": [
"application/json"
],
"parameters": [
{
"in": "path",
"name": "attachmentID",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "doumentIDs",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
}
}
],
"responses": {
"200": {
"description": "Append this attachments to all documents in the list",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentStatus"
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Document(s) do not exist"
}
}
},
"delete": {
"tags": [
"attachments"
],
"description": "Remove the referenced attachment from all documents, which are not yet shipped.\n",
"parameters": [
{
"in": "path",
"name": "attachmentID",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentStatus"
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Attachment not found"
}
}
}
},
"/accounts": {
"get": {
"tags": [
"accounts"
],
"description": "Gets the account's financial data.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Account"
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/accounts/personaldata": {
"get": {
"tags": [
"accounts"
],
"description": "Gets the account's personal data.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/User"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "User not found"
}
}
},
"patch": {
"tags": [
"accounts"
],
"description": "Updates the personal data\n",
"parameters": [
{
"name": "personalData",
"in": "body",
"required": true,
"schema": {
"description": "The customer's personal data.",
"type": "object",
"properties": {
"forename": {
"type": "string"
},
"surname": {
"type": "string"
},
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"plz": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"organization": {
"type": "string"
},
"title": {
"type": "string"
},
"phone": {
"type": "string"
},
"partnerId": {
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/User"
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "User not found"
}
}
}
},
"/accounts/options": {
"get": {
"tags": [
"accounts"
],
"description": "Gets default options which are assigned to the account.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Options"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "User not found"
}
}
},
"put": {
"tags": [
"accounts"
],
"description": "Updates default options which are assigned to the account.\n",
"parameters": [
{
"name": "defaultOptions",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/Options"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/Options"
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "User not found"
}
}
}
},
"/accounts/coworkers": {
"get": {
"tags": [
"accounts"
],
"description": "Gets the coworkers.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Coworker"
}
}
},
"403": {
"description": "Forbidden"
}
}
}
},
"/accounts/coworkers/{debitornumber}/journal/{month}": {
"get": {
"tags": [
"accounts"
],
"description": "Gets all transctions of a month for a coworker.\n",
"parameters": [
{
"in": "path",
"name": "debitornumber",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "month",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Transaction"
}
}
},
"404": {
"description": "User not found"
}
}
}
},
"/accounts/journal/{month}": {
"get": {
"tags": [
"accounts"
],
"description": "Gets all transctions of a month.\n",
"parameters": [
{
"in": "path",
"name": "month",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Transaction"
}
}
}
}
}
},
"/invoices": {
"get": {
"tags": [
"invoices"
],
"description": "Gets all stored invoices references.\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Invoice"
}
}
}
}
}
},
"/invoices/{invoiceNumber}": {
"get": {
"tags": [
"invoices"
],
"description": "Gets all transctions of the invoice.\n",
"parameters": [
{
"in": "path",
"name": "invoiceNumber",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Transaction"
}
}
}
}
}
},
"/invoices/{invoiceNumber}/pdf": {
"get": {
"tags": [
"invoices"
],
"description": "Get a specific invoice as PDF.\n",
"parameters": [
{
"in": "path",
"name": "invoiceNumber",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "the invoice as PDF",
"schema": {
"type": "file"
}
},
"404": {
"description": "Document not found"
}
}
}
}
},
"definitions": {
"Document": {
"type": "object",
"required": [
"id",
"filename",
"status",
"documentType"
],
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"filename": {
"type": "string"
},
"numberOfPages": {
"type": "integer",
"format": "int32"
},
"status": {
"$ref": "#/definitions/Status"
},
"documentType": {
"type": "string",
"enum": [
"Letter",
"SerialLetter"
]
},
"letter": {
"$ref": "#/definitions/Letter"
},
"serialLetter": {
"$ref": "#/definitions/SerialLetter"
}
}
},
"Attachment": {
"type": "object",
"required": [
"id",
"filename",
"numberOfPages",
"newSheet"
],
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"filename": {
"type": "string"
},
"numberOfPages": {
"type": "integer",
"format": "int32"
},
"newSheet": {
"type": "boolean",
"default": true
},
"ntimesUsed": {
"description": "This attachment appended to 'n' documents",
"type": "integer",
"format": "int32"
},
"remarks": {
"type": "string"
}
}
},
"Letter": {
"type": "object",
"required": [
"letterType"
],
"properties": {
"letterType": {
"type": "string",
"enum": [
"LetterData",
"Error"
]
},
"letterData": {
"$ref": "#/definitions/LetterData"
},
"errors": {
"type": "array",
"items": {
"$ref": "#/definitions/Error"
}
}
}
},
"LetterData": {
"type": "object",
"required": [
"recipientAddress",
"price",
"international",
"options"
],
"properties": {
"recipientAddress": {
"type": "string",
"example": "\"Musterfirrna\" \"Max Mustermann\" \"Musterstr. 20\" \"64342 Musterstadt\""
},
"price": {
"$ref": "#/definitions/Price"
},
"international": {
"type": "boolean",
"default": false,
"example": false
},
"options": {
"$ref": "#/definitions/Options"
},
"attributes": {
"type": "array",
"items": {
"$ref": "#/definitions/LetterAttribute"
}
},
"attachments": {
"description": "The Attachments which are appended to this document.\nOnly documents from documentType 'Letter' can have attachments",
"type": "array",
"items": {
"$ref": "#/definitions/Attachment"
}
}
}
},
"SerialLetter": {
"type": "object",
"properties": {
"splitToken": {
"type": "string",
"description": "This token is used to split the serial letter."
},
"splitAfterNumberOfPages": {
"type": "integer",
"format": "int32",
"description": "Every N pages, the serial letter is split."
},
"status": {
"$ref": "#/definitions/SerialLetterStatus"
},
"letters": {
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
}
},
"SerialLetterStatus": {
"type": "object",
"required": [
"nrTotal",
"nrGenerated",
"nrSuccess",
"nrError"
],
"properties": {
"nrTotal": {
"type": "integer",
"format": "int32"
},
"nrGenerated": {
"type": "integer",
"format": "int32"
},
"nrSuccess": {
"type": "integer",
"format": "int32"
},
"nrError": {
"type": "integer",
"format": "int32"
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"text",
"blankText"
],
"properties": {
"code": {
"type": "integer",
"format": "int32",
"description": "Binect error code."
},
"text": {
"type": "string",
"description": "Human readable error text with filled-in place holders."
},
"blankText": {
"type": "string",
"description": "Text with place holders for parameters. Place holders are framed in %-Symbols, e. g. 'error on page number %pageNr% of your document'."
},
"parameters": {
"type": "array",
"description": "Parameters for place holder in 'blankText'.",
"items": {
"$ref": "#/definitions/ErrorParam"
}
},
"errorOnPage": {
"type": "integer",
"format": "int32",
"description": "On which page of the document the error occurred."
}
}
},
"Price": {
"type": "object",
"required": [
"priceBeforeTax",
"priceAfterTax",
"unit",
"taxInPercent"
],
"properties": {
"priceBeforeTax": {
"type": "integer",
"format": "int32"
},
"priceAfterTax": {
"type": "integer",
"format": "int32"
},
"unit": {
"$ref": "#/definitions/CurrencyEnum"
},
"taxInPercent": {
"type": "integer",
"format": "int32",
"description": "e. g. 19 for 19% sales tax"
}
},
"example": {
"priceBeforeTax": 78,
"priceAfterTax": 93,
"unit": "EUROCENT",
"taxInPercent": 19
}
},
"Options": {
"type": "object",
"required": [
"simplex",
"color"
],
"properties": {
"simplex": {
"description": "if false it is duplex",
"type": "boolean"
},
"color": {
"description": "if false it is black and white",
"type": "boolean"
},
"envelope": {
"description": "'DINLANG' is the default envelope.",
"type": "string",
"enum": [
"DINLANG",
"C4"
],
"example": "DINLANG"
},
"dvFranking": {
"description": "if true, DV-Freimachung is mandatory In this case the valdation is more strict ",
"type": "boolean"
}
},
"example": {
"simplex": true,
"color": false,
"envelope": "DINLANG",
"dvFranking": true
}
},
"LetterAttribute": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"example": {
"key": "Key",
"value": "Value"
}
},
"DocumentStatus": {
"type": "object",
"required": [
"id",
"status"
],
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"status": {
"$ref": "#/definitions/Status"
}
}
},
"Status": {
"type": "object",
"required": [
"code",
"text"
],
"properties": {
"code": {
"description": "Following status codes are defined:\n\n 1 (in preparation),\n \n 2 (is shippable),\n \n 3 (in production, waiting to be sent),\n \n 4 (in print process),\n \n 5 (is sent),\n \n 6 (is canceled),\n \n 7 (is erroneous)\n ",
"type": "integer",
"format": "int32"
},
"text": {
"type": "string"
}
},
"example": {
"code": 2,
"text": "is shippable"
}
},
"ResponseFormatEnum": {
"description": "Define the format of the response. Default is FULL.
Use SHORT for direct API response without validation result.
The validation is running afterwards.",
"type": "string",
"enum": [
"FULL",
"SHORT"
],
"default": "FULL",
"example": "FULL"
},
"Account": {
"description": "account data",
"type": "object",
"required": [
"credit",
"unit"
],
"properties": {
"credit": {
"type": "integer",
"format": "int32"
},
"promotionCredit": {
"type": "integer",
"format": "int32"
},
"creditLimit": {
"type": "integer",
"format": "int32"
},
"unit": {
"$ref": "#/definitions/CurrencyEnum"
}
}
},
"ErrorParam": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"Content": {
"description": "The content of the file and file name. The content must be base64 encoded.",
"type": "object",
"required": [
"filename",
"content"
],
"properties": {
"filename": {
"type": "string"
},
"content": {
"type": "string",
"format": "binary"
}
},
"example": {
"filename": "test.pdf",
"content": "BASE64 encoded string"
}
},
"User": {
"description": "The customer's personal data.",
"type": "object",
"required": [
"email"
],
"properties": {
"debitornumber": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"forename": {
"type": "string"
},
"surname": {
"type": "string"
},
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"plz": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"organization": {
"type": "string"
},
"title": {
"type": "string"
},
"phone": {
"type": "string"
},
"partnerId": {
"type": "string"
}
}
},
"Coworker": {
"description": "The coworkers data.",
"type": "object",
"required": [
"email"
],
"properties": {
"debitornumber": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"forename": {
"type": "string"
},
"surname": {
"type": "string"
},
"registrationDate": {
"type": "string",
"format": "date"
},
"numberOfSendings": {
"type": "integer",
"format": "int32"
},
"totalAmount": {
"$ref": "#/definitions/Price"
}
}
},
"CurrencyEnum": {
"type": "string",
"enum": [
"EUROCENT"
]
},
"Address": {
"description": "Adress.",
"type": "object",
"required": [
"name",
"street",
"zipCode",
"city"
],
"properties": {
"name": {
"type": "string"
},
"nameExtend": {
"type": "string"
},
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"zipCode": {
"type": "string"
},
"country": {
"type": "string"
}
}
},
"Invoice": {
"description": "Invoice.",
"type": "object",
"required": [
"id",
"filename"
],
"properties": {
"id": {
"type": "string"
},
"filename": {
"type": "string"
},
"totalAmount": {
"$ref": "#/definitions/Price"
},
"date": {
"type": "string",
"format": "date"
}
}
},
"Transaction": {
"description": "Invoice.",
"type": "object",
"required": [
"id",
"action",
"date"
],
"properties": {
"id": {
"type": "string"
},
"action": {
"$ref": "#/definitions/Action"
},
"date": {
"type": "string",
"format": "date"
},
"documentId": {
"type": "string"
},
"filename": {
"type": "string"
},
"amount": {
"$ref": "#/definitions/Price"
},
"numberOfPages": {
"type": "integer",
"format": "int32"
},
"options": {
"$ref": "#/definitions/Options"
},
"status": {
"$ref": "#/definitions/Status"
},
"coworker": {
"description": "Debitornumber of coworker",
"type": "string"
}
}
},
"Action": {
"description": "Describe an action of a transaction",
"type": "object",
"required": [
"code",
"text"
],
"properties": {
"code": {
"description": "Following action codes are defined:\n\n 1 (is sent),\n \n 2 (is canceled),\n \n 3 (delivery error)\n ",
"type": "integer",
"format": "int32"
},
"text": {
"type": "string"
}
},
"example": {
"code": 1,
"text": "is sent"
}
}
}
}