@gietmanic/finom-api-client

A Node.js client for the Finom Public API

📦 Installation

npm install @danielgtmn/finom-api-client

🚀 Quick Start

import FinomClient from '@gietmanic/finom-api-client';

// Initialize the client
const client = new FinomClient('YOUR_API_TOKEN');

// For sandbox mode
const sandboxClient = new FinomClient('sandbox', true);

✨ Features

• 🔑 Simple authentication
• 📋 Customer management
• 📄 Invoice handling
• 🔔 Webhook support
• 📦 TypeScript support
• 🚀 Promise-based API

📋 Usage Examples

Customer Management

// Create a customer
const customer = await client.createCustomer({
  countryCode: "DE",
  businessType: "Company",
  companyName: "Example GmbH",
  vatNumber: "DE123456789",
  email: "[email protected]"
});

// List customers
const customers = await client.listCustomers({
  pageSize: 10
});

// Get a single customer
const customer = await client.getCustomer('customer-id');

Invoice Management

// Create an invoice
const invoice = await client.createInvoice({
  customerId: "customer-id",
  dueDate: "2024-11-30",
  items: [
    {
      name: "Service",
      unit: "Hours",
      quantity: 10,
      unitPrice: 100,
      taxRate: 19
    }
  ]
});

// Mark invoice as paid
await client.payInvoice('invoice-id', {
  amount: 1190,
  paymentType: 'BankTransfer',
  paymentDate: '2024-10-30'
});

Webhook Management

// Create a webhook
const webhook = await client.createWebhook({
  events: ['InvoiceStatusChanged', 'InvoiceOverdue'],
  url: 'https://your-domain.com/webhook',
  secret: 'your-secret-key'
});

🔧 Error Handling

try {
  const invoice = await client.createInvoice({
    // invoice data
  });
} catch (error) {
  if (error.response) {
    console.error('Error:', error.response.data);
  } else if (error.request) {
    console.error('No response:', error.request);
  } else {
    console.error('Error:', error.message);
  }
}

📘 API Methods

Customers

• createCustomer(data)
• listCustomers(params?)
• getCustomer(id)
• updateCustomer(id, data)
• deleteCustomer(id)

Invoices

• createInvoice(data)
• listInvoices(params?)
• getInvoice(id)
• updateInvoice(id, data)
• deleteInvoice(id)
• payInvoice(id, paymentData)

Webhooks

• createWebhook(data)
• listWebhooks()
• getWebhook(id)
• deleteWebhook(id)

📝 License

MIT

🤝 Contributing

1. Fork it
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📫 Support

• Create a GitHub issue for bug reports and feature requests
• Follow @gietmanic for announcements