Philosophie Funktionen Schnittstellen Preismodell Login EN
General
Introduction Authentication Data Structure
Sales
Orders Products Components
Print data management
Introduction Print Data File Print Data Erratum
Master data management
Customers
Accounting
Introduction Customer Invoices Reversal Invoices Supplier Invoices Addresses Contacts Line items

Introduction

We've organised the Keyline API to be RESTful. That means you'll get predictable responses on your HTTP requests.

The facts

  • Keyline is build for use in any language or framework.
  • You'll receive all responses in JSON.

Authentication

In order to secure your data, Keyline requires API users to authenticate before they can access any information. This is done by supplying an API access token in the HTTP header with every request that you make.

Be sure to keep access tokens secret. With great power comes great responsibility!

Authorization header

To gain API access you must supply an HTTP header with the name "Authorization" and the contents "Bearer your access token", like so: 

curl -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"

HTTP/1.1 200 OK

If you didn't send any token, your access token is wrong or you're not allowed to access the requested resource, you'll get

HTTP/1.1 401 Unauthorized

Token administration

You can add or revoke access tokens in Keyline in the Settings > API section.

Data Structures & Status Codes

Common Requirements for API Requests

All requests should set the following headers

Accept application/json

Concepts related to Responses

Attributes Common to all Objects

Every object returned by the Keyline API always has the following attributes. So in order to simplify the overall documentation, we list those common attributes here instead of adding them to each object's documentation.

id integer The Keyline internal ID of the invoice
created_at datetime The date and time when the invoice was created
updated_at datetime The date and time when the invoice was last modified

Types Used throughout the API

The Keyline API at some places encodes certain types with some meta-information. In order to simplify the documentation and make it easier to read, those types, that are used across multiple objects, are listed below.
Money

Whenever an attribute in Keyline denotes a money value, such as the net total price of an invoice, it is encoded with the type Money, and contains the following meta-information.

cent_amount integer The amount in cents of the money value.
currency string The ISO code for the currency of the cent_amount field
Tax
cent_amount decimal The amount in cents of the money value. Esp. line items can have prices with cent fractions, so this amount is encoded as a decimal.
currency string The ISO code for the currency of the cent_amount field
rate float The tax rate percentage, formatted as a float number, such as that 0.19 translates to a tax rate of 19%

Response Paging

Responses to GET requests that hit index endpoints, such as /api/v1/customers will at most get back a result set of size 100. If the total size of the desired result set exceeds 100, multiple requests need to be made.

If a response's result set was paged, the response headers contain the following extra headers:

X-Keyline-Result-Page Gives the page number of the current returned result subset
X-Keyline-Result-Per-Page Gives the maximum size of the current returned result subset. Is always 100.
X-Keyline-Result-Total Gives the total number of results across all pages.

If a client wants to fetch a page number different from the first, it must specify the parameter page as a query parameter, where page is always an integer, and the lowest page number is always 1.

Status Codes

The Keyline API uses standardised HTTP response codes the inform the caller about the status of any requests.

These are the most common codes you'll get to see:

200 OK Everything is okay
201 Created You just created a new resource
204 No Content The update or delete operation you just ran was successful
400 Bad request The request you made is missing required parameters and cannot be executed
401 Unauthorized You're not allowed to access this resource. Check your access token
404 Not found You tried to access a resource that doesn't exist
422 Unprocessable Entity The validation of the resource you wanted to create or change failed. The JSON will contain a detailed error description
500 Internal Server Error Yikes! This is pretty bad and might be our fault. If you encounter one of these, we are automatically informed, but please contact us with some in-depth infos.

Missing parameters (HTTP 400)

Create and update request have certain requirements regarding the parameters you must submit in order the execute the request. A line item change request for example needs the order information as parameter. If you do not supply this, you will get the following error: 

$ curl -X POST https://api.keyline-mis.com/api/v1/orders/434333

HTTP/1.1 400 Bad Request
{
  "error_description": "A required parameter for this request was not supplied",
  "missing_parameters": ["order"]
}

Validation errors (HTTP 422)

If the creation or alteration of a resource failed because some validation criteria were not met, you will get a HTTP response with the status code 422 which contains error information just like in the following example: 

$ curl -X POST -d "order[reference]=Piece" https://api.keyline-mis.com/api/v1/orders/434333

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "reference": ["cannot be changed"]
  }
}

Sales

Orders

This endpoint allows you to create, update and delete orders inside Keyline.

