npm package: @rantalainen/koho-api-helper
Description: Koho Sales API helper library
Latest version: 8.0.0

# 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

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

### Import to TypeScript project

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

### Setup with options

```javascript
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):

```javascript
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:

```javascript
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:

```javascript
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:

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

### Setter examples

Update by id:

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

Or by fetching resource first and using update method:

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

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

:warning: **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.

```javascript
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.

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

### Create example

Create new customer

```javascript
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](https://github.com/rantalainen/koho-api-helper/tree/old-changelog?tab=readme-ov-file#changelog).

## Miscellaneous examples

Update employee groups.

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