fennoa-api-client

FennoaApiClient is a third party Fennoa API client.

:warning: This tool is in early stages and is subject to change.

Installation

Add to project's package.json:

npm install @rantalainen/fennoa-api-client

Setup

Import to NodeJS project

const { FennoaApiClient } = require('@rantalainen/fennoa-api-client');

Import to TypeScript project

import { FennoaApiClient } from '@rantalainen/fennoa-api-client';

Setup client with options

In order to obtain an API key, please contact Fennoa Sales or Fennoa Support. An API key is needed to access all API functions.

const fennoa = new FennoaApiClient({
  // Mandatory options:
  fennoaUser: 'selected_company_identifier',
  fennoaPassword: 'api_key',

  // Optional options (and default values):
  apiBaseUrl: 'https://app.fennoa.com/api',
  timeout: 120000
});

Implemented methods

The following api methods have been implemented:

• accounting Accounting, ledger and budgets
• customers Customers
• dimensions Dimensions and dimension types
• sales Sales invoices
• purchases Purchase invoices

Getter examples

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

const customers = await fennoa.customers.getAll(); // array of customers
const customer = await fennoa.customers.getById(1234); // single customer by id

Customer examples

Get customer by customer number:

const customer = await fennoa.customers.getByCustomerNo('1234'); // single customer by customer number

const newCustomer: INewCustomer = {
  customer_no: '1234',
  name: 'Test Customer 2 Oy',
  name2: 'Nimi 2',
  address: 'Test Address 1',
  postalcode: '00100',
  city: 'Helsinki',
  country_id: 'FI',
  description: 'Test Description',
  email: '[email protected]',
  phone: '0123456789',
  fax: '0123456789',
  website: 'https://www.example.com',
  business_id: '1837795-7',
  vat_number: 'FI18377957',
  identity_number: '123456-7890',
  account_type_id: 1,
  contact_person: 'John Doe',
  einvoice_address: '[email protected]',
  einvoice_operator_id: 'OKOYFIHH',
  sales_invoice_delivery_method: 'email',
  customer_group_ids: [1, 2],
  locale_id: 1,
  locale_code: 'FI'
};

const createdCustomer = await fennoa.customers.createCustomer(newCustomer);

const updateCustomer: IUpdateCustomer = {
  name: 'Updated Customer Oy'
  customer_group_ids: [3],
};

const updatedCustomer = await fennoa.customers.updateCustomer('1234', updateCustomer);

Sales examples

Here is an example of creating, approving and sending a new sales invoice to a customer:

const invoice = {
  name: 'Customer Inc',
  address: 'Mariankatu 2',
  postalcode: '00170',
  city: 'Helsinki',
  country: 'FI',
  invoice_date: '2018-12-12',
  due_date: '2018-12-26',
  row: [
    {
      name: 'My product',
      description: 'Describe product here',
      price: 14.5,
      quantity: 3,
      vatpercent: 14
    },
    {
      name: 'My service',
      description: 'Describe service here',
      price: 56.66,
      quantity: 12.5,
      vatpercent: 24
    }
  ]
};

// Create a new sales invoice to Fennoa
const newInvoiceId = await fennoa.sales.createInvoice(invoice);
console.log(`Sales invoice #${newInvoiceId} created`);

// Approve created sales invoice and send it to customer
await fennoa.sales.approveInvoice(newInvoiceId);
await fennoa.sales.sendInvoice(newInvoiceId);
console.log(`Sales invoice #${newInvoiceId} approved and sent to customer`);

Create a new sales invoice using FORM DATA:

const newInvoiceId = await fennoa.sales.createInvoiceByFormData(formData);

Create a new sales invoice from Finvoice XML data:

const newInvoiceId = await fennoa.sales.createInvoiceByFinvoiceXML(xml);

Fetch a sales invoice by invoice number and patch the due date:

const invoice = await fennoa.sales.getByInvoiceNo(1001);

await fennoa.sales.patchInvoiceDueDate(Number(invoice.SalesInvoice?.id), '2026-07-01');

Add a sales invoice payment and fetch payments:

await fennoa.sales.addPayment({
  invoice_no: '1001',
  payment_date: '2026-05-12',
  sum: 100,
  payment_type: 2,
  is_factoring: 0,
  description: 'Cash payment'
});

const payments = await fennoa.sales.getPayments('2026-05-01', '2026-05-31');

Purchases examples

Here is an example of fetching all purchase invoices from approval queue:

const purchases = await fennoa.purchases.getApprovalQueue();

Fetch single purchase invoice by ID:

const purchaseInvoice = await fennoa.purchases.getPurchaseInvoiceById(12);

Approve purchase invoice by approval ID with an optional comment:

fennoa.purchases.approvePurchaseInvoice(2, 'Approved by automation');

Add payment to purchase invoice:

const paymentInfo = {
  purchase_invoice_id: 2,
  sum: 100,
  payment_date: '2025-03-01',
  description: 'Paid by automation'
};

await fennoa.purchases.addPurchasePayment(paymentInfo);

Accounting examples

Fetch accounting periods, ledger rows and account balances:

const periods = await fennoa.accounting.getPeriods();

const ledger = await fennoa.accounting.getLedger('2024-01-01', '2024-01-31', {
  accounts: [1900, 3000],
  page: 1,
  limit: 100
});

const balance = await fennoa.accounting.getAccountBalance(1900, '2024-01-31');

const budgets = await fennoa.accounting.getBudgets(periods[0].id);

Create a balanced accounting statement and a budget:

const statementId = await fennoa.accounting.createStatement({
  entry_date: '2024-01-01',
  statement_series_code: 'CA',
  description: 'Cash sales',
  row: [
    {
      debit: 100,
      account: 1900,
      description: 'Cash received'
    },
    {
      credit: 100,
      account: 3000,
      description: 'Sales income',
      vatcode: 11
    }
  ]
});

const budgetId = await fennoa.accounting.createBudget({
  name: 'Budget 2024',
  accounting_period_id: 1,
  accounts: [
    {
      code: '3000',
      period_total_sum: 15000
    }
  ]
});

const patchedBudget = await fennoa.accounting.patchBudget(budgetId, {
  name: 'Budget 2024 updated',
  accounting_period_id: 1,
  accounts: [
    {
      code: '3000',
      period_total_sum: 18000
    }
  ]
});

Dimension examples

Fetch dimensions and dimension types:

const dimensionTypes = await fennoa.dimensions.getTypes();

const dimensions = await fennoa.dimensions.getAll({
  dimension_type_id: 1,
  is_active: 1
});

const dimension = await fennoa.dimensions.getById(2);

Create a new dimension or update an existing one:

const dimensionId = await fennoa.dimensions.createDimension({
  dimension_type_id: 1,
  code: 'ABC',
  name_fi: 'Projekti ABC',
  name_en: 'Project ABC'
});

const dimensionTypeId = await fennoa.dimensions.createDimensionType({
  name_fi: 'Projekti',
  name_en: 'Project'
});

Resources

• Fennoa website: https://www.fennoa.com/
• Fennoa API Documentation: https://www.fennoa.com/api-documentation/
• Fennoa login page: https://app.fennoa.com/login