External API

Finpilo piedāvā ārējo API, lai integrētu citas sistēmas — grāmatvedības programmatūru, ERP platformas vai pielāgotus iekšējos rīkus — ar jūsu darbvietu.

Šī lapa ir atsauce izstrādātājiem vai integrācijas konsultantiem, kas veido savienojumu starp Finpilo un citu sistēmu.

Ko var darīt caur API

• Sinhronizēt partnerus (piegādātājus) no jūsu grāmatvedības sistēmas uz Finpilo.
• Sinhronizēt dimensiju vērtības (izmaksu centrus, PVN kodus, grāmatvedības kontus) no jūsu grāmatvedības sistēmas.
• Lasīt apstrādātos dokumentus, ieskaitot izgūtos datus, rindas pozīcijas un piešķirtās dimensijas.
• Lejupielādēt oriģinālo failu jebkuram dokumentam.
• Aktivizēt dokumenta nosūtīšanu uz konfigurēto webhook.

Dokumentus Finpilo var izveidot tikai caur portāla saskarni vai e-pasta pārsūtīšanu — caur API dokumentus izveidot nevar. Partneru un dimensiju dati gan var plūst abos virzienos.

Autentifikācija

Visiem API pieprasījumiem jāiekļauj galvene X-API-Key ar jūsu darbvietas API atslēgu.

X-API-Key: fp_jusu_darbvietas_atslega

Atslēgu ģenerējiet sadaļā Workspace Settings → API cilnē. Skatiet Workspace Settings, lai iegūtu norādījumus.

Atslēga ir piesaistīta vienai darbvietai. Piekļuve visiem resursiem tiek automātiski ierobežota ar šo darbvietu — nevar piekļūt entītijām vai dokumentiem ārpus tās.

Reference ID

Lielākā daļa galapunktu izmanto jūsu pašu reference ID (virknes identifikatorus, ko iestatāt, veidojot entītijas, partnerus vai dimensiju vērtības Finpilo), nevis iekšējos UUID. Tas vienkāršo integrāciju — izmantojiet tos pašus ID, ko izmanto jūsu grāmatvedības sistēma.

• companyReferenceId — entītijas reference ID (piem., ENT-00001).
• referenceId partneriem un dimensiju vērtībām — jūsu izvēlētais identifikators.

Izņēmums ir dokumenti — tos adresē pēc iekšējā UUID, ko atgriež saraksta galapunkts.

Partneri (Suppliers)

Galapunkta prefikss: /api/v1/companies/{companyReferenceId}/suppliers

Grupveida partneru pievienošana/atjaunināšana

POST /api/v1/companies/{companyReferenceId}/suppliers

Izveido jaunus partnerus vai atjaunina esošos. Atbilstība tiek noteikta pēc referenceId. Katrs ieraksts tiek apstrādāts neatkarīgi — kļūdas neatcel citus veiksmīgi apstrādātos ierakstus.

Limiti: 1 līdz 10 000 ierakstu vienā pieprasījumā.

Pieprasījuma dati:

[
  {
    "referenceId": "SUP-001",
    "legalName": "Acme Supplies OÜ",
    "regNo": "12345678",
    "vatNo": "EE123456789",
    "legalAddress": "Tallinn, Estonia",
    "bankAccounts": ["EE382200221020145685"]
  }
]

Obligātie lauki: referenceId, legalName. Visi pārējie ir neobligāti.

Atbilde 200:

{
  "created": 2,
  "updated": 1,
  "failed": 0,
  "results": [
    { "referenceId": "SUP-001", "status": "created" },
    { "referenceId": "SUP-002", "status": "updated" },
    { "referenceId": "SUP-003", "status": "failed", "error": "..." }
  ]
}

Partneru saraksts

GET /api/v1/companies/{companyReferenceId}/suppliers

Vaicājuma parametri:

Viens partneris

GET /api/v1/companies/{companyReferenceId}/suppliers/{referenceId}

Atbilde 200:

