Integrations

Overview

System	Protocol	Auth	Purpose
Tripletex	REST API v2	OAuth2 + session tokens	Accounting operations (full ERP)
Fiken	REST API v2	OAuth2 (bearer token)	Accounting operations (SMB)
Conversation Agent	REST	Internal service auth	Multi-turn context, clarification, routes to Accounting API
Slack	Bot Events API	OAuth2 (bot token)	Employee chat interface (via Conversation Agent)
Email	SMTP webhook	Inbound webhook + DKIM verification	Invoice forwarding (via Conversation Agent)
Gemini (Vertex AI)	REST	GCP service account (Workload Identity)	Primary LLM
Claude (Anthropic)	REST	API key	Fallback LLM for complex tasks

Tripletex

OAuth2 Onboarding Flow

1. Customer clicks "Connect Tripletex" on dashboard
2. Redirect to Tripletex OAuth consent screen
   GET https://tripletex.no/v2/token/session/:create
3. Customer authorizes access
4. Tripletex redirects back with authorization code
5. Backend exchanges code for consumer token + employee token
6. Tokens encrypted (AES-256-GCM) and stored in company table
7. Session token created per API request (auto-refresh, 1 hour TTL)

Authentication per Request

Every API call uses Basic Auth with a session token:

Authorization: Basic base64("0:" + session_token)

Session tokens are created via PUT /token/session/:create using the consumer token and employee token. The system maintains a token cache and refreshes 5 minutes before expiry.

Rate Limits

Tripletex enforces 100 requests/second per company. The TripletexProvider implements:

Request queuing with token bucket (80 req/s target, 20 req/s buffer)
Retry with exponential backoff on 429 responses
Batch endpoints used where available (GET /invoice?id=1,2,3)

Key Endpoints Used

Category	Endpoints
Customers	`GET/POST /customer`
Suppliers	`GET/POST /supplier`
Invoices	`GET/POST /invoice`, `PUT /invoice/:id/:action`
Supplier Invoices	`GET/POST /supplierInvoice`, `POST /:id/:action=pay`
Vouchers	`GET/POST /ledger/voucher`
Ledger	`GET /ledger/account`, `GET /ledger/posting`, `GET /ledger/vatType`
Employees	`GET /employee`
Travel Expenses	`GET/POST /travelExpense`
Salary	`GET/POST /salary/payslip`, `GET/POST /salary/transaction`
Bank	`GET /bank/statement`, `POST /bank/reconciliation`
Departments	`GET /department`
Projects	`GET /project`

Fiken

Overview

Fiken is a Norwegian accounting system aimed at small businesses. Pricing starts at 99 NOK/month. The AI Accountant connects via the Fiken API v2.

OAuth2 Flow

1. Customer clicks "Connect Fiken" on dashboard
2. Redirect to Fiken OAuth consent screen
   GET https://fiken.no/oauth/authorize?client_id=...&response_type=code&redirect_uri=...&scope=...
3. Customer authorizes access
4. Fiken redirects back with authorization code
5. Backend exchanges code for access token + refresh token
   POST https://fiken.no/oauth/token
6. Tokens encrypted (AES-256-GCM) and stored in company table
7. Access token used as Bearer token in all API calls

Authentication per Request

Every API call uses a Bearer token:

Authorization: Bearer <access_token>

Refresh tokens are used to obtain new access tokens before expiry.

Rate Limits

Fiken enforces 120 requests per minute per access token. The FikenProvider implements:

Request queuing with sliding window (100 req/min target, 20 req/min buffer)
Retry with exponential backoff on 429 responses
Batch operations where the API supports them

Base URL

https://api.fiken.no/api/v2

Key Endpoints Used

Category	Endpoints
Contacts	`GET/POST /companies/{slug}/contacts`
Invoices	`GET/POST /companies/{slug}/invoices`
Credit Notes	`POST /companies/{slug}/credit-notes`
Purchases	`GET/POST /companies/{slug}/purchases`
Payments	`POST /companies/{slug}/payments`
Journal Entries	`GET/POST /companies/{slug}/journal-entries`
Accounts	`GET /companies/{slug}/accounts`
Bank Accounts	`GET /companies/{slug}/bank-accounts`
Products	`GET/POST /companies/{slug}/products`

Limitations vs Tripletex

Fiken does not support: employee management, travel expenses, salary/payroll, department-level filtering, or project tracking. These operations are handled only by TripletexProvider.

Slack

Bot Setup

Create Slack App at api.slack.com/apps
Enable Event Subscriptions with request URL: https://api.ai-accountant.no/webhook/slack
Subscribe to bot events: message.channels, message.im, app_mention, file_shared
Enable Interactive Components for button actions (approve, send, undo)
Install to workspace -- bot token stored encrypted in company table

Message Flow

Slack messages are received by the Conversation Agent, which manages multi-turn context and clarification before calling the Accounting API.

Slack Event API ──POST──→ Conversation Agent /webhook/slack
                          │
                          ├── Verify signature (HMAC-SHA256)
                          ├── Parse event (message, file, action)
                          ├── Resolve employee (slack_user_id → employee_mapping)
                          ├── Manage conversation context (multi-turn, clarification)
                          └── POST /solve → Accounting API SolveController

Bot Scopes Required

Scope	Purpose
`chat:write`	Post messages and replies
`files:read`	Read uploaded receipt photos and PDFs
`users:read`	Resolve user display names
`im:history`	Read DM messages to the bot
`channels:history`	Read messages in channels the bot is in
`app_mentions:read`	Respond to @mentions

Email Webhook

Inbound Email Processing

Companies configure a forwarding address (e.g., regnskap@firma.no) that routes to the Conversation Agent via email webhook.

Email arrives ──→ Cloudflare Email Worker ──→ Conversation Agent POST /webhook/email
                                              │
                                              ├── Verify DKIM signature
                                              ├── Extract sender, subject, body
                                              ├── Extract attachments (PDF, images)
                                              ├── Match company by recipient domain
                                              └── POST /solve → Accounting API SolveController

Setup Options

Method	How
Cloudflare Email Routing	Add MX records, create Worker to forward to webhook
Custom domain forwarding	Customer sets up email forwarding rule in their provider
Direct integration	Microsoft 365 / Google Workspace app (Phase 3)

Attachment Handling

PDF invoices: text extracted via pdf-parse, OCR fallback via Google Cloud Vision
Images (receipt photos): sent directly to LLM with vision capability
Maximum attachment size: 10 MB
Supported formats: PDF, PNG, JPG, HEIC

LLM Providers

Primary: Gemini 2.5 Flash (Vertex AI)

Setting	Value
Model	`gemini-2.5-flash`
Endpoint	Vertex AI (via GCP)
Auth	Workload Identity Federation (keyless)
Latency	~2s per turn
Cost	~$0.002 per task
Features	Native function-calling, vision, 1M token context

Fallback: Claude Sonnet 4.6 (Anthropic)

Setting	Value
Model	`claude-sonnet-4-6-20250514`
Endpoint	`api.anthropic.com`
Auth	API key (stored in secret manager)
Latency	~3s per turn
Cost	~$0.01 per task
Features	Superior reasoning, PDF understanding, tool use

Fallback Logic

1. Try Gemini Flash (fast, cheap)
2. If Gemini returns 429/500/timeout → retry once
3. If still failing → switch to Claude Sonnet
4. If Claude also fails → return error to user
5. Log all fallback events for monitoring

Function Calling

Both LLMs use the same tool schema, defined by the IAccountingProvider interface. The AgentManager translates between the provider interface and each LLM's native function-calling format.