# TRF / Trivis Integration API

> Machine-to-machine REST API for Trivis, an accounting and business platform for Estonian companies. It covers sales and purchase invoices, contacts, products, payments, journal entries, billing contracts, CRM tasks, and file attachments, and is built for integrations, data sync, and migrations from other systems.

Base URL: https://api.trivis.ee (production), https://api.trf.is (staging). Interactive explorer for humans: /docs. This page and the per-topic pages it links to are the API reference for machines; fetch only the topic page you need.

## Authentication

- Every /v1 endpoint requires `Authorization: Bearer <key>`, where the key is a trfsk_live_... API key (or a Trivis UI session JWT).
- API keys are created in the Trivis app, or via POST /v1/api-keys from a UI session. The raw key is shown exactly once.
- Scopes: read, write, admin. Write operations need the write scope; /v1/api-keys needs admin, which API keys never have.

## Conventions

- POST bodies may be a single object or an array of up to 100; bulk calls return 207 Multi-Status with a per-item {ok, ...} or {ok:false, error}.
- Creating a document resolves referenced records or creates them: contacts by registration code, VAT number, or email; products by SKU. Send ids when you have them, natural keys when you do not.
- Amounts and quantities are decimal strings ("150.00"); ids are UUIDs; dates are ISO 8601.
- Listing: limit and skip (not offset; unknown query parameters are silently ignored). Incremental sync: modified_since=<RFC3339>, plus the per-resource /deleted endpoints for pruning.
- Async create routes honour an Idempotency-Key header (records expire after 24h). For migrations, use external_system + external_id instead; they never expire.
- Errors return {"error": {"code", "message", "suggestion"}} and every response with status 400+ is also recorded in GET /v1/error-logs.
- Rate limiting is per key; watch the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. 429 means slow down.

## Topics

Each page lists every endpoint of the topic with example payloads.

- [Infrastructure](/llms/infrastructure.md): Health and readiness probes (public, no auth), plus the per-tenant migration endpoint.
- [API Keys](/llms/api-keys.md): Create, list, and revoke trfsk_live_... API keys.
- [Sales Invoices](/llms/sales-invoices.md): List, fetch, create (sync or async, single or bulk up to 100), and soft-delete sales invoices; creating resolves or creates the contact and products automatically.
- [Ledger — Accounts](/llms/ledger-accounts.md): Read-only chart of accounts; use the ids as account_id on purchase invoice rows and journal entry lines.
- [Ledger — Periods](/llms/ledger-periods.md): Read-only accounting periods, including fiscal_year_id and quarter_id when linked.
- [Ledger — Entries](/llms/ledger-entries.md): List and fetch journal entries, and create posted entries (single or bulk up to 100).
- [Contacts](/llms/contacts.md): Direct CRUD on contacts; POST upserts by registration code, VAT number, then email, and PUT upserts under a UUID you supply.
- [Products](/llms/products.md): Direct CRUD on products; POST upserts by SKU, and /with-prices adds each product's active price list entries.
- [Purchase Invoices](/llms/purchase-invoices.md): List, fetch, and create purchase invoices: sync, async, bulk, or multipart with the source document attached.
- [Payments](/llms/payments.md): List, fetch, and create posted payments, optionally allocated to sales or purchase invoices.
- [Rentals and reservations](/llms/rentals.md): Rentable units (apartments, vehicles, equipment) with live availability, and reservations on them: book, confirm, cancel, hand over, return, quote, link to an invoice.
- [Contracts](/llms/contracts.md): Create billing contracts that activate immediately and schedule recurring invoicing; optionally register a signed webhook in the same transaction.
- [Tax Rates](/llms/tax-rates.md): Read-only list of active tax rates; use the id as tax_rate_id on sales and purchase invoice rows.
- [Dimensions](/llms/dimensions.md): Read-only dimension types and their values; tag postings via dimension_value_ids on invoice rows and journal entry lines.
- [Tasks](/llms/tasks.md): CRM follow-up tasks linked to contacts or deals: list, create, update, complete, archive.
- [Error Logs](/llms/error-logs.md): Every API response with HTTP status 400 or above is recorded per organisation; list them here instead of digging through server logs.
- [Invoice Dispatch](/llms/invoice-dispatch.md): Send confirmed sales invoices by email PDF or through the e-invoice network, singly or up to 100 in a batch.
- [Files](/llms/files.md): Upload, list, download, and delete binary documents (PDFs, images) attached to entities such as purchase invoices.
- [Migration](/llms/migration.md): How to import purchase invoices repeatably: stable external identity, duplicate recognition, and reconciliation.
- [Purchase Imports](/llms/purchase-imports.md): Upload invoice PDFs or images and let the AI parse them into purchase invoices; returns job ids to poll.