Eenvoudig Factureren API Integration Skill

Eenvoudig Factureren API Integration

This skill provides instructions for interacting with the Eenvoudig Factureren invoicing platform API.

Base URL

https://eenvoudigfactureren.be/api/v1

Authentication

The API supports two authentication methods:

API Key (Recommended)

Pass the API key via the X-API-Key header:

X-API-Key: your-api-key

Environment Variable: The API key should be stored in EENVOUDIG_FACTUREREN_API_KEY. Always use this environment variable rather than hardcoding the key.

Example usage:

curl -H "X-API-Key: $EENVOUDIG_FACTUREREN_API_KEY" https://eenvoudigfactureren.be/api/v1/clients

Basic Authentication

Use email and password with standard Basic Authentication via the Authorization header. If the user has access to multiple accounts, specify the account via the X-AccountId header.

Response Formats

Add ?format= parameter to specify response format:

json - JSON format
xml - XML format (default)
csv - CSV format (Excel compatible)
html - HTML table
pdf - PDF document (invoices, receipts, quotes, orders, deliveries only)
efff, ublbe, peppol, peppolbis3 - Electronic invoice formats (invoices only)

HTTP Methods

GET - Retrieve data
POST - Create or partially update data (unmentioned fields remain unchanged)
PUT - Replace data completely (unmentioned fields are deleted)
DELETE - Delete data

Result Codes

200 - Success
201 - Created
400 - Bad request (invalid data)
401 - Authentication failed
403 - Access denied
404 - Not found
500 - Internal error

Available Domains

Clients (`/clients`)

Manage customer data including contacts and custom fields.

Endpoints:

GET /clients - List all clients
GET /clients/{id} - Get specific client
POST /clients - Create client
POST /clients?bulk - Bulk create/update clients (max 100)
PUT /clients/{id} - Update client
DELETE /clients/{id} - Delete client

Key fields:

client_id - Unique ID (auto-generated)
name - Client name (required, max 75 chars)
number - Client number
email_address - Email address
tax_code - VAT number
street, city, postal_code, country_code - Address fields
contacts - List of contact persons
delivery_address, site_address - Additional addresses
state - 'active' or 'archived'

Invoices (`/invoices`)

Manage invoices and credit notes. Credit notes have negative totals.

Endpoints:

GET /invoices - List all invoices
GET /invoices/{id} - Get specific invoice
POST /invoices - Create invoice
PUT /invoices/{id} - Update invoice
DELETE /invoices/{id} - Delete invoice

Subdomains:

/invoices/{id}/items - Invoice line items
/invoices/{id}/payments - Payments received
/invoices/{id}/remarks - Internal remarks
/invoices/{id}/costs - Reminder costs
/invoices/{id}/events - Events/history

Key fields:

invoice_id - Unique ID (auto-generated)
client_id - Client ID (required)
number - Invoice number (auto-generated if not provided)
date - Invoice date (YYYY-MM-DD)
days_due - Payment term in days
status - 'open', 'overdue', 'closed' (auto-determined)
type - 'invoice' or 'creditnote' (auto-determined)
items - List of invoice items
total_with_tax - Total including VAT (calculated)
structured_message - Belgian payment reference (12 digits)
note - Note shown on invoice

Invoice items:

description - Item description (required)
amount - Unit price excl. VAT
amount_with_tax - Unit price incl. VAT
quantity - Number of units (default: 1)
tax_rate - VAT percentage
stockitem_id - Link to stock item (auto-adjusts inventory)

Quotes (`/quotes`)

Manage quotations/offers.

Endpoints: Same structure as invoices

GET /quotes, GET /quotes/{id}, POST /quotes, etc.

Orders (`/orders`)

Manage order confirmations.

Endpoints: Same structure as invoices

Deliveries (`/deliveries`)

Manage delivery notes.

Endpoints: Same structure as invoices

Receipts (`/receipts`)

Manage cash register receipts.

Endpoints: Same structure as invoices

Subscriptions (`/subscriptions`)

Manage recurring invoices.

Stock Items (`/stockitems`)

Manage product/service catalog.

Endpoints:

GET /stockitems - List all items
POST /stockitems?bulk - Bulk create/update (max 100)

Layouts (`/layouts`)

Manage document templates.

Activities (`/activities`)

View activity log/events.

Common Query Parameters

Filtering

?filter=field%3Dvalue,field2%3D%7Etext

Operators (URL-encoded):

= (%3D) - equals
!= (%21%3D) - not equals
< (%3C), > (%3E), <= (%3C%3D), >= (%3E%3D) - comparisons
=~ (%3D%7E) - contains

Searching

?search=searchterm

Sorting

?sort=field1%2B-field2

Prefix with - for descending order. Separate multiple fields with + (%2B).

Pagination

?skip=30&take=10

Recommended: max 100 documents per request.

Field Selection

?fields=name,email_address

Sending Documents

Send via Email

POST /invoices/{id}?send_mail

Body parameters:

recipient - Email address, contact_id, or: 'myself', 'main_contact', 'first_contact', 'all_contacts'
recipients - List of recipients
subject - Email subject (optional)
message - Email body (optional)
document_type - 'pdf', 'ubl', 'both', 'duplicate', 'reminder', 'reminder_summary'
attachments - List of attachments (upload_id, filename)

Send via PEPPOL

POST /invoices/{id}?send_peppol

Send via Postal Mail (BPost)

POST /invoices/{id}?send_postalmail

Body parameters:

address_type - 'billing', 'delivery', 'site'
send_registered - 0 (non-prior) or 1 (registered)

Send to Accountant

POST /invoices/{id}?send_accountant

File Uploads (Attachments)

POST /uploads

Upload files as form-data with key 'file' (max 5MB). Returns upload_id to use with email attachments.

Example: Create Invoice with Items

{
  "client_id": 101,
  "number": "INV2024-001",
  "days_due": 30,
  "items": [
    {
      "description": "Product A",
      "amount": 100.00,
      "quantity": 2,
      "tax_rate": 21
    },
    {
      "description": "Shipping",
      "amount": 10.00,
      "tax_rate": 21
    }
  ]
}

Example: Register Payment

POST /invoices/{id}/payments
{
  "date": "2024-01-15",
  "amount": 250.00,
  "method": "transfer",
  "description": "Bank transfer"
}

Payment methods: transfer, cash, debitcard, creditcard, directcollection, online, bancontact, ideal

Important Notes

Always use HTTPS
Rate limiting applies - avoid too many consecutive requests
Use bulk endpoints for importing large datasets
Invoice numbers must be unique
Dates use format YYYY-MM-DD
Currency defaults to EUR
Language options: 'dutch', 'french', 'english', 'german'

Agent Skills: Eenvoudig Factureren API Integration

Install this agent skill to your local

Skill Files