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. Lai pievienotu sarunvalodas AI asistentu (piemēram, Claude), nevis sistēmu, skatiet AI asistenti. Asistents izmanto tās pašas iespējas ar pierakstīšanos, nevis API atslēgu.

Ko var darīt caur API

• Sinhronizēt dimensiju vērtības — partnerus, izmaksu centrus, PVN kodus, grāmatvedības kontus — starp Finpilo un jūsu grāmatvedības sistēmu abos virzienos. Partneris ir tāda pati dimensija kā jebkura cita.
• Lasīt, meklēt un summēt dokumentus. Filtrējiet pēc jebkura lauka un saņemiet summas, skaitus vai vidējos rādītājus pa partneriem, izmaksu centriem vai periodiem, aprēķinātus no jūsu datiem.
• Augšupielādēt dokumentus un labot to laukus, rindu pozīcijas un dimensiju vērtības.
• Virzīt dokumentus pa statusiem.
• Lejupielādēt oriģinālo failu jebkuram dokumentam.

Ko API atslēga nekad nevar

Dažas lietas pieder cilvēkam ar pieteikšanos, nevis atslēgai, un neviena atļauja tās nepiešķir:

• Atbildēšana uz apstiprinājumiem. Apstiprinājums ir piešķirts konkrētam cilvēkam.
• Konfigurācijas labošana — dzīves cikli, darbplūsmas, integrācijas, skati.
• Entītiju izveide vai dzēšana un lietotāju pārvaldība. Atslēga ar pamatdatu rakstīšanas atļauju var atjaunināt esošas entītijas datus.

AI asistents, kas pievienots ar cilvēka pieteikšanos, to var, šī cilvēka lomas robežās — skatiet AI asistenti.

Maršruta izvēle — izlasiet, pirms sagatavojat piedāvājumu

Datus var pārvietot trīs veidos, un šī lapa apraksta tikai pirmo. Nepareizā izvēle maksā dienas darba, ko Finpilo jau dara.

1. Jūsu sistēma izsauc Finpilo (šī lapa). Jūs rakstāt klientu, turat API atslēgu un pēc sava grafika iesūtāt pamatdatus vai izgūstat dokumentus. Piemērots, ja plānotājs ir jūsu sistēmas pusē vai jums jāreaģē uz kaut ko pie sevis.

2. Jūsu sistēma nosūta darbplūsmai. Finpilo iedod jums ienākošo URL un slepeno atslēgu, un jūs nosūtāt saturu — visu partneru reģistru vienā izsaukumā, līdz 10 MB — un darbplūsma to pārveido un ieraksta. Nav jāraksta Finpilo klients. Piemērots, ja jūsu sistēma var izsaukt webhook. Ja jūsu sistēma izsaukumus paraksta, nevis sūta mūsu atslēgu (galvenē ir satura HMAC, kā to dara GitHub, Stripe un daudzas ERP), darbplūsma var pārbaudīt šo parakstu ar savu slepeno atslēgu. Skatiet Darbvietas iestatījumi.

3. Finpilo izsauc jūsu sistēmu pēc grafika. Šo parasti palaiž garām. Darbplūsma ar cron palaidēju izsauc jūsu API, pati iziet cauri jūsu lappusēm (page, offset, cursor vai link-header), prasa tikai ierakstus, kas mainījušies kopš pēdējās veiksmīgās reizes, atrisina jūsu iekšējos ID un ieraksta rindas ar idempotentu upsert. Jums nav jāraksta ne klients, ne plānotājs, ne kursora uzskaite, ne atkārtojumu loģika — jūs atverat lasīšanas galapunktu, un darbvietas administrators konfigurē pārējo.