{
  "id": "uuid",
  "referenceId": "SUP-001",
  "legalName": "Acme Supplies OÜ",
  "regNo": "12345678",
  "vatNo": "EE123456789",
  "legalAddress": "Tallinn, Estonia",
  "bankAccounts": ["EE382200221020145685"],
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601"
}

Dimensiju vērtības

Galapunkta prefikss: /api/v1/companies/{companyReferenceId}/dimensions/{dimensionReferenceId}/items

dimensionReferenceId ir dimensijas reference ID, kā iestatīts entītijas Dimensions cilnē.

Grupveida dimensiju vērtību pievienošana/atjaunināšana

POST /api/v1/companies/{companyReferenceId}/dimensions/{dimensionReferenceId}/items

Tāda pati daļējas veiksmes semantika kā partneriem.

Limiti: 1 līdz 10 000 ierakstu vienā pieprasījumā.

Pieprasījuma dati:

[
  {
    "referenceId": "DIM-00001",
    "name": "Administration",
    "description": "Accounting, legal, management fees"
  }
]

Obligātie lauki: referenceId, name. description ir neobligāts.

Dimensiju vērtību saraksts

GET /api/v1/companies/{companyReferenceId}/dimensions/{dimensionReferenceId}/items

Vaicājuma parametri: page, pageSize (maks. 1000), updatedSince — tādi paši kā partneriem.

Viena dimensijas vērtība

GET /api/v1/companies/{companyReferenceId}/dimensions/{dimensionReferenceId}/items/{referenceId}

Atbilde 200:

{
  "id": "uuid",
  "referenceId": "DIM-00001",
  "name": "Administration",
  "description": "Accounting, legal, management fees",
  "allocationListReferenceId": "DEPT",
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601"
}

Dokumenti

Galapunkta prefikss: /api/v1/companies/{companyReferenceId}/documents

Dokumenti caur API ir tikai lasāmi. Tos var izveidot tikai caur augšupielādi vai e-pastu Finpilo portālā.

Dokumentu saraksts

GET /api/v1/companies/{companyReferenceId}/documents

Vaicājuma parametri:

Atbilde 200: dokumentu datu objektu masīvs (skatiet shēmu zemāk).

Viens dokuments

GET /api/v1/companies/{companyReferenceId}/documents/{documentId}

Atgriež pilnu dokumentu, ieskaitot visas rindas pozīcijas un dimensiju piešķīrumus.

Oriģinālā faila lejupielāde

GET /api/v1/companies/{companyReferenceId}/documents/{documentId}/file

Atgriež oriģinālo augšupielādēto failu kā bināru straumi. Content-Type atbilst oriģinālajai augšupielādei (PDF, JPEG, PNG).

Finpilo nepārveido un nepārkodē failus — jūs saņemat tieši to, kas tika augšupielādēts.

Dokumenta nosūtīšana uz webhook

POST /api/v1/companies/{companyReferenceId}/documents/{documentId}/send

Aktivizē nosūtīšanas plūsmu — Finpilo nosūta dokumentu uz konfigurēto webhook (entītijas webhook, ja iestatīts, citādi darbvietas webhook).

Vaicājuma parametri:

Atbilde 200:

{
  "success": true,
  "accountingReferenceId": "INV-2026-0042"
}

accountingReferenceId ir vērtība, ko atgriezis jūsu webhook galapunkts (ja tāda ir).

Atbilde 400 — nosūtīšana neizdevās:

{ "error": "Custom webhook is enabled for this entity but no URL is configured." }

Dokumenta datu shēma

Šī ir struktūra, ko atgriež dokumentu galapunkti un kas tiek sūtīta kā webhook saturs, kad dokuments tiek nosūtīts.

{
  "documentId": "3fa0b1c2-d3e4-5f67-8901-abcdef123456",
  "documentType": "Invoice",
  "direction": "Incoming",
  "documentNumber": "INV-2025-0042",
  "issueDate": "2025-01-15T00:00:00Z",
  "dueDate": "2025-02-15T00:00:00Z",
  "servicePeriodStartDate": "2025-01-01T00:00:00Z",
  "servicePeriodEndDate": "2025-01-31T00:00:00Z",
  "currency": "EUR",

  "supplierName": "Acme Supplies OÜ",
  "supplierRegNumber": "12345678",
  "supplierVatNumber": "EE123456789",
  "supplierAddress": "Tallinn, Estonia",
  "supplierBankAccounts": ["EE382200221020145685"],
  "supplierReferenceId": "SUP-001",

  "recipientName": "My Company SIA",
  "recipientRegNumber": "40003012345",
  "recipientVatNumber": "LV40003012345",
  "recipientAddress": "Riga, Latvia",
  "recipientBankAccounts": null,
  "recipientReferenceId": "ENT-00001",

  "lineItemsSubtotalExcludingTax": 1000.00,
  "allowancesAmountExcludingTax": 0,
  "chargesAmountExcludingTax": 0,
  "retentionAmountExcludingTax": 0,
  "totalExcludingTax": 1000.00,
  "taxAmount": 200.00,
  "totalIncludingTax": 1200.00,
  "prepaidAmountIncludingTax": null,
  "payableAmountIncludingTax": 1200.00,

  "comment": null,
  "validatedAt": "2025-01-20T09:15:00Z",
  "entityName": "My Company SIA",
  "fileUrl": "https://docmanager-api.../api/v1/companies/ENT-00001/documents/3fa0b1c2-.../file",

  "lineItems": [
    {
      "position": 1,
      "title": "Consulting services",
      "description": "January 2025",
      "supplierCode": "CONS-001",
      "unit": "h",
      "quantity": 10.0,
      "unitPriceExcludingTax": 100.00,
      "totalExcludingTax": 1000.00,
      "taxRate": 20.0,
      "taxAmount": 200.00,
      "totalIncludingTax": 1200.00,
      "allocations": [
        {
          "allocationListReferenceId": "DEPT",
          "dimensionName": "Department",
          "code": "IT",
          "name": "IT Department",
          "description": null
        }
      ]
    }
  ],
  "allocations": []
}

Lauki bez datiem ir null (nekad netiek izlaisti). lineItems un allocations vienmēr ir masīvi (tukši [], ja nav nekā).

Webhook integrācijas plūsma

Kad Finpilo nosūta dokumentu uz jūsu webhook, ievērojiet šo tipisko plūsmu:

1. Saņemiet HTTP POST pieprasījumu. Saturs ir application/json, atbilstošs augstāk aprakstītajai shēmai.
2. Ja Finpilo webhook iestatījumos konfigurējāt API atslēgu, tā pienāks Authorization: Bearer <key> galvenē. Pārbaudiet to pirms apstrādes.
3. Izveidojiet ierakstu savā sistēmā, izmantojot strukturētos datus.
4. Iegūstiet oriģinālo failu no fileUrl, izmantojot savu Finpilo darbvietas API atslēgu (to pašu, kas tiek izmantota visiem API pieprasījumiem).
5. Pievienojiet failu savam ierakstam.
6. Atgrieziet JSON atbildi ar accountingReferenceId, kas iestatīts kā jūsu iekšējā ieraksta ID. Tukšs 200 OK atbildes ziņojums arī ir derīgs, ja neizsekojat atsaucei.

Finpilo gaida līdz 30 sekundēm uz jūsu atbildi. Pieprasījumi, kas pārsniedz šo laiku, tiek atzīmēti kā neizdevušies.

Finpilo sūtītās galvenes

Katrs webhook pieprasījums ietver:

Content-Type: application/json
Authorization: Bearer <api-key>

Authorization galvene tiek iekļauta tikai tad, ja webhook iestatījumos konfigurējāt API atslēgu.

Kļūdu atbildes

Visas kļūdu atbildes izmanto formu { "error": "apraksts" }.