Activepieces Acumulus Piece

Een custom Activepieces piece voor integratie met SIEL Acumulus Nederlandse online boekhouding.

Features

Actions

| Action | Beschrijving | |--------|-------------| | Factuur Aanmaken | Maak een nieuwe factuur aan in Acumulus met volledige controle over alle velden | | Factuur van HostBill | Maak een factuur aan op basis van HostBill JSON data (geoptimaliseerd voor HostBill webhooks) | | Betaalstatus Bijwerken | Werk de betaalstatus van een factuur bij (betaald/niet betaald) | | Betaalstatus Ophalen | Haal de huidige betaalstatus op | | Factuur E-mailen | Verstuur een factuur per e-mail als PDF | | Kostenplaatsen Ophalen | Haal de lijst met kostenplaatsen op | | Grootboekrekeningen Ophalen | Haal de lijst met grootboekrekeningen op | | Factuursjablonen Ophalen | Haal de lijst met factuursjablonen op |

Automatische BTW-detectie

De piece bepaalt automatisch het juiste BTW-type op basis van:

• Land van de klant (NL, EU, of buiten EU)
• BTW-nummer aanwezig of niet

| Situatie | BTW-type | |----------|----------| | NL klant | Nationaal (21%) | | EU klant + BTW-nummer | Intracommunautair (verlegd) | | EU klant zonder BTW-nummer | Europese BTW | | Buiten EU | Export (0%) |

Installatie

Optie 1: Via npm (aanbevolen voor self-hosted Activepieces)

Voeg de piece toe aan je Activepieces installatie:

# In je Activepieces directory
npm install @cloudformatie/piece-acumulus

# Of voeg toe aan packages/pieces/community/package.json:
# "@cloudformatie/piece-acumulus": "^1.0.0"

Optie 2: Git clone

# Clone naar je pieces directory
cd /path/to/activepieces/packages/pieces/community
git clone https://github.com/cloudformatie/activepieces-acumulus.git acumulus
cd acumulus
npm install
npm run build

Optie 3: Docker volume mount

Als je Activepieces in Docker draait:

# docker-compose.yml
services:
  activepieces:
    volumes:
      - ./custom-pieces/acumulus:/app/packages/pieces/community/acumulus

Configuratie

Acumulus API-gebruiker aanmaken

1. Log in op Acumulus
2. Ga naar Beheer → Gebruikers
3. Klik op Nieuwe gebruiker
4. Kies type: API gebruiker of API beheerder
5. Vul gebruikersnaam en wachtwoord in
6. Sla op

Contract code vinden

1. Ga naar Beheer → Licentie
2. Je contract code staat bovenaan

Verbinding testen

Bij het aanmaken van een nieuwe Acumulus connection in Activepieces wordt automatisch een test uitgevoerd.

Voorbeeldflows

Flow 1: HostBill Invoice → Acumulus

Trigger: Webhook (HostBill invoice.created)
    ↓
Action: Acumulus - Factuur van HostBill
    - hostbillInvoice: {{trigger.body}}
    - sendAsConcept: false
    ↓
Action: Store - Bewaar Acumulus token
    - key: acumulus_{{trigger.body.id}}
    - value: {{previous.acumulusToken}}

Flow 2: HostBill Payment → Acumulus betaalstatus

Trigger: Webhook (HostBill invoice.paid)
    ↓
Action: Store - Haal Acumulus token op
    - key: acumulus_{{trigger.body.invoice_id}}
    ↓
Branch: Token gevonden?
    ↓ Ja
Action: Acumulus - Betaalstatus Bijwerken
    - token: {{previous.value}}
    - paymentStatus: Betaald
    - paymentDate: {{trigger.body.datepaid}}

Flow 3: Handmatige factuur aanmaken

Trigger: Webhook (extern systeem)
    ↓
Action: Acumulus - Factuur Aanmaken
    - customerEmail: [email protected]
    - customerCompanyName: Bedrijf BV
    - customerCountryCode: NL
    - invoiceLines: [
        {
          "product": "Consultancy",
          "unitPrice": 125.00,
          "vatRate": 21,
          "quantity": 8
        }
      ]
    - sendEmail: true

HostBill Webhook Configuratie

HostBill webhook URL instellen

1. Log in op HostBill Admin
2. Ga naar Settings → Notifications → Webhooks
3. Voeg een nieuwe webhook toe:
   • URL: https://jouw-activepieces.com/api/v1/webhooks/xxx
   • Events: invoice.created, invoice.paid, invoice.cancelled
   • Format: JSON

Verwachte HostBill webhook payload

{
  "event": "invoice.created",
  "id": 12345,
  "client": {
    "id": 100,
    "email": "[email protected]",
    "firstname": "Jan",
    "lastname": "Janssen",
    "companyname": "Bedrijf BV",
    "address1": "Straat 1",
    "postcode": "1234AB",
    "city": "Amsterdam",
    "country": "NL",
    "tax_id": "NL123456789B01",
    "phonenumber": "+31612345678"
  },
  "date_created": "2024-03-15",
  "subtotal": 100.00,
  "tax": 21.00,
  "total": 121.00,
  "status": "Unpaid",
  "items": [
    {
      "id": 1,
      "description": "Webhosting pakket",
      "amount": 100.00,
      "tax_rate": 21,
      "quantity": 1
    }
  ]
}

Token Opslag

De Acumulus API retourneert een token (32-karakter hash) voor elke factuur. Deze token is nodig voor:

• Betaalstatus bijwerken
• Factuur e-mailen
• PDF ophalen

Aanbevolen: Activepieces Store

Gebruik de ingebouwde Store piece om tokens op te slaan:

Key: acumulus_invoice_{hostbill_invoice_id}
Value: {acumulus_token}

Alternatief: Database

Als je veel facturen hebt, overweeg een externe database (MySQL, PostgreSQL) via de Database piece.

Foutafhandeling

De piece retourneert altijd een success boolean:

{
  "success": true,
  "invoiceNumber": "2024-0001",
  "token": "abc123...",
  "entryId": 12345
}

Of bij fouten:

{
  "success": false,
  "errors": [
    {
      "code": "401",
      "codetag": "auth_error",
      "message": "Invalid credentials"
    }
  ]
}

Gebruik een Branch piece om op success te filteren.

Development

# Installeer dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Tests
npm test

# Lint
npm run lint

Licentie

MIT

Auteur

Cloudformatie - cloudformatie.nl