KohoApiHelper

API Helper for Koho Sales ERP (http://www.kohosales.com/)

Installation

Install from npm:

npm install @rantalainen/koho-api-helper

Usage

Import to NodeJS project

const KohoApiHelper = require('@rantalainen/koho-api-helper').KohoApiHelper;

Import to TypeScript project

import { KohoApiHelper } from '@rantalainen/koho-api-helper';

Setup with options

const kohoApiHelperOptions = {
  token: 'KOHO_API_TOKEN', // Token from Company Koho settings
  companyId: 1234, // Company ID in Koho, optional if enterpriseId is defined

  // Set Koho API url (you can also use KOHO_API_URL environment variable)
  url: 'https://suite.koho.cloud/api',

  // Optional:

  // Enterprise ID in Koho, if defined make sure to use enterprise token
  enterpriseId: 1234,

  // If you are spamming multiple requests to Koho, you should set this to true so that connections are reused
  // This option was depcerated in 6.0.0, internal keepAliveAgent enabled by default
  // useKeepAliveAgent: true,

  // Added in 2.0.0, disable streaming for Koho GET requests, defaults to false and GET requests are streamed
  disableStreaming: true,

  // Added in 3.1.0, optional throttleOptions
  throttleOptions: {
    enabled: true, // default: true
    delay: 30000, // default: 15000
    maxRetries: 1 // default: 3
  },

  // Disable keepAliveAgent, which is true by default (one can also pass own instance of https.Agent)
  keepAliveAgent: false,

  // Disable dnsCache, which is true by default (using got's cacheable-lookup)
  dnsCache: false
};

const helper = new KohoApiHelper(kohoApiHelperOptions);

Implemented methods and resources

The following api resources have been implemented:

• contracts Invoicing contracts
• customers Customers
• customersCategories Customer categories (asiakasryhmä)
• customersGroups Customer groups (erikoisryhmä)
• employees Employees
• invoices Invoices
• persons Customer contact persons
• products Products (product types)
• projects Projects
• sales Sales (pikakauppa)
• notifications Notifications
• offers Offers
• customReports Custom reports

Getter examples

Each resource type has getAll() and getById(1234) getters (below examples with contracts):

const contracts = await helper.contracts.getAll(); // array of contract instances
const contracts = await helper.contracts.getById(1234); // single contract instance

There are also some resource specific getters for customers:

const customers = await helper.customers.getByName('Customer Oy');
const customers = await helper.customers.getByNumber(1234);
const customers = await helper.customers.getByOrganizationId('1234567-8');

Above result can also be achieved by calling getAll() with parameters:

const customers = await helper.customers.getAll({ name: 'Customer Oy' });
const customers = await helper.customers.getAll({ number: 1234 });
const customers = await helper.customers.getAll({ organization_id: '1234567-8' });

Request query parameters can be passed freely. With call below you can find projects that have been updated after said date:

const projects = await helper.projects.getAll({ updated_after: '2020-06-01' });

Setter examples

Update by id:

await helper.projects.updateById(1234, { name: 'New project name' });

Or by fetching resource first and using update method:

const project = await helper.projects.getById(1234); // Get single project instance

await project.update({
  name: 'New project name'
});

⚠️ Warning!

When updating custom_parameters you should always first fetch the resource and then make the update with existing custom_parameters as in example below. Otherwise you will write over existing custom_parameters.

const customer = await helper.customers.getById(1234);

await customer.update({
  custom_parameters: {
    ...customer.custom_parameters, // assign existing parameters

    updated_parameter: 'Updated' // update other parameters
  }
});

You can also use patch_parameters for updating custom_parameters.

await customer.update({
  patch_parameters: {
    updated_parameter: 'Updated'
  }
});

Create example

Create new customer

const customer = await helper.customers.create({
  name: 'Example Customer Oy',
  description: 'Customer generated by Koho Api Helper',
  organization_id: '1234567-8'
});

Changelog

Changelog has moved to releases.

For older changelog, please refer to old-changelog branch.

Miscellaneous examples

Update employee groups.

await employee.update({
  group_ids: [1234, 123]
});