Attributes you send to Keyline

due_at datetime The date and time when the order is due

Attributes Keyline sends back to you

id integer The ID of the order that was just created
printery_id integer The ID of your printery
customer_id integer The ID of the customer
creator_id integer The ID of the creator
brand_id integer The ID of the brand
reference string The reference of the order
due_at datetime The date and time when the order is due
created_at datetime The date and time when the order was created
updated_at datetime The date and time when the order was last modified

Actions

Creating an order

POST
/api/v1/orders

Example request

$ curl -X POST -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"order": {
       "due_at": "2016-06-21T08:20:54.760+02:00"
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123"
View example response View example error response

Updating an order

PATCH
/api/v1/orders/{ORDER_ID}

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"order": {
       "due_at": "2016-06-20T09:16:57.495+02:00"
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123"
View example response View example error response

Deleting an order

DELETE
/api/v1/invoices/{ORDER_ID}

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
"https://api.keyline-mis.com/api/v1/orders/123"
View example response View example error response

Products

This endpoint allows you to create, update and delete products inside Keyline.

Attributes you send to Keyline

name string The name of the product
kind string The kind of the product, the value has to be one of the following:
brochure, book, business_card, sticker, pad, pages, couvert, custom
custom_description string The custom description of the product

Attributes Keyline sends back to you

id integer The ID of the product that was just created
order_id integer The ID of the associated order
state integer The state of the product
reference integer The reference of the product
name integer The name of the product
custom_description string The customs description of the product
costs datetime The costs of the product
kind datetime The kind of the product
print_externally boolean true if print externally
cleared_for_production_at datetime The date and time when the product was cleared for production
created_at datetime The date and time when the product was last modified
updated_at datetime The date and time when the product was last modified

Actions

Creating a product

POST
/api/v1/orders/{ORDER_ID}/products

Example request

$ curl -X POST -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{ "product": {
        "name": "Broschüre (Rückendrahtheftung)",
        "kind": "brochure"
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123/products"
View example response View example error response

Updating a product

PATCH
/api/v1/orders/{ORDER_ID}/products/{PRODUCT_ID}

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"product": {
      "custom_description": "Rückendrahtheftung"
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123/products/1"
View example response View example error response

Deleting a product

DELETE
/api/v1/invoices/{ORDER_ID}/products/{PRODUCT_ID}

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
"https://api.keyline-mis.com/api/v1/orders/123/products/1"
View example response View example error response

Product components

This endpoint allows you to create, update and delete product components inside Keyline.

Attributes you send to Keyline

name string The name of the component
number_of_pages string The number of pages
production_method string The production method, the value has to be one of the following:
offset, digital
page_arrangement string The page arrangement, the value has to be one of the following:
standalone, parallel, crossover, standalone_single_motive,
parallel_single_motive, crossover_single_motive
paper string The type of paper, the value has to be one of your stock papers
closed_dimensions array [integer] The closed dimensions
front_colors array [string] The front colors, the value has to be one or more of our predefined colors
or your stock colors
back_colors array [string] The back colors, the value has to be one or more of our predefined colors
or your stock colors

Attributes Keyline sends back to you

id integer The ID of the product component that was just created
name integer The name of the component
number_of_pages integer The number of pages
closed_dimensions array [integer] The closed dimensions
production_method integer The production method
page_arrangement string The page arrangement
front_colors array [string] The front colors
back_colors array [string] The back colors
paper object The associated paper object
sheets object The associated sheet objects

Actions

Creating a product

POST
/api/v1/orders/{ORDER_ID}/products/{PRODUCT_ID}/components

Example request

$ curl -X POST -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{ "component": {
        "name": "Keyline Cover",
        "number_of_pages": "2",
        "production_method": "offset",
        "page_arrangement": "standalone",
        "paper": "INASET PLUS matt holzfrei weiß, 70g, 430.0mm×610.0mm (Schmalbahn)",
        "closed_dimensions": [210, 297],
        "front_colors": ["CMYK/Cyan", "CMYK/Magenta", "CMYK/Yellow", "CMYK/Black"],
        "back_colors": ["Pantone/439"]
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123/products/1/components"
View example response View example error response

Updating a product

PATCH
/api/v1/orders/{ORDER_ID}/products/{PRODUCT_ID}/components/{COMPONENT_ID}

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"product": {
      "custom_description": "Rückendrahtheftung"
      }
    }'
"https://api.keyline-mis.com/api/v1/orders/123/products/1/components/1"
View example response View example error response

Deleting a product

DELETE
/api/v1/invoices/{ORDER_ID}/products/{PRODUCT_ID}/components/{COMPONENT_ID}

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
"https://api.keyline-mis.com/api/v1/orders/123/products/1/components/1"
View example response View example error response

Print data management

Keyline as an overseeing MIS does not interact with any print data files ("the PDF") directly. However, in order to orchestrate the processes of a printery, Keyline stores meta-data about the print data files and can trigger events based on this meta-data. This can be used to ease communication between different tools during the PDF processing and preflight.

Goals of Keyline's Print Data Management

Streamlining Processes & Connecting Tools

Keyline is the central location of all production-relevant data for any print product, and enables streamlining of many more processes of a printery. It does this, among other things, by

  • Providing a central storage for meta-data of print data files (such as file locations and sizes) and their processing
  • Pass meta-data between various print data processing tools
  • Trigger workflows with print data processing tools after certain events

Tracking Status & Informing Users

However print data management in Keyline not only enables process streamlining, but also informing users about the status of production of any print product, by

  • Tracking the progress of print data file processing and display this inside the Keyline UI
  • Providing users with links in the UI for quick access to print data files
  • Communicate print data file problems (called errata) inside Keyline's UI
  • Providing a comprehensive overview of a print product's production, incl. preflight and print data preprocessing

Metadata storage

Usually there are several tools involved in the processing of print data. However those tools don't integrate well with each other and data between those tools needs to be transferred manually. Keyline provides you with a key/value store for each print data file, that accepts almost any data you provide. With this mechanism you can use Keyline as the primary source of meta-data during preflight and processing tasks, instead of generating and moving XML or other files around.

Progress tracking

Keyline not only allows you to store print data file information, but also encourages you to store information about the state of these files. For example, during processing of an original file during which processed files will be created, we recommend that you create the objects for these processed files right away and continuously update their progress and state via the Keyline API. Keyline can then provide the user with this information, allowing her to view all critical information in one place, no matter the underlying PDF processing tool.

Problem tracking

Through print data errata, Keyline allows you to track problems during print data processing down to the page level. If you use the Keyline API to store such information you allow the user to easily view problems and devise rescue strategies. This information can also be consumed by proofing portals or mailed to a client.

These endpoints allow you to create, read, update and delete print data files.

The types of print data files

In order to cover the entire processing and preflight of PDF print data, Keyline separates print data files into three categories:

  • Original files are such files that a client uploaded to a given location (could be a web-shop API, etc). After the upload the responsible software component can tell Keyline via the API that an upload occurred and have Keyline trigger further processing steps.
  • Processed files are such files that have been created by the print data PDF tools. This files can also be connected to a product's component (we recommend to always split print data files on a component-basis).
  • Imposed files are such files that are ready for print and already have the layout for a specific sheet that is attached to a print product in Keyline.

Attributes of a Print Data File object

id integer The ID of the print data file
product_id integer The ID of the associated product which owns this print data file
component_id integer The ID of the assoicated component this print data file refers to (when the file is of kind "processed")
sheet_id integer The ID of the assoicated sheet this print data file refers to (when the file is of kind "imposed")
uri string The full URI of this print data file, including the protocol
filesize integer The size of this print data file in bytes
kind string The kind of this print data file, one of "original", "processed", "imposed"
state string The state of this print data file, one of "newly_uploaded", "processing", "processed"
progress float The progress of the current processing, as percentage between 0 and 1
first_page integer The first page inside the print data file's PDF
last_page integer The last page inside the print data file's PDF
created_at datetime The date and time when the product was last modified
updated_at datetime The date and time when the product was last modified

Parameters

All of the below actions, expect the GET operations, expect a JSON document in the request body with the following attributes. Attributes that are marked as optional, can be omitted from the JSON document.

uri string The full URI, including the protocol under which the print data file can be retrieved. Note that this URI needs to be accessible to the Keyline user and all components involved in print data processing, but not to Keyline itself. Valid protocols are: http, https ftp, sftp, smb, and afp.
filesize integer The file size on disk of the print data file in bytes
state string The state of this print data file's processing. Since we want to give the user feedback about processing in the Keyline UI, the object should be created when processing starts and then continously updated (see also progress). Valid values are: newly_uploaded, processing, processed
kind string The kind of this print data file.
Use original if the file was uploaded by the user and not touched by processing.
Use processed when the file was created by the processing tools, in this case, Keyline expects the file's content to match a component, so a valid component_id must also be supplied.
Use imposed when this file contains the final imposed PDF data, in this case a sheet_id must be supplied, and a component_id cannot be supplied.
first_page integer The page number of the first page this print data file referes to
last_page integer The page number of the last page this print data file referes to
progress float The progress of processing to show in the Keyline UI. Must be a number between 0 and 1, should be continously updated during processing

Actions

Retrieve a List of all Print Data File objects

GET
/api/v1/products/{product_id}/print_data_files

Example request

$ curl -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
-H "Content-Type: application/json" \
https://api.keyline-mis.com/api/v1/products/8557/print_data_files
View example response

Retrieve a Print Data File object

GET
/api/v1/products/{product_id}/print_data_files/{print_data_file_id}

Example request

$ curl -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
-H "Content-Type: application/json" \
https://api.keyline-mis.com/api/v1/products/8557/print_data_files/1
View example response

Create a Print Data File object

POST
/api/v1/products/{product_id}/print_data_files

Example request

$ curl -X POST -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
-H "Content-Type: application/json" \
-d '{
      "print_data_file": {
        "filesize": "1234",
        "kind": "original",
        "state": "newly_uploaded",
        "uri": "smb://data_files/to_process/file1.pdf"
      }
    }'
https://api.keyline-mis.com/api/v1/products/8557/print_data_files
View example response

Update a Print Data File object

PATCH
/api/v1/products/{product_id}/print_data_files/{print_data_file_id}

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
-H "Content-Type: application/json" \
-d '{
      "print_data_file": {
        "filesize": "12345678",
        "state": "processed",
      }
    }'
https://api.keyline-mis.com/api/v1/products/8557/print_data_files/1
View example response

Delete a Print Data File object

DELETE
/api/v1/products/{product_id}/print_data_files/{print_data_file_id}

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
-H "Content-Type: application/json" \
https://api.keyline-mis.com/api/v1/products/8557/print_data_files/1
View example response

This endpoint allows you to create, update and delete print data errata. Print data errata are status messages which pop up during processing of print data files. These errata will be shown in the user interface of Keyline and can be used as the basis for proofing decisions. Errata can be related to a single page inside a print data file PDF or can relate to an entire print data file.

Attributes you send to Keyline

code string The problem/error/information code that describes the problem that occured best. Allowed values are: "color_mismatch", "other" (more to follow)
message text The full erratum description generated by the underlying processing tool
severity string The severity of the encountered erratum. Allowed values are: "info", "warning", "error"
page_number integer The page number inside the print data file PDF where this erratum was encountered. This is optional and should always be used for page-specific errata, however, some errors like "PDF format is incorrect" apply to the entire file and thus this field should remain unset

Attributes Keyline sends back to you

id integer The ID of the print data erratum
print_data_file_id integer The ID of the associated print data file id which owns this print data erratum
code string The computer-readable error code of this erratum
message text The full error message as originally generated by the PDF processing tool
severity string The severitiy of this erratum, one of "info", "warning", "error"
page_number integer The number of the page where this erratum was encountered. If the erratum applies to the entire print data file this filed will be empty
created_at datetime The date and time when the product was last modified
updated_at datetime The date and time when the product was last modified

Master data management

Customers

Customers within Keyline are usually companies, the clients of the printery, for which they produce printed products. Because of this central role, they occupy in Keyline, the API for now only allows to list and fetch customers, and does not provide any means for creating and changing customers.

Attributes of a Customer Object

name string The customer's name, usually a company name
reference string A Keyline-generated 6-character reference for the customer
tax_identifier string The customer's VAT ID
number string Optional customer id, that might be specified by the printery

Actions

Listing Customers

GET
/api/v1/customers

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customers
View example response View example error response

Fetching a Single Customer

GET
/api/v1/customers/{customer_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customers/1666
View example response View example error response

Accounting

Introduction to Invoices in Keyline

Keyline knows about different kinds of invoices.

The most prevalent type are customer invoices which are invoices, that a printery sends to it's customers in order to bill them for products they manufactured as part of an order.

The usual workflow when interacting with customer and supplier invoices is, they get created, eventually updated. As soon as they're deemed final from an accounting perspective, they are either marked as 'billed' (in case of customer invoices) or 'checked' (in case of supplier invoices). Once invoices are either 'billed' or 'checked' they can't be changed or deleted anymore. Customer Invoices however, can be reversed, which effectively creates a negated version of the respective customer invoice.

All invoices types share certain fields and characteristics. Most important of these commonalities is that theu all have line items. Customer and Reversal Invoices also both have contacts and addresses.

Important: Please note that the current version of the API is not suited to create invoices that are based on orders. Currently, the preferred way to do this, is still via the Web UI of Keyline.
If you want to do this via the API, then please reach out to us.

Customer Invoices

Introduction

A customer invoice is usually an invoice that's a consequence of an order and as such is related to an order. However, Keyline also allows creating and therefore tracking invoices totally unrelated to an order and with arbitrary line items.

Lifecycle of a Customer Invoice

The most common way to interact with the customer_invoices endpoints, is to

  • create a record with a POST request
  • extract id attribute of the created customer invoice.
  • attach line_items to the invoice by way of issuing POST requests to the line_items resources of the invoice
  • declare the customer invoice as billed and therefore not editable anymore by setting the billed_at field to a valid date.

Additionally any customer invoice can be reverted at any point in time, resulting in the creation of a reversal invoice.

Attributes of a Customer Invoice object

address Object The invoicing address
billed_at datetime The date and time the invoice was billed to the customer
business_unit_id integer ID of the business unit this invoice belongs to
contact Object The number of the invoice
custom_references Object Key-value pairs custom to this invoice
custom_text text A custom free-form text that is added to the invoice.
customer_id integer ID of the customer this invoice belongs to.
due_at date The due date of the invoice
gross_total Money The gross total amount of the invoice
line_items line_item[] Array of line_item objects
net_total Money The net total amount of the invoice
number string The number of the invoice
order_id integer ID of the order this invoice belongs to. If this invoice is not associated with an order, this field is null
paid_at date The date the invoice was paid by the customer
reversal_invoice_id integer If this invoices was reversed, this field contains the ID of the reversal invoice, otherwise this field is null.
sent_at date Date when the invoice was sent to the customer
taxes Tax[] All taxes of the invoice, where the keys are the tax rates and the values are accrued amounts of all line items with the respective tax rate

Attributes that you can set via the API

The only mandatory attribute, when creating a customer invoice, is the customer_id.
Otherwise any combination of the below attributes can be provided to the POST and PATCH actions, to create or update a customer invoice, with a minimum of one attribute.

billed_at datetime The date and time when the invoice was or is billed to the customer. Once this date is set, the invoice is considered 'invoiced' and therefore final from an accounting perspective and can't be changed anymore.
business_unit_id integer ID of the business unit this invoice should belong to
customer_id integer ID of the customer this invoice should belong to
custom_text string A custom free-form text that is added to the invoice
due_at date The date and time when the invoice is due for payment
paid_at date The date the invoice was paid by the customer
sent_at date Date when the invoice was sent to the customer

Actions

Listing Customer Invoices

GET
/api/v1/customer_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices
View example response View example error response

Fetch a Single Customer Invoice

GET
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3689
View example response View example error response

Creating a Customer invoice

The only must-have attribute when creating a customer invoice is the customer_id.

POST
/api/v1/customer_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "customer_invoice": {
          "due_at": "2017-03-15",
          "customer_id": 1398
        }
      }
  '
  https://api.keyline-mis.com/api/v1/customer_invoices
View example response View example error response

Update a Customer invoice

All fields, except the customer_id, of a Customer invoices can be updated as long as billed_at is null. When trying to update an already billed customer invoice, the response's status code will be 422.

PATCH
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "customer_invoice": {
          "due_at": "2017-03-25",
          "custom_text": "This invoice can be payed later"
        }
      }
  '
  https://api.keyline-mis.com/api/v1/customer_invoices/3067
View example response View example error response

Delete a Customer Invoice

Customer invoices can be deleted as long as billed_at is null. When trying to delete an already billed customer invoice, the response's status code will be 422.

DELETE
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X DELETE \
  https://api.keyline-mis.com/api/v1/customer_invoices/3067
View example response View example error response

Reverse a Customer Invoice

Billed Customer Invoices can be reversed, that is a reversal invoice is created, which is a negation of the original customer invoice in all relevant aspects.

See the documentation about reversal invoices for more details.

POST
/api/v1/customer_invoices/{customer_invoice_id}/reverse

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3688/reverse
View example response View example error response

Reversal Invoices

Introduction

Reversal invoices share a lot of characteristics with customer invoices, and differ mostly in minor ways. Most important and stark difference is, that a reversal invoice is marked as billed, as soon as it's created. Which means, that reversal invoices cannot be changed, once they're created.
Therefore besides the endpoint for creating reversal invoices there are only endpoints for listing and reading reversal invoices.

Attributes of a Reversal Invoice object

address Object The invoicing address
billed_at datetime The date and time the invoice was billed to the customer.
business_unit_id integer ID of the business unit this invoice belongs to
contact Object The number of the invoice
custom_references Object Key-value pairs custom to this invoice
custom_text text A custom free-form text that is added to the invoice.
customer_id integer ID of the customer this invoice belongs to.
due_at date The due date of the invoice
gross_total Money The gross total amount of the invoice
line_items line_item[] Array of line_item objects
net_total Money The net total amount of the invoice
number string The number of the invoice
order_id integer ID of the order this invoice belongs to. If this invoice is not associated with an order, this field is null.
paid_at date The date the invoice was paid by the customer
reversed_invoice_id integer The ID of the customer invoice , which is reversed by this reversal invoice.
sent_at date Date when the invoice was sent to the customer
taxes Tax[] All taxes of the invoice, where the keys are the tax rates and the values are accrued amounts of all line items with the respective tax rate

Actions

Listing Reversal Invoices

GET
/api/v1/reversal_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/reversal_invoices
View example response View example error response

Fetch a Single Reversal Invoice

GET
/api/v1/reversal_invoices/{reversal_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/reversal_invoices/3689
View example response View example error response

Creating a Reversal invoice

See the documentation for customer invoices on how to create reversal invoices.

Supplier Invoices

Introduction

A supplier invoice is an invoice, that your printery has received from one of it's suppliers, and which you want to track with Keyline. Tracking supplier invoices with Keyline, allows you to associate material orders, which might get triggered by customer orders, to supplier invoices, which in turn allows for full tracking of all costs that are associated with an order and it's associated products.

Lifecycle of a Supplier Invoice

The most common way to interact with the supplier_invoices endpoints, is to

  • create a record with a POST request
  • extract id attribute of the created supplier invoice.
  • attach line_items to the invoice by way of issuing POST requests to the line_items resources of the invoice
  • declare the supplier invoice as checked and therefore not editable anymore by setting the checked_at field to a valid date.

Supplier invoices can be created and updated with any combination of the below listed attributes, as long as at least one attribute is specified. A supplier invoice is not editable anymore as soon as the checked_at attribute is set. Once this is the case, the PATCH and DELETE actions will return a 403 status code.

Note, that supplier invoices are different from customer invoices in many respects. Most important is, the significance of the billed_at field. While customer invoices can't be changed once billed_at is set to a date, the same is not true for supplier invoices.

Attributes of a Supplier Invoice object

billed_at datetime The date and time when the invoice was billed
checked_at datetime The date and time when the invoice was checked. Once this date is set, the invoice can't be changed anymore.
custom_text string A custom free-form text that has been set for this invoice
due_at date The due date of the invoice
gross_total Money The gross total amount of the invoice
line_items line_item[] Array of line_item objects
net_total Money The net total amount of the invoice
number string The number of the invoice
order_id integer The ID of the associated order
paid_at date The date when the invoice was paid
supplier_id integer The ID of the associated supplier
taxes Tax[] All taxes of the invoice, where the keys are the tax rates and the values are accrued amounts of all line items with the respective tax rate

Attributes you send to Keyline to Create or Update a Supplier Invoice

The only mandatory attribute, when creating a supplier invoice, is the supplier_id.
Otherwise and as mentioned above, any combination of attributes can be provided to the POST and PATCH actions, to create or update a supplier invoice, with a minimum of one attribute.

billed_at datetime The date and time when the invoice was billed
checked_at datetime The date and time when the invoice was checked. Once this date is set, the invoice can't be changed anymore.
custom_text string A custom free-form text that has been set for this invoice
due_at date The due date of the invoice
number string The number of the invoice
order_id integer The ID of the associated order
paid_at date The date when the invoice was paid
supplier_id integer The ID of the associated supplier

Actions

Listing Supplier Invoices

GET
/api/v1/supplier_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/supplier_invoices
View example response View example error response

Fetch a Single Supplier Invoice

GET
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/supplier_invoices/3059
View example response View example error response

Creating a Supplier invoice

The only must-have attribute when creating a supplier invoice is the supplier_id.

POST
/api/v1/supplier_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "supplier_invoice": {
          "billed_at": "2017-02-21",
          "due_at": "2017-03-15",
          "number": "13-XC 456",
          "supplier_id": 36
        }
      }
  '
  https://api.keyline-mis.com/api/v1/supplier_invoices
View example response View example error response

Update a Supplier invoice

Supplier invoices can be updated as long as checked_at is null. When trying to update an already checked supplier invoice, the response's status code will be 422.

PATCH
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "supplier_invoice": {
          "due_at": "2017-03-25",
          "custom_text": "This invoice can be payed later"
        }
      }
  '
  https://api.keyline-mis.com/api/v1/supplier_invoices/3067
View example response View example error response

Delete a Supplier invoice

Supplier invoices can be deleted as long as checked_at is null. When trying to delete an already checked supplier invoice, the response's status code will be 422.

DELETE
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X DELETE \
  https://api.keyline-mis.com/api/v1/supplier_invoices/3067
View example response View example error response

Invoice Addresses

This endpoint allows you to create, update and delete addresses that belong to customer invoices and to list and fetch addresses that belong to reversal invoices.

Addresses only exist in the context of a specific invoice. So whenever you want to list or interact with the addresses for an invoice, you have to keep the type of invoice in mind and construct the endpoint's path from there. When referring to an endpoint's path below, whenever there's a {invoice_path}/address, you have to adapt the path to the type of invoice you're dealing with. For example the path to listing the address for a customer invoice is /api/v1/customer_invoices/{customer_invoice_id}/address while the respective path for a reversal invoice is /api/v1/reversal_invoices/{reversal_invoice_id}/address.

Attributes of an Address

addressable_type integer The address type
addressee string The addressee, which usually holds the name and lastname of the entity being addressed
street string The street name of the address
number string The number of the address
addition string The address addition
zip_code string The zip code of the address
town string The town of the address
country_code string The ISO country code of the address
state_or_province string The state or province of the address

Attributes you send to Keyline to Create or Update an Address

addressee string The addressee
street string The street name of the address
number string The number of the address
addition string The address addition
zip_code string The zip code of the address
town string The town of the address
country_code string The country code of the address
state_or_province string The state or province of the address

Actions

Creating an invoice address

An address can be created for invoices as long as the customer invoice is not billed yet.

POST
{invoice_path}/address

Example request

$ curl -i -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
  -H "Content-Type: application/json"\
  -X POST \
  -d '{"address": {
        "addressee": "Mustermann GmbH",
        "street": "Musterstraße",
        "number": "12",
        "addition": "Floor 1",
        "zip_code": "12345",
        "town": "Musterstadt",
        "country_code": "DE"
        }
      }'
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/address
View example response View example error response

