Stapsgewijze integratiehandleiding

Deze pagina is bedoeld voor de IT- en integratieverantwoordelijken die de gegevens van hun bedrijf naar TheFinly sturen. Er zijn twee manieren: automatisch verzenden vanuit uw ERP via de API, of handmatig uploaden met de Excel-sjabloon.

A) Verzenden via de API

Eindpunten

Proef- en saldibalans: POST https://<domain>/api/v1/ingest/trial-balance
Openstaande posten (ouderdomsanalyse debiteuren en crediteuren): POST https://<domain>/api/v1/ingest/open-items
Voorraadmutaties: POST https://<domain>/api/v1/ingest/inventory. asOfDate (yyyy-MM-dd) is optioneel. Als het wordt weggelaten, ook in de strikte modus, wordt de voorraaddatum afgeleid van de laatste mutatiedatum en bevat het antwoord een waarschuwing.

Verzoekheaders

Alleen HTTPS en POST worden geaccepteerd.
Content-Type: application/json
Authorization: Bearer <API_KEY> of X-Api-Key: <API_KEY>
Het bedrijf wordt altijd uit de API-sleutel afgeleid; zet geen bedrijfs-id in de body.

API-sleutel

De bedrijfsleiding van uw bedrijf maakt de sleutel aan op de pagina Integraties in TheFinly en geeft deze via een beveiligd kanaal aan u door.
De sleutel wordt maar één keer getoond; bewaar hem op een veilige plek. Deel hem niet per e-mail of in documenten.
Als de sleutel uitlekt, trekt de bedrijfsleiding hem direct in en maakt een nieuwe aan. Intrekken werkt onmiddellijk.

Minimaal voorbeeld van de body (proef- en saldibalans)

{
  "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" }
    ]
  }
}

Het voorbeeld is fictief en ingekort. Zie voor de volledige veldenlijst, verplichte sleutels en de body voor openstaande posten het API-document dat naar uw bedrijf is gestuurd. In JSON zijn datums yyyy-MM-dd en bedragen gewone getallen (bijv. 4800000).

Antwoordcodes in één oogopslag

401: sleutel ontbreekt, is ongeldig of is ingetrokken.
403: het bedrijfsaccount is opgeschort.
409: dezelfde externalId is al met andere inhoud verzonden.
413: body van het verzoek te groot (maximaal 4 MB).
422: validatiefout; er wordt niets opgeslagen, zie de lijst met fouten.
429: snelheidslimiet overschreden; wacht even en probeer het opnieuw.

B) Handmatig uploaden met Excel

Download de sjabloon:
Vul de sjabloon in met de gegevens van uw bedrijf; wijzig de kolomkoppen niet.
Meld u aan bij TheFinly en upload het bestand op de pagina Uploaden.

Voor het importeren van ERP-gegevens (Integraties → Importeren) zijn rechten van de bedrijfsleiding nodig.

C) Support

Neem bij vragen eerst contact op met de bedrijfsleiding van uw bedrijf en zo nodig met de support van TheFinly (support@thefinly.com).

Aanmelden bij TheFinly