Step-by-step integration guide

Endpoints

• Trial balance: POST https://<domain>/api/v1/ingest/trial-balance
• Open items (receivables and payables aging): POST https://<domain>/api/v1/ingest/open-items
• Inventory movements: POST https://<domain>/api/v1/ingest/inventory. asOfDate (yyyy-MM-dd) is optional. If it is omitted, including in strict mode, the stock date is derived from the latest movement date and the response includes a warning.

Request headers

• Only HTTPS and POST are accepted.
• Content-Type: application/json
• Authorization: Bearer <API_KEY> or X-Api-Key: <API_KEY>
• The company is always taken from the API key; do not put a company id in the body.

API key

• Your company's Company Admin creates the key on the Integrations page in TheFinly and passes it to you through a secure channel.
• The key is shown only once; store it somewhere safe. Do not share it by email or in documents.
• If the key leaks, the Company Admin revokes it at once and creates a new one. A revoke takes effect immediately.

Minimal example body (trial balance)

{
  "externalId": "demo-2024-12",
  "period1": {
    "label": "2023",
    "periodEnd": "2023-12-31",
    "lines": [
      { "accountCode": "DEMO-001", "debit": 400000, "credit": 0, "balance": 400000, "templateKey": "HAZIR_DEGERLER" }
    ]
  },
  "period2": {
    "label": "2024",
    "periodEnd": "2024-12-31",
    "lines": [
      { "accountCode": "DEMO-001", "debit": 450000, "credit": 0, "balance": 450000, "templateKey": "HAZIR_DEGERLER" }
    ]
  }
}

The example is synthetic and shortened. For the full field list, required keys and the open-items body, see the API document sent to your company. In JSON, dates are yyyy-MM-dd and amounts are plain numbers (e.g. 4800000).

Response codes at a glance

• 401: key missing, invalid or revoked.
• 403: the company account is suspended.
• 409: the same externalId was already sent with different content.
• 413: request body too large (4 MB at most).
• 422: validation error; nothing is stored, see the errors list.
• 429: rate limit exceeded; wait briefly and try again.

1. Download the template:
   • TheFinly financial statement template
   • Receivables aging template
   • Payables aging template
2. Fill in the template with your company's data; do not change the column headers.
3. Sign in to TheFinly and upload the file on the Upload page.

ERP data import (Integrations → Import) requires Company Admin permission.

For questions, contact your company's Company Admin first and, if needed, TheFinly support (support@thefinly.com).

Sign in to TheFinly