How to Connect Snelstart to Your Custom Ecommerce Website: A Complete Guide

an article from mebsly.com

Running an online store is exciting, but managing the bookkeeping can be a real headache. Every order needs to be tracked, invoices need to be issued, and financial data needs to be organized. If you're doing all of this manually, you're probably spending hours each week on administrative work that could be automated.

This is where Snelstart comes in. Snelstart is popular Dutch accounting software that helps business owners keep their finances organized and up-to-date. The good news? You can connect it directly to your custom ecommerce website. Once connected, your orders, customer information, and financial data sync automatically, saving you massive amounts of time and reducing errors.

In this guide, we'll walk you through everything you need to know about connecting Snelstart to your custom ecommerce website. Whether you're building with Node.js, Django, or any other framework, we'll cover the technical setup, best practices, and what you can expect from the integration.

Understanding Snelstart and Why It Matters for Your Store

Before diving into the technical details, let's talk about why Snelstart matters for your ecommerce business.

Snelstart is cloud-based accounting software designed specifically for Dutch businesses. It handles invoicing, bookkeeping, tax calculations, and financial reporting. For ecommerce businesses, this is incredibly valuable because online sales have unique accounting challenges.

Traditional accounting software wasn't built with online stores in mind. When you sell online, you deal with payment processors, multiple currencies, shipping costs, discounts, and complex tax calculations. Snelstart is designed to handle exactly these scenarios.

The real power comes when you integrate Snelstart with your ecommerce website. Instead of manually entering each order into your accounting system, the integration does it automatically. Your customer data syncs, inventory updates are reflected in real-time, and every transaction is recorded exactly as it should be. For business owners, this means less time doing paperwork and more time growing your business.

Prerequisites: What You Need Before Starting

Before you begin the integration process, make sure you have the following in place:

Snelstart Account Requirements:

• A Snelstart account with the right subscription plan. You'll need either the inZicht or inControl package to access API functionality. These are Snelstart's mid-to-premium plans designed for businesses that need more control and automation.
• If you don't already have a Snelstart account, you can sign up on their website. The good news is that Snelstart offers a free trial period, so you can test the integration before committing.

Developer Account:

• Access to the Snelstart Developer Portal. This is where you'll register your application and get your API credentials. You'll need to create a developer account if you don't have one already.

Your Ecommerce Platform:

• A custom-built ecommerce website (not using a platform like Shopify or WooCommerce, since those have pre-built integrations). This could be built with Next.js, Django, Node.js, PHP, or any modern web framework.
• Server-side access where you can write code to make API calls to Snelstart.
• HTTPS enabled on your website (this is required by Snelstart's API).

Technical Skills:

• Basic understanding of APIs and REST principles.
• Ability to work with API credentials securely (storing them in environment variables, not hardcoding them).
• Knowledge of your ecommerce platform's architecture so you know where to add the integration code.

The Two Types of Snelstart Connections: Which One Is Right for You?

Snelstart offers two main ways to connect your website to their accounting system. Understanding the difference will help you choose the right approach for your needs.

Connection Type 1: Using a Connection Key (API Key)

This is the most straightforward method for custom integrations. Here's how it works:

With this method, you generate a unique connection key from your Snelstart account. This key acts like a password that authorizes your website to communicate with Snelstart. You store this key securely in your website's backend, and whenever you need to send data to Snelstart (like a new order), your website uses this key to authenticate.

When to use this method:

• You're building a custom integration for your own website
• You want direct control over how data is synchronized
• You're comfortable storing and managing API credentials

How straightforward is it?
Very straightforward. Once you have the key, you can start making API calls immediately. This is usually the fastest path from setup to working integration.

Connection Type 2: Using Webhooks

Webhooks are a different approach. Instead of your website constantly asking Snelstart for information or pushing data whenever something happens, Snelstart sends information to your website automatically when specific events occur.

For example, imagine a webhook is like having a messenger who watches your shop. Whenever something important happens in Snelstart (like an invoice gets paid), the messenger immediately runs to your website and tells it about the event. Your website then handles the information as needed.

When to use this method:

• You want real-time event notifications from Snelstart
• You prefer an event-driven architecture
• You want to minimize constant API polling

How straightforward is it?
Webhooks require a bit more setup since you need to create endpoints on your website that can receive and process incoming data from Snelstart. But once configured, they're very reliable and efficient.

Step-by-Step: Setting Up Your Connection Key

Let's walk through the process of generating your connection key from Snelstart. This is the first step you need to take.

Step 1: Log Into Your Snelstart Account

Start by logging into Snelstart with your credentials. Once you're logged in, you'll see your dashboard. On the left side of the screen, you'll see a menu. Look for the option called "Koppelingen" (which means "Connections" in Dutch). Click on it.

Step 2: Find the Custom Integration Option

In the Koppelingen section, you'll see several tiles representing different pre-built integrations (like connections with specific webshop platforms). However, since you're building a custom integration, you need to find the tile labeled "Maatwerk" (which means "Custom" in Dutch). This tile is for people building custom connections.

Click on this tile.

Step 3: Set Up Your Connection

After clicking on Maatwerk, you'll see an option that says "Koppeling instellen" (Set up connection). Click this button.

Snelstart will show you some permission scopes. These are essentially asking: "What is your website allowed to do with my Snelstart data?" For example, your website might need permission to read customer data, create invoices, read invoices, update payments, and so on.

Review these permissions carefully. They should match what your integration actually needs to do. For a typical ecommerce integration, you'll need permissions for:

• Reading and creating customers
• Reading and creating invoices
• Reading and updating orders
• Reading payment data

Once you've reviewed the permissions and they look correct, agree to them and save your settings.

Step 4: Copy and Secure Your Connection Key

After you've agreed to the permissions, Snelstart will generate a unique connection key for you. This looks like a long string of random characters. This is incredibly important: copy this key and store it somewhere safe.

Important security note: Never, ever put this key directly in your website's code or commit it to your version control system. Anyone who gets this key can access your Snelstart accounting data. Instead, store it in an environment variable on your server. If you're using Node.js, for example, you'd store it in a .env file (which is not committed to version control) and access it through process.env.SNELSTART_CONNECTION_KEY.

Getting Your Subscription Key: The Second Piece of the Puzzle

In addition to your connection key, Snelstart requires a subscription key for production use. This is an application-level credential that identifies your integration to Snelstart.

Step 1: Access the Snelstart Developer Portal

Visit the Snelstart Developer Portal and log in with your developer account credentials. If you don't have a developer account yet, you'll need to create one.

Step 2: Set Up a Subscription

In the Developer Portal, navigate to the "Products" section. Here, you'll see different subscription plans for API access. These range from basic development and testing plans to full production plans.

For most integrations, you'll start with the "Ontwikkeling & Test" (Development & Testing) plan. This plan is designed for testing your integration and doesn't cost anything. Later, when you're ready to go live, you can upgrade to a production plan.

Choose a name for your subscription (something like "My Ecommerce Integration") and subscribe to the plan. This is usually just a few clicks.

Step 3: Copy Your Subscription Key

Once your subscription is created, you'll be taken to your profile page. Here you'll see your subscription keys. There are typically two keys (primary and backup). Copy the primary key and store it securely, just like you did with your connection key.

Why two keys?
Snelstart gives you this two-key system for security and reliability. The connection key is unique to your Snelstart account and identifies your business. The subscription key is unique to your application registration and identifies your integration. Together, they create a secure two-factor authentication system.

Understanding Snelstart's API: What Can You Actually Do?

Now that you have your keys, let's talk about what you can actually do with the Snelstart API. What data can you sync? What operations can you perform?

What Data Can You Sync?

The Snelstart API allows you to work with a wide range of business data:

Customer Data:

• Create new customers in Snelstart when someone makes an account on your website
• Update customer information (names, addresses, email addresses, etc.)
• Retrieve existing customer data
• Manage payment terms for customers

Invoices and Transactions:

• Create invoices automatically when orders are placed
• Update invoice status as orders progress
• Create credit notes for refunds or cancellations
• Retrieve historical invoice data for reporting
• Access payment information

Order Management:

• Create and update sales orders
• Sync order lines (individual items in an order)
• Include shipping costs, discounts, and tax information
• Track order status throughout the fulfillment process

Products and Inventory:

• Create and update product information
• Sync inventory levels so Snelstart has accurate stock data
• Update pricing and cost information
• Manage product dimensions and specifications

Payments:

• Record payments received from customers
• Update payment status
• Manage payment terms and conditions
• Track outstanding invoices

Financial Records:

• Access journal entries for comprehensive financial reporting
• Retrieve ledger data
• Work with chart of accounts
• Access trial balance information

Other Business Information:

• Manage suppliers and vendor information
• Handle tax rates and calculations
• Work with payment methods
• Track bank accounts and reconciliation data

The beauty of this is that your ecommerce website can sync all relevant data to Snelstart, creating a complete financial record without any manual data entry.

Important Limitations to Know

While the Snelstart API is powerful, there are some limitations you should be aware of:

Subscription Package Requirements:

• API access is only available with inZicht and inControl packages. If you have a basic package like inStap or inKaart, you won't be able to use the API. You'll need to upgrade.

Rate Limiting:

• Like most APIs, Snelstart implements rate limiting. This means you can't make unlimited API calls. There are limits on how many requests you can make per minute or hour. For most ecommerce operations, this won't be an issue, but if you're syncing thousands of products, you might need to implement queuing.

Real-Time Constraints:

• While API sync is very fast, it's not instantaneous. There's always a small delay between when something happens on your website and when it appears in Snelstart. For most purposes, this delay is negligible (under a second), but it's worth knowing.

Data Validation:

• Snelstart has rules about what data is valid (for example, invoice numbers must be unique). If your website sends invalid data, the API call will fail. You'll need to implement proper validation on your website before sending data to Snelstart.

Building the Integration: Practical Implementation

Now let's talk about the actual implementation. We'll walk through the general architecture, then look at specific code examples for different frameworks.

General Architecture

Your ecommerce website will need to:

1. Authenticate with Snelstart using your connection key and subscription key
2. Prepare data from your database in a format that Snelstart expects
3. Send this data to Snelstart's API endpoints
4. Handle responses and errors
5. Log what was synced for audit purposes

Here's how this typically flows:

When a customer places an order on your website, your backend code triggers an integration function. This function:

• Retrieves the order data from your database
• Reformats the data into Snelstart's required format
• Makes an API call to Snelstart to create an invoice
• Receives a response confirming the invoice was created (or gets an error)
• Stores the Snelstart invoice ID in your database for future reference
• Logs the sync for debugging purposes

Node.js Example

If you're building with Node.js and Express, here's a practical example of how you might structure this:

javascript// snelstart-integration.js
const axios = require('axios');

class SnelstartIntegration {
constructor() {
this.connectionKey = process.env.SNELSTART_CONNECTION_KEY;
this.subscriptionKey = process.env.SNELSTART_SUBSCRIPTION_KEY;
this.baseURL = 'https://api.snelstart.nl/v3';
}

// Create a new customer in Snelstart
async createCustomer(customerData) {
try {
const response = await axios.post(
`${this.baseURL}/customers`,
{
name: customerData.name,
email: customerData.email,
address: customerData.address,
city: customerData.city,
zipCode: customerData.zipCode,
country: customerData.country
},
{
headers: {
'Authorization': `Bearer ${this.connectionKey}`,
'X-Subscription-Key': this.subscriptionKey,
'Content-Type': 'application/json'
}
}
);

return response.data;
} catch (error) {
console.error('Error creating customer in Snelstart:', error.response?.data);
throw error;
}
}

// Create an invoice in Snelstart
async createInvoice(invoiceData) {
try {
const response = await axios.post(
`${this.baseURL}/invoices`,
{
customerId: invoiceData.customerId,
invoiceNumber: invoiceData.invoiceNumber,
invoiceDate: invoiceData.invoiceDate,
dueDate: invoiceData.dueDate,
lines: invoiceData.lines, // Array of line items
notes: invoiceData.notes
},
{
headers: {
'Authorization': `Bearer ${this.connectionKey}`,
'X-Subscription-Key': this.subscriptionKey,
'Content-Type': 'application/json'
}
}
);

return response.data;
} catch (error) {
console.error('Error creating invoice in Snelstart:', error.response?.data);
throw error;
}
}

// Retrieve customer data from Snelstart
async getCustomer(customerId) {
try {
const response = await axios.get(
`${this.baseURL}/customers/${customerId}`,
{
headers: {
'Authorization': `Bearer ${this.connectionKey}`,
'X-Subscription-Key': this.subscriptionKey
}
}
);

return response.data;
} catch (error) {
console.error('Error retrieving customer from Snelstart:', error.response?.data);
throw error;
}
}
}

module.exports = SnelstartIntegration;

In your main application, you'd use it like this:

javascript// In your order processing code
const SnelstartIntegration = require('./snelstart-integration');
const snelstart = new SnelstartIntegration();

app.post('/api/orders', async (req, res) => {
try {
// Create order in your database
const order = await Order.create(req.body);

// Sync to Snelstart
const customerSnelstartId = await getOrCreateSnelstartCustomer(order.customerId);

const snelstartInvoice = await snelstart.createInvoice({
customerId: customerSnelstartId,
invoiceNumber: `INV-${order.id}`,
invoiceDate: new Date().toISOString().split('T'),
dueDate: new Date(Date.now() + 302460601000).toISOString().split('T'),
lines: order.items.map(item => ({
description: item.name,
quantity: item.quantity,
unitPrice: item.price
}))
});

// Store Snelstart invoice ID for reference
order.snelstartInvoiceId = snelstartInvoice.id;
await order.save();

res.json({ success: true, order });
} catch (error) {
console.error('Error processing order:', error);
res.status(500).json({ error: 'Failed to process order' });
}
});

Python/Django Example

If you're using Django, here's how you might structure the same integration:

python# snelstart_integration.py
import requests
import os
from django.conf import settings

class SnelstartIntegration:
def __init__(self):
self.connection_key = os.getenv('SNELSTART_CONNECTION_KEY')
self.subscription_key = os.getenv('SNELSTART_SUBSCRIPTION_KEY')
self.base_url = 'https://api.snelstart.nl/v3'
self.headers = {
'Authorization': f'Bearer {self.connection_key}',
'X-Subscription-Key': self.subscription_key,
'Content-Type': 'application/json'
}

def create_customer(self, customer_data):
"""Create a new customer in Snelstart"""
payload = {
'name': customer_data['name'],
'email': customer_data['email'],
'address': customer_data['address'],
'city': customer_data['city'],
'zipCode': customer_data['zip_code'],
'country': customer_data['country']
}

response = requests.post(
f'{self.base_url}/customers',
json=payload,
headers=self.headers
)

if response.status_code != 201:
raise Exception(f'Failed to create customer: {response.text}')

return response.json()

def create_invoice(self, invoice_data):
"""Create an invoice in Snelstart"""
payload = {
'customerId': invoice_data['customer_id'],
'invoiceNumber': invoice_data['invoice_number'],
'invoiceDate': invoice_data['invoice_date'],
'dueDate': invoice_data['due_date'],
'lines': invoice_data['lines'],
'notes': invoice_data.get('notes', '')
}

response = requests.post(
f'{self.base_url}/invoices',
json=payload,
headers=self.headers
)

if response.status_code != 201:
raise Exception(f'Failed to create invoice: {response.text}')

return response.json()

def get_customer(self, customer_id):
"""Retrieve customer from Snelstart"""
response = requests.get(
f'{self.base_url}/customers/{customer_id}',
headers=self.headers
)

if response.status_code != 200:
raise Exception(f'Failed to get customer: {response.text}')

return response.json()

Best Practices for a Reliable Integration

Once you've built the basic integration, there are several best practices you should follow to keep it running smoothly and securely.

1. Never Expose Your API Keys

This might seem obvious, but it's worth emphasizing. Your connection key and subscription key should never be visible in your code. Never commit them to version control. Never expose them in client-side JavaScript. Always store them as environment variables on your server.

If you accidentally expose a key, immediately regenerate it in the Snelstart Developer Portal. Exposed keys can be used by anyone to access and modify your accounting data.

2. Implement Proper Error Handling

When things go wrong (and they will sometimes), you need to handle it gracefully. Network errors happen. Snelstart's API might be temporarily unavailable. You might send invalid data.

Always wrap your API calls in try-catch blocks. Log errors so you can debug later. Consider implementing retry logic with exponential backoff for transient errors. Never let an integration error crash your entire website.

3. Queue Your Syncs for High-Volume Operations

If you're syncing a large amount of data (like importing a thousand products), don't try to do it all synchronously. This will be slow and fragile.

Instead, implement a queue system. Use something like Bull (for Node.js) or Celery (for Django) to add sync tasks to a queue. Then, a background worker processes these tasks one at a time, respecting Snelstart's rate limits.

javascript// Example with Bull queue
const Queue = require('bull');
const snelstartQueue = new Queue('snelstart-sync');

snelstartQueue.process(async (job) => {
const { type, data } = job.data;

if (type === 'create_invoice') {
await snelstart.createInvoice(data);
} else if (type === 'create_customer') {
await snelstart.createCustomer(data);
}

return { success: true };
});

// When you need to sync, add to queue instead of calling directly
app.post('/api/orders', async (req, res) => {
const order = await Order.create(req.body);

// Add to queue instead of syncing immediately
await snelstartQueue.add({ type: 'create_invoice', data: orderData });

res.json({ success: true, order });
});

4. Log Everything

Keep detailed logs of all API interactions with Snelstart. Log successful syncs, failed attempts, and any errors. This will be invaluable for debugging when something goes wrong.

Create a logging table in your database that tracks:

• What was synced (customer, invoice, order, etc.)
• When it was synced
• The Snelstart ID returned
• Your local ID
• Whether it succeeded or failed
• Error messages if it failed

5. Validate Data Before Sending

Snelstart expects data in a specific format. Before sending anything to the API, validate it thoroughly.

For example:

• Make sure invoice numbers are unique
• Verify that customer IDs exist in Snelstart
• Check that amounts are positive numbers
• Ensure email addresses are valid format
• Verify that required fields are not empty

The earlier you catch data problems, the fewer API calls you'll waste and the better your error messages will be.

6. Handle Webhooks Securely

If you're using webhooks, make sure you're validating them properly. Snelstart should include a signature or token in webhook requests that proves they came from Snelstart. Verify this signature before processing the webhook data.

Never assume a webhook came from Snelstart just because it has the right format.

7. Plan for Schema Changes

Over time, Snelstart might add new fields or change how their API works. Design your integration to be flexible enough to handle these changes.

Don't hardcode too much. Make your data mapping configurable. Regularly update your integration code as Snelstart releases new versions of their API.

Troubleshooting Common Issues

Even with careful planning, things sometimes go wrong. Here are some common issues and how to fix them.

Problem: "Authentication Failed" Error

Cause: Your API keys are invalid, expired, or incorrectly formatted.

Solution:

• Double-check that you've copied your connection key and subscription key correctly
• Make sure you're not including any extra spaces or line breaks
• Verify that you're storing them in the correct environment variables
• Check if your keys have expired (this can happen if you regenerated them)
• Make sure your Snelstart package (inZicht or inControl) still has API access enabled

Problem: "Rate Limit Exceeded" Error

Cause: You're making too many API calls too quickly.

Solution:

• Implement queuing and batch processing
• Add delays between requests
• Contact Snelstart to see if you can increase your rate limits
• Review your integration to see if you're making unnecessary duplicate calls

Problem: "Invalid Customer ID" Error

Cause: You're trying to use a customer ID that doesn't exist in Snelstart, or you're using your local ID instead of the Snelstart ID.

Solution:

• Make sure you're creating customers in Snelstart before trying to create invoices for them
• Store the Snelstart customer ID when you create a customer, and use that ID for future invoices
• Query Snelstart to verify the customer exists before trying to use it

Problem: "Invalid Data Format" Error

Cause: You're sending data in a format that Snelstart doesn't expect.

Solution:

• Review the Snelstart API documentation carefully
• Ensure dates are in the correct format (usually YYYY-MM-DD)
• Verify that numbers are actually numbers, not strings
• Check that required fields are included
• Validate your JSON structure is correct

Problem: Data Is Syncing But Calculations Look Wrong

Cause: You're not handling VAT/tax correctly, or you're not formatting prices correctly.

Solution:

• Understand Snelstart's VAT rules for your country
• Make sure you're sending prices in the correct format (with or without VAT, depending on your setup)
• Verify that shipping costs and discounts are being handled correctly
• Test with a known order to see if calculations match

Going Live: What to Know

When you're ready to move your integration from testing to production, there are several important steps to take.

Get Approved as a Snelstart Partner

If you're building this for other people to use (not just your own store), you'll need to become an official Snelstart Partner. This requires:

• Submitting your application and integration details
• Demonstrating that your integration works correctly
• Agreeing to Snelstart's partner terms
• Sometimes paying a certification fee (usually €250 excluding VAT for custom integrations)

Switch to a Production Subscription

In the Snelstart Developer Portal, upgrade from your development and testing subscription to a production subscription. Production subscriptions give you access to live customer data.

Thoroughly Test Before Launch

Before you let real customers start using the integration:

• Test with your own account first
• Test every scenario (creating customers, invoices, updating payments, etc.)
• Test error scenarios (what happens if the API is down?)
• Test with real data to make sure calculations are correct
• Have another person test it to catch things you might have missed

Monitor After Launch

After you go live:

• Monitor your logs closely for the first week
• Set up alerts for any integration errors
• Watch for unusual patterns (like sync failures on specific orders)
• Be ready to respond quickly if something breaks

Conclusion: Automate Your Way to Growth

Connecting Snelstart to your custom ecommerce website is one of the best investments you can make in your business. Yes, there's some technical setup involved. Yes, you need to store API keys securely and handle errors properly. But once it's working, the benefits are enormous.

You'll stop wasting hours on manual data entry. Your financial records will be more accurate because there's no human error in transcription. You'll have real-time visibility into your business finances. And best of all, you'll be able to focus your energy on actually growing your business instead of drowning in administrative work.

The process is straightforward: get your API keys, set up authentication, build your sync logic, implement error handling, and test thoroughly. Follow the best practices we've outlined, and you'll have a reliable integration that runs smoothly day after day.

Your future self will thank you for setting this up today. Now, stop manually entering orders and invoices, and let the automation do the work.

You might also be interested in:

• https://topiclo.com/post/lahore-where-history-hits-you-like-a-bus-and-the-food-never-quits
• https://topiclo.com/post/multan-where-ancient-history-meets-sweltering-heat
• https://topiclo.com/post/guwahati-messed-up-by-monsoon-my-jumbled-take
• https://topiclo.com/post/messy-daylight-hunches
• https://topiclo.com/post/dhanbad-coal-dust-dams-and-a-whole-lotta-stuff