Ja uzdevums ir "uzturēt klienta partnerus un izmaksu centrus vienādus", 3. maršruts parasti ir visa atbilde. To konfigurē darbplūsmu redaktorā vai palūdzot AI asistentam to uzbūvēt — skatiet AI asistenti. Sūtīšanas soļa iespējas, kas svarīgas pareizai iegrāmatošanai, ir šīs: lappušu iziešana, izmaiņu kursors, jūsu ID atrisināšana pirms satura veidošanas, idempotences atslēga un noteikums, kā nolasīt noraidījumu no 2xx atbildes.

API piekļuves iespējošana

API darbojas tikai tad, kad darbvietas administrators darbvietai ir ieslēdzis API & AI access (Workspace Settings → Integrations → Connect, kur ir arī API adrese ar pogu Copy). Kamēr tas ir izslēgts, katrs pieprasījums atbild ar 403. Izsaukums ar cilvēka pieteikšanos var darīt tikai to, ko atļauj šī cilvēka loma lietotnē. Skatiet Workspace Settings.

Bāzes URL

Visi pieprasījumi tiek sūtīti uz:

https://api.finpilo.com

Katrs zemāk norādītais ceļš ir relatīvs pret to, piemēram, GET https://api.finpilo.com/api/v1/companies/ENT-00001/documents.

Autentifikācija

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

X-API-Key: fp_jusu_api_atslega

Atslēgas ir katram savienojumam, nevis darbvietai: dažādas sistēmas nekad nedala pieejas datus, un katru var atslēgt atsevišķi. Izveidojiet to sadaļā Workspace Settings → Integrations → API Keys. Skatiet Integrācijas par visu procedūru, tostarp atslēgas nomaiņu ar pārejas periodu un atsaukšanu.

Katrai atslēgai ir savas atļaujas, kas izvēlētas tās izveides brīdī un vēlāk labojamas. Atļauja, kas nevienai atslēgai nav pieejama, saglabājot tiek noraidīta, un ziņojums to nosauc:

Atslēga bez atzīmētām atļaujām nevar neko — tā autentificējas un pēc tam tiek noraidīta katrā izsaukumā. Ja saņemat 403 izsaukumā, kam vajadzētu strādāt, vispirms pārbaudiet atslēgas atļaujas.

Atslēga sniedz piekļuvi tikai tām entītijām, kuras tās savienojums aptver. Pieprasījumi par jebkuru citu entītiju atgriež 404, tieši tā, it kā tā nepastāvētu. Ja savienojums aptver visas entītijas, tā atslēga darbojas visā darbvietā, bet nekad ārpus tās.

Pieprasījumu ierobežojums

300 pieprasījumi 60 sekundēs, skaitot uz katru savienojumu (tāpēc 24 stundu atslēgas nomaiņas laikā vecā un jaunā atslēga dala vienu limitu). Pārsniedzot, pieprasījumi tiek noraidīti ar 429, nevis ielikti rindā. Sadaliet lielus darbus laikā un izmantojiet paku galapunktus — viens 10 000 partneru upsert maksā vienu pieprasījumu.

Reference ID

Lielākā daļa galapunktu izmanto jūsu pašu reference ID (virknes identifikatorus, ko iestatāt, veidojot entītijas 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 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.

Kā atrast reference ID. GET /api/v1/companies uzskaita entītijas, ko atslēga var sasniegt, kopā ar to reference ID. GET /api/v1/companies/{companyReferenceId}/dimensions uzskaita šīs entītijas dimensijas un to reference ID. Sāciet ar tiem, nevis lūdziet kādam nolasīt tos no ekrāna.

Lappuses

Saraksta galapunkti atgriež vienkāršu JSON masīvu bez apvalka — bez kopskaita un bez kursora. Ejiet pa lappusēm, līdz kāda lappuse atgriež mazāk vienumu nekā pageSize.

pageSize ārpus pieļaujamā diapazona tiek ignorēts un aizstāts ar noklusējumu, nevis piesaistīts maksimumam: prasot 5000, saņemsiet 100, nevis 1000.

Divi atklāšanas galapunkti atšķiras: GET /api/v1/companies atgriež { total, items }, bet GET .../dimensions nav sadalīts lappusēs vispār.

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",
    "code": "6100",
    "values": { "owner": "K. Ozols", "bankAccounts": ["LV11AAA", "LV22BBB"] }
  }
]