Updating an invoice address

An address can be updated for invoices as long as the customer invoice is not billed yet.

PATCH
/api/v1/invoices/{INVOICE_ID}/address

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"address": { "number": "24" } }'
https://api.keyline-mis.com/api/v1/customer_invoices/3609/address
View example response View example error response

Deleting an invoice address

An address can be deleted for invoices as long as the customer invoice is not billed yet.

DELETE
{invoice_path}/address

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
https://api.keyline-mis.com/api/v1/customer_invoices/3609/address
View example response View example error response

Invoice Contacts

This endpoint allows you to create, update and delete contacts that belong to customer invoices and to list contacts that belong to reversal invoices.

Contacts only exist in the context of a specific invoice. So whenever you want to list or interact with the contact for an invoice, you have to keep the type of invoice in mind and construct the endpoint's path from there. When referring to an endpoint's path below, whenever there's a {invoice_path}/contact, you have to adapt the path to the type of invoice you're dealing with. For example the path to listing the contact for a customer invoice is /api/v1/customer_invoices/{customer_invoice_id}/contact while the respective path for a reversal invoice is /api/v1/reversal_invoices/{reversal_invoice_id}/contact.

Attributes of an Contact

title string The salutation of the contact
first_name string The first name of the invoice's contact
name string The name of the invoice's contact
email string The contact's email address
phone string The contact's phone number in international format, such as +4912345123
fax string The contact's fax number in international format, such as +4912345123
mobile string The contact's fax number in international format, such as +4912345123
debitor identifier string

Attributes you send to Keyline to Create or Update a Contact

title string The salutation of the contact
first_name string The first name of the invoice's contact
name string The name of the invoice's contact
email string The contact's email address
phone string The contact's phone number in international format, such as +4912345123
fax string The contact's fax number in international format, such as +4912345123
mobile string The contact's fax number in international format, such as +4912345123
debitor identifier string

Actions

Creating an Invoice's Contact

A contact can be created for invoices as long as the customer invoice is not billed yet.

POST
{invoice_path}/contact

Example request

$ curl -i -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
  -H "Content-Type: application/json"\
  -X POST \
  -d '{"contact": {
        "title": "Herr",
        "first_name": "Max",
        "name": "Mustermann",
        "email": "email@example.com",
        "phone": "+49123124"
      } }'
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/contact
View example response View example error response

Updating an Invoice's Contact

A contact can be updated for invoices as long as the customer invoice is not billed yet.

PATCH
{invoice_path}/contact

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
  -H "Content-Type: application/json"\
  -d '{"contact": { "title": "Frau", "first_name": "Maxine" } }'
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/contact
View example response View example error response

Deleting an Invoice's Contact

A contact can be delted for invoices as long as the customer invoice is not billed yet.

DELETE
{invoice_path}/contact

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
  -H "Content-Type: application/json"\
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/contact
View example response View example error response

Invoice Line Items

This endpoint allows you to create, update and delete line items that belong to customer invoices or supplier invoices.

Line items only exist in the context of a specific invoice. So whenever you want to list or interact the line items for an invoice, you have to keep the type of invoice in mind and construct the endpoint's path from there. When referring to an endpoint's path below, whenever there's a {invoice_path}/line_items, you have to adapt the path to the type of invoice you're dealing with. For example the path to listing line items for a customer invoice is /api/v1/customer_invoices/{customer_invoice_id}/line_items while the respective path for a supplier invoice is /api/v1/supplier_invoices/{supplier_invoice_id}/line_items.

Attributes of a Line Item

accounting category Object The name and number of the accounting category that has been assigned to this line item
description string The line item description
discount decimal Discount rate that applies to this line item's price. This means this field is to be interpreted as a percentage, but formatted as a decimal number.
discounted_net_total Money The discounted net price of this line item, which is calculated by reducing the line item's net_total by the discount.
gross_total Money The gross total amount of the line item
net Money The net price of one unit of this line item
net_total Money The net total amount of all units of this line item
order_number string The order number of this line item, a free-form text.
qty integer The line item quantity
tax Tax The line item tax amount
unit string The line item unit

Attributes you send to Keyline to Create or Update a Line Item

description string The line item description
qty integer The line item quantity
unit string The line item unit, a free-form string. Keyline internally works with the following units, so if you use them, they will be recognized by the Web UI of Keyline.
pdf piece, plate, sheet, folded_sheet, meter, sqmeter, sqmillimeter, millimeter, liter, milliliter, gram, kilogram, ream
net decimal The line item net price in cents
tax_rate decimal The line item tax rate, the value has to be one of the following: 0.0, 0.07 or 0.19

Actions

Listing an Invoice's Line Items

GET
{invoice_path}/line_items

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/line_items

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/supplier_invoices/3607/line_items
View example response View example error response

Fetching a single Invoice's Line Item

GET
{invoice_path}/line_items/{line_item_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3609/line_items/4923
View example response View example error response

Creating an Invoice Line Item

Line Items can be created for invoices as long as the invoice is not billed or checked yet.

POST
{invoice_path}/line_items

Example request

$ curl -X POST -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"line_item": {
       "description": "printing ink",
       "qty": 3,
       "unit": "drum",
       "net": 2.5,
       "tax_rate": 0.19}
       }'
"https://api.keyline-mis.com/api/v1/customer_invoices/123/line_items"
View example response View example error response

Updating an invoice line item

Line Items can be updated as long as the invoice is not billed or checked yet.

PATCH
{invoice_path}/line_items/{line_item_id}

Example request

$ curl -X PATCH -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
-d '{"line_item": { "qty": 10 }'
https://api.keyline-mis.com/api/v1/customer_invoices/3609/line_items/4923
View example response View example error response

Deleting an invoice line item

Line Items can be deleted as long as the invoice is not billed or checked yet.

DELETE
{invoice_path}/line_items/{line_item_id}

Example request

$ curl -X DELETE -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f"\
-H "Content-Type: application/json"\
https://api.keyline-mis.com/api/v1/customer_invoices/3609/line_items/4923
View example response View example error response