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 - 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 the Custom User Information Directory Provider API. 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 3 - 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 avaliable 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 4 - 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 5 - Copier Terminal/Controller and 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 avaliable 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 6 - 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 and 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 any integration as any source effectively replaces PaperCut's database so any failures will extend through all layers of the system.

Option 7 - 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:

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.