Obligātie lauki: referenceId, name. description, code un values ir neobligāti.

values satur papildu kolonnas, ko dimensija ir deklarējusi. Tās iestata entītijas cilnē Dimensijas, un tās var apskatīt ar GET .../dimensions. Nosūtiet tās kā { "key": vērtība }, izmantojot katras kolonnas atslēgu. Kolonna, kas satur sarakstu, pieņem masīvu. Ja values neiekļaujat, saglabātās vērtības paliek nemainīgas; nosūtiet {}, lai tās notīrītu. Atslēga, ko dimensija nav deklarējusi, tiek ignorēta, nevis saglabāta.

code ir pašas vērtības īsais kods, tas, ko lietotāji redz, izvēloties vērtību dokumentā. Tas nav referenceId, pēc kura šis galapunkts saskaņo ierakstus: kods var atkārtoties, būt tukšs un brīvi mainīties. Ja code neiekļaujat, saglabātais kods paliek nemainīgs; nosūtiet "", lai to notīrītu.

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",
  "code": "6100",
  "allocationListReferenceId": "DEPT",
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601",
  "archivedAt": null,
  "values": { "owner": "K. Ozols", "bankAccounts": ["LV11AAA", "LV22BBB"] }
}

values atgriežas tieši tāds, kāds tika nosūtīts, tāpēc varat salīdzināt savus datus ar Finpilo datiem, nepārveidojot nevienu pusi. Ja vērtībai nav papildu kolonnu, šī lauka nav.

Pēc deklarētās kolonnas var arī filtrēt. POST .../items/query pieņem tos pašus strukturētos filtrus, ko dokumentu vaicājums, un deklarētu kolonnu norāda ar values. un tās atslēgu, piemēram, values.regNo. Tātad "kuram partnerim ir reģistrācijas numurs X" ir viens izsaukums.

Priedēklis nošķir jūsu kolonnas no laukiem, kas katrai vērtībai jau ir. Tāpēc kolonnu varat nosaukt kā vēlaties, arī code. Tad code nozīmē pašas vērtības kodu, bet values.code jūsu kolonnu, un tie viens otru neaizsedz.

Kolonna, kas satur sarakstu, atbilst tad, ja atbilst kāds no tās ierakstiem. Salīdzinājumiem ar lielāks/mazāks un between kolonnai jābūt deklarētai kā skaitlim vai datumam. Kārtot pēc deklarētas kolonnas nevar, tāpēc filtrējiet pēc tās un kārtojiet pēc cita lauka.

Dokumentus var atrast arī pēc deklarētas kolonnas vērtībai, kurai tie ir piesaistīti. Vaicājumā POST .../documents/query norādiet to kā allocations.<dimensija>.values.<atslēga>. Tātad "kuri rēķini ir no partnera ar šo reģistrācijas numuru" ir viens izsaukums. Tiek nolasīta pašreizējā vērtība, nevis tā, kas bija dokumenta piesaistes brīdī. Ja partnera reģistrācijas numuru izlabo, meklēšanas rezultāti uzreiz ir pareizi.

archivedAt ir aizpildīts, ja vērtība ir izņemta no aprites. Izņemtās vērtības joprojām parādās sarakstā, un tas ir apzināti. Sinhronizācija, kas tās neredzētu, uzskatītu vērtību par pazudušu un nosūtītu to atkārtoti, atjaunojot to, ko kāds apzināti izņēma.

Dokumenti

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

Zemāk esošie galapunkti aptver dokumentu lasīšanu un lejupielādi. API atbalsta arī dokumenta augšupielādi, tā lauku un rindu pozīciju labošanu, dokumentu meklēšanu un summēšanu ar strukturētiem filtriem un statusu maiņu. Šīs iespējas ievēro tās pašas Reference ID un autentifikācijas konvencijas. Detalizētām shēmām rakstiet uz help@finpilo.com.

POST /api/v1/companies/{companyReferenceId}/documents/query ir vērts zināt: atšķirībā no saraksta galapunkta tas pieņem strukturētus filtrus un atgriež { total, items }, un tā rindas satur dokumenta statusu, kura zemāk aprakstītajā saturā nav. Tukšs rezultāts satur noMatchReason, kas nosauc nosacījumu, kurš to iztukšoja.

Augšupielāde atgriež citu ID. POST .../documents/upload atbild ar companyFileId, kamēr visi pārējie galapunkti pieņem documentId. Query galapunkts atgriež abus, tāpēc izmantojiet to, lai tos savietotu.

Dokumentu saraksts

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

Vaicājuma parametri:

status ir reģistrjutīgs un atkarīgs no darbvietas. Statusus nosaka darbvietas pašas dzīves cikls, tāpēc fiksēta saraksta nav — Validated un Sent ir parastās atslēgas, bet validated neatbilst nekam un atgriež tukšu masīvu ar 200, nevis kļūdu. Nolasiet atslēgas no GET .../documents/{documentId}/status-options (tam vajag atļauju lasīt dokumentus, un pārejas tiek rādītas tikai atslēgai, kurai ir arī atļauja virzīt dokumentus) vai pajautājiet darbvietas administratoram. Tas pats attiecas uz sentOnly, kas meklē tieši atslēgu Sent. Ja jūsu darbvietas dzīves cikls piegādāto stāvokli sauc citādi, izmantojiet status= ar šo atslēgu.

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, katra cita grid rindas 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 datu shēma

Šī ir struktūra, ko atgriež dokumentu galapunkti. Nosūtīšanas darbplūsma tos var nosūtīt uz jūsu sistēmu, kad dokuments tiek nosūtīts, un administratori darbplūsmā nosaka, ko tā nosūta (skatiet Savienojumi).

{
  "documentId": "3fa0b1c2-d3e4-5f67-8901-abcdef123456",
  "documentType": "Invoice",
  "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"],

  "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": [
    {
      "id": "8c1f0a2b-4d5e-6f70-8192-a3b4c5d6e7f8",
      "position": 0,
      "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ā). Katras rindas id ir tas, ko nosūtāt atpakaļ dokumenta labošanā, lai atjauninātu šo rindu, nevis izveidotu dublikātu.

Lauki ir jūsu darbvietas lauki. Šeit ir katrs lauks, ko dokuments satur, zem tā atslēgas: gan tie, ar kuriem Finpilo jums sāk, gan katrs lauks, ko izveidojat paši. Lauks, ko atceļat, paliek šeit ar vērtību, ko satur katrs dokuments, un pēc tā joprojām var filtrēt un meklēt. To vienīgi vairs nevar aizpildīt. Atjaunojiet lauku, lai to atkal aizpildītu.

Katra grid rindas tiek nodotas vienādi. Rindas pozīcijas ir viena grid rindas, un tā atslēga ir lineItems. Ja jūsu darbvietā ir izveidoti citi grid (piemēram, pārvadājumu rindas), katra rindas nāk blakus lineItems ar šī grid atslēgu, un katra vērtība ir zem sava lauka nosaukuma, kas ir vienāds visos grid. Atslēga norāda uz grid visur. Dokumenta labošanā sūtiet "<grid key>": [rindas] katram grid, arī lineItems. Rindas vērtība ar nosaukumu, kura grid nav, tiek noraidīta, un atbilde nosauc šo nosaukumu. Vaicājuma filtrā rindas vērtību nosauciet kā <grid key>.<field>, tāpat kā lineItems.title rindas pozīcijām. Viss, kas rakstīts lineItems, turpina strādāt bez izmaiņām. Labošana, kas nosūta grid rindas, aizstāj visas šī grid rindas, tāpēc iekļaujiet katru rindu, ko vēlaties paturēt. Rinda, kas nosūtīta tikai ar savu id, saglabā to, kas tai bija, un grid, ko nenosaucat, paliek nemainīts. Grid, ko kāds ir izņēmis no lietošanas, nepieņem jaunas rindas. Rinda bez id šādam grid tiek noraidīta, un atbilde nosauc grid. Rindas, kas tajā jau ir, joprojām var labot un izlaist, lai tās dzēstu, tāpēc to var iztukšot.

Statuss šeit apzināti nav. Lai to nolasītu, izmantojiet POST .../documents/query, kura rindas satur statusu un katru lauku, kas ir šeit.

Piešķīruma code ir dimensijas vērtības referenceId — tas pats identifikators, pēc kura ierakstāt dimensiju vērtības, tikai ar citu nosaukumu.

Nosūtīto dokumentu saņemšana

Kad Finpilo nosūta dokumentu uz jūsu sistēmu, 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. Pieprasījums satur savienojumā konfigurēto autentifikāciju: Bearer token, Basic akreditācijas datus, pielāgotu galveni, OAuth token, token no jūsu pašu pieteikšanās galapunkta vai satura parakstu ar kopīgu slepeno atslēgu. Tas var uzrādīt arī klienta sertifikātu (skatiet Savienojumi). Pārbaudiet to pirms apstrādes.
3. Izveidojiet ierakstu savā sistēmā, izmantojot strukturētos datus.
4. Iegūstiet oriģinālo failu, ja tas jums vajadzīgs. Izveidojiet URL pats no satura: GET /api/v1/companies/{recipientReferenceId}/documents/{documentId}/file, ar savu API atslēgu. Nosūtītajā saturā ir fileUrl: null, tāpēc integrācija, kas uz to paļaujas, klusi pazaudē pielikumu.
5. Pievienojiet failu savam ierakstam.
6. Atgrieziet JSON atbildi ar accountingReferenceId, kas iestatīts kā jūsu iekšējā ieraksta ID. Finpilo to saglabā dokumenta laukā Accounting Reference. 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.

Atbildiet ar kļūdas statusu, kad noraidāt dokumentu. Pēc noklusējuma Finpilo uzskata jebkuru 2xx par veiksmīgu sūtījumu, tāpēc 200 ar {"ok": false} atzīmē dokumentu kā piegādātu. Ja jūsu API arī noraidījumam atbild ar 2xx un citādi nevar, darbvietas administrators var konfigurēt sūtīšanas soli lasīt atbildes saturu. Pasakiet, kurš lauks to norāda.

Neizdevies POST netiek automātiski atkārtots, ja vien darbvietas administrators to neieslēdz, tieši tāpēc, ka atkārtots POST var nosūtīt divreiz. Ja varat droši pieņemt atkārtojumu, pasakiet to un palūdziet to ieslēgt. Ja atbalstāt idempotences atslēgu, pasakiet, kurā galvenē to vēlaties.

Pasakiet administratoram, kur ir jūsu kļūdas ziņojums. Kad jūsu sistēma sūtījumu noraida, palaišana rāda jūsu pašu ziņojumu, ja administrators norāda, kur tas atrodas (piemēram, body.message). Citādi tā rāda jūsu statusa kodu un atbildes sākumu. Kad cēlonis novērsts, neizdevušos sūtījumu var nosūtīt vēlreiz no soļa, kas neizdevās, neatkārtojot iepriekšējos soļus.

Lieli saraksti un ātruma ierobežojumi. Ja vienā pieprasījumā pieņemat ne vairāk kā noteiktu ierakstu skaitu vai minūtē ne vairāk kā noteiktu pieprasījumu skaitu, pasakiet to. Finpilo var sadalīt sarakstu daļās un sūtīt pieprasījumus jūsu ātrumā.

Aprēķinātas vērtības saturā

Sūtīšanas soļa saturs ir JSON veidne. Lielākā daļa vērtību tiek kopētas no dokumenta ar {{path}} — {{subject.documentNumber}}, {{subject.totalExcludingTax}}. Ja jūsu sistēmai vajag kaut ko, kā dokumentā nav, vērtību var arī aprēķināt, tāpēc starp Finpilo un jums nekam nav jāatrodas.

Jebkurā vietā, kur iet vērtība, ir pieejamas sešas formas:

• "{{path}}" kopē vērtību. "{{path?}}" pieļauj, ka tās nav.
• {"$map": {"from": "subject.lineItems", "as": { ... }}} pārveido sarakstu, katra rinda ir item. Pievienojiet "groupBy": ["taxRate"], lai sūtītu vienu elementu katrai rindu grupai ar vienādu vērtību, piemēram, vienu rindu katrai PVN likmei. Grupas pirmā rinda ir item, visas tās rindas ir lines, tāpēc {"$value": {"aggregate": {"op": "sum", "over": {"var": "lines"}, "field": "totalExcludingTax"}}} ir grupas kopsumma. Rindas bez vērtības veido savu grupu. Pats dokuments nemainās. Pievienojiet "sortBy": ["account", {"path": "totalExcludingTax", "order": "desc"}], lai rindas sūtītu šādā secībā (augošā, ja vien nav norādīts desc). Rindas bez vērtības nonāk beigās. Grupas iekšienē $map ar "from": "lines" uzskaita šīs grupas rindas.
• {"$value": <operands>} aprēķina vienu.
• {"$csv": {"rows": <$map>, "separator": ";", "header": true}} uzraksta rindas kā vienu CSV tekstu: pirmās rindas kolonnas, vērtība ar atdalītāju, pēdiņām vai rindas pārnesumu tiek likta pēdiņās.
• {"$lines": <tekstu $map>} savieno rindas vienā tekstā. Fiksēta platuma failam katru rindu veidojiet ar pad un truncate līdz tās platumiem.

Sistēmai, kas failus importē, nevis pieņem izsaukumus, Finpilo var ievietot failu (CSV, fiksēta platuma vai XML tekstu, vai paša dokumenta PDF) jūsu SFTP mapē. Pirms sūtīšanas tas pārbauda servera identitāti un nekad nepārraksta failu, kas tur jau ir. Lūdziet savu Finpilo kontaktpersonu to iestatīt.

• {"$xml": { ... }} uzraksta mezglu kā XML virkni, nevis JSON, sistēmai, kurai vajag XML. Var aptvert visu saturu vai tikai vienu JSON lauku. Sūtot to kā visu saturu, solim jāiestata arī Content-Type galvene (piemēram, application/xml). Bez tās saturs aizies kā vienkāršs teksts.

Operands ir literālis, {"var": "path"}, agregāts vai kāda no šīm operācijām:

Nosacījumi izmanto eq, ne, gt, gte, lt, lte, in, contains, empty, on (on = viena un tā pati kalendārā diena), apvienojot ar and, or, not, any, all.

Piemēram, tikai viena izmaksu centra rindu kopsumma:

{ "ccTotal": { "$value": { "aggregate": {
    "op": "sum", "over": { "var": "subject.lineItems" }, "field": "totalExcludingTax",
    "where": { "eq": [ { "var": "dimensions.cost_centre.code" }, "CC-100" ] } } } } }

Pieejamie ceļi ir paša dokumenta lauki (subject.supplierName, subject.lineItems[].totalExcludingTax, subject.dimensions.<dimensijas atslēga>.code), iepriekšēja soļa atbilde outputs.<soļa id>.body un saņemts webhook saturs input.webhook. Norādiet dimensiju ar tās atslēgu. Atslēga nemainās, bet dimensijas nosaukums vairs neatbilst, tiklīdz kāds dimensiju pārdēvē.

Vietas, kur kartējums parasti aiziet greizi:

• mode ir obligāts visam, kas dala vai noapaļo — half-up, half-even, up (uz augšu) vai down (uz leju). places ir 0–28. Finpilo neizvēlas noapaļošanas noteikumu jūsu vietā.
• format ir .NET datuma šablons — yyyy-MM-dd, nevis YYYY-DD. Neatpazīts burts tiek nodots tālāk kā teksts.
• {{token}} neatrisinās operanda iekšienē. Tur izmantojiet {"var": "path"}.
• coalesce izlaiž null, bet ne tukšu virkni.
• Ceļš, kura nav, aptur soli, nevis sūta tukšumu — tāpat kā dalīšana ar nulli, nenolasāms datums vai lookup bez atbilstības un bez noklusējuma.
• sum vai count, kura where neatbilst nekam, atbild ar nulli un to nosūta. (avg, min un max pār tukšumu atbildes nav, tāpēc tie aptur soli.) Nepareizi uzrakstīts ceļš where iekšienē izskatās tieši tāpat kā patiesi tukša kopa. Ceļi ir reģistrjutīgi, un dimensijas nosaukums zaudē punktu (Dept. code nolasās kā dimensions.Dept code.code). Pārbaudiet to pret īstu dokumentu un nolasiet skaitli.

AI asistents, kas pievienots darbvietai, var tos uzbūvēt un pārbaudīt jūsu vietā — skatiet AI asistenti.

Finpilo sūtītās galvenes

Katrs nosūtīšanas pieprasījums ietver:

Content-Type: application/json

kā arī autentifikācijas galveni no galamērķa: Authorization: Bearer <token> Bearer autentifikācijai, Authorization: Basic <akreditācijas dati> Basic autentifikācijai, OAuth piekļuves pilnvaru ar jūsu norādīto shēmu vai jūsu nosaukto pielāgoto galveni. Galamērķis ar No auth nesūta autentifikācijas galveni.

Divas uzvedības, ko vērts ņemt vērā. Pāradresācijas netiek sekotas, tāpēc 301 vai 302 no jums tiek uzskatīts par kļūmi — norādiet galīgo adresi. Un Finpilo izsauc tikai adreses, kas sasniedzamas publiskajā internetā. Privāta, iekšēja vai loopback adrese tiek noraidīta pirms pieprasījuma.

Kļūdu atbildes

403 ir četri dažādi iemesli un četri dažādi risinājumi, tāpēc lasiet ziņojumu, nevis kodu:

• API & AI piekļuve darbvietai ir izslēgta. To ieslēdz administrators.
• Darbvietas pakalpojums ir apturēts — neapmaksāts vai beidzies abonements. Katrs izsaukums tiek noraidīts, līdz tas ir nokārtots. Ja sinhronizācija vakar strādāja, bet šodien visur atbild ar 403, parasti iemesls ir šis.
• Atslēgai trūkst atļaujas. Izveidojiet vai izlabojiet atslēgu ar to, kas vajadzīgs.
• Cilvēka loma to neatļauj. Izsaukums ar cilvēka pieteikšanos var darīt tikai to, ko atļauj šī cilvēka loma lietotnē. Lomu maina administrators cilnē People.
• Galapunktam vajadzīga cilvēka pieteikšanās — apstiprinājumi, konfigurācija, entītijas, lietotāji. To nevar neviena atslēga.

Lielākā daļa kļūdu izmanto formu { "error": "apraksts" }. Kļūdas, kas rodas dziļāk servisa slānī, tostarp katrs 409, izmanto formu { "status", "code", "message", "errors" }, tāpēc lasiet abas. 401 satura nav vispār, jo neviens vēl nav sevi identificējis.