Knowledge Base

The following API documentation is provided to support system integrators wishing to undertake development to hook PaperCut in with other systems. Reasons for considering integration include:

• Real-time integration with other accounting and/or payment systems.
• Replace the balance in the PaperCut database with a value hosted in another system.
• Allow users to transfer funds from one system to another.
• Integration with stored value cards or campus “one card” solutions.
• Integration with commercial payment POS systems already in place in the organization.

APIs are primarily presented as Web Services approach using XML-RPC as the preferred format. Recently some APIs have been also been exposed in a REST form (JSON and XML). Example code and wrapper classes are provided for many leading programming languages.

These integration options are possible using one of the following options:

Option 1 - Public APIs (Inbound APIs)

These XML web services APIs are included as standard with PaperCut and have no additional costs or certification requirements. They are open, supported and fully documented. For example the APIs can be used to “push” funds (i.e. transfer) from an external source into a PaperCut account. See the Inbound API documentation and the api.adjustUserAccountBalance call for more details. Helper utilities and example source code in C#, Java, Python, PHP and Ruby is provided.

The web services APIs are also available via a command line scripting tool, server-command. This method is ideal for usage from batch files, shell scripts and cron jobs.

All pubic APIs are open, documented and free to use by either PaperCut administrators, system integrators or middleware developers.

Option 2 - Print Scripting API

A popular option for extending PaperCut’s behaviour to implement tasks such as print routing, redirection, print policies, etc. is to use the Print Scripting Feature. Print Scripting offers a rich range of APIs and these can be used to implement many print workflow automation tasks.

Option 3 - User Directory Integration APIs (Advanced)

Organizations wishing to replace PaperCut’s LDAP/AD/eDiretory/OpenDirectory user direction support with a custom user directory provide may do so using a Custom User Information Directory Provider. This takes the form of an external command-line process designed to output data in a prescribed format. More information, including references to example code can be found in Chapter 16 in the PaperCut manual.

Option 4 - Standalone Cash Loader and Kiosk API (Advanced)

There is an advanced internal web services API specially designed for smart cash loading devices such as vending hardware and kiosk stations. This API is only available for PaperCut MF. It offers:

• The ability for the device to register itself with PaperCut.
• The device appears as a “device” in PaperCut offering configuration from the web interface.
• The status of the device can be monitored from PaperCut.
• There is a separate dedicated transaction log and associated reconciliation reports.

Please contact support for details. A small license fee applies to enable this API. All implementations also need to be certified by PaperCut.

Option 5 - Vending API in the Release Station and/or Pay Station (Advanced)

This API is targeted at simple cash or stored value card equipment that can connect to a computer via a USB or serial cable. It allows vendors to connect their devices as funds sources into the PaperCut for:

• Pay and Release: Users can pay cash and release jobs at a release station.
• Pay Station: Users can put funds into PaperCut using the release station software running in Pay Station mode.

An overview of the pay/release station software (including screenshots) is provided in the PaperCut MF tour section Cash Payment Hardware.

Documentation for this API is distributed with PaperCut MF, and can be found at [app-path]/release/examples/extensions/credit-sources/, including a readme file, API documentation and some mock implementations. These should provide enough information for a developer to start implementing the integration.

For further details contact support. Customers using devices that integrate via this API will need to be running PaperCut MF and purchase a Pay Station license for each device. All implementations also need to be certified by PaperCut.

Option 6 - Copier Terminal and Controller API

There is an advanced internal web services API specially designed for smart hardware copier terminal devices (copier controls) that can track and/or restrict copying, allowing copies to be reported to PaperCut for tracking and charging. This API is only available for PaperCut MF. It offers:

• The ability for the device to register itself with PaperCut.
• The device appears as a “device” in PaperCut offering configuration from the web interface.
• The status of the device can be monitored from PaperCut.
• There is a separate dedicated job log showing jobs tracked by the device.

Please contact support to discuss the API access, development licenses, and functional requirements. Each site using the implementation must pay a small license fee applies to enable the APIs (a Copier Controller Terminal License). All implementations also need to complete a set of test cases to be certified by PaperCut and vendors are required to offer quality assurance commitments (to ensure compatibility is maintained over time).

Option 7 - Device REST API (for Device SSO)

This API allows 3rd party applications to query PaperCut for the list of connected external devices (e.g. MFPs running embedded software, hardware terminals, etc). This API allows the callers to determine the user logged into the device. This can be used for Single Sign-on for other 3rd party applications (e.g. embedded scan applications).

Option 8 - Outbound External Account API (Advanced)

This API set allows 3rd party system integrators to develop interfaces to instruct PaperCut to use an external source for account balances (i.e. replace the balance in the PaperCut database with a value hosted in another system in real-time). This feature/setting is also known as an External Account Source. These documents cover the Outbound API set and should be read in conjunction with the standard Inbound Web Services APIs discussed in detail in the PaperCut Public API documentation.

IMPORTANT: Before starting you should discuss your options with the PaperCut development team. End-users must pay a small license fee to enable support for leveraging an external account source. All implementations also need to be certified (because if your implementation is buggy, you’ll take down PaperCut!)

Outbound APIs are a complex topic! The PaperCut Software Development Team is happy to answer any questions and/or work with system integrators to find the best solutions. Implementers should take considerable care in development and integration as implementations effectively replace PaperCut’s database so any failures will extend through all layers of the system.

Option 9 - Intranet integration via gadgets/widgets and AJAX

A simple set of AJAX widgets and JSON based REST APIs are avaliable to assist with basic Intranet integration. See:

Option 10 - Hold/Release Queue and Release Station API

A rarely used API, this can be used to list, release and cancel/delete print jobs from hold/release queues, in addition to basic user authentication.

Certification

Several of the APIs above make reference to the certification process. This is explained here. Details are also available regarding PaperCut’s Certified Integration Technology program, for certifying solutions that integrate with PaperCut.

See also

• Looking up card numbers in an external database
• Adding the PaperCut Web Widgets in Moodle

Categories: APIs

Keywords: PaperCut integration, vending API, XML-RPC, SOAP, DLL, middleware, external account source

Comments

Share your findings and experience with other PaperCut users. Feel free to add comments and suggestions about this Knowledge Base article. Please don't use this for support requests.