Integrations

Finpilo var nosūtīt validētus dokumentus tieši uz jūsu grāmatvedības sistēmu, izmantojot webhook. Tā vietā, lai eksportētu failus manuāli, dokumenta dati tiek nodoti automātiski, kad noklikšķināt Send pogu validētā dokumentā.

Šī lapa apraksta, kā konfigurēt webhook darbvietas un entītijas līmenī.

Kā webhook darbojas

Webhook ir URL jūsu grāmatvedības sistēmā, kas pieņem ienākošos dokumenta datus JSON formātā. Kad Finpilo dokumentā noklikšķināt Send, notiek sekojošais:

1. Finpilo izveido JSON datus ar visu dokumenta informāciju — galvenes laukiem, rindas pozīcijām, dimensijām un URL oriģinālā faila lejupielādei.
2. Finpilo veic HTTP POST pieprasījumu uz jūsu webhook URL ar šiem datiem.
3. Jūsu grāmatvedības sistēma saņem datus, izveido ierakstu savā datubāzē un neobligāti atgriež grāmatvedības atsauces ID atbildes ziņojumā.
4. Ja atsauces ID tiek atgriezts, Finpilo to saglabā dokumentā un attēlo dokumenta galvenē.

Oriģinālais fails netiek iekļauts webhook datos. Tā vietā dati satur fileUrl lauku, kas norāda uz Finpilo faila lejupielādes galapunktu. Jūsu sistēma var iegūt failu, izmantojot to pašu API atslēgu, ja nepieciešams.

Skatiet External API, lai iegūtu pilnu webhook datu formātu.

Webhook izšķirtspējas secība

Finpilo pārbauda divus webhook konfigurācijas līmeņus, sūtot dokumentu:

1. Entītijas webhook — ja entītijai ir iespējots pielāgots webhook ar URL, tas tiek izmantots.
2. Darbvietas webhook — ja entītijai nav pielāgota webhook, tiek izmantots darbvietas līmeņa webhook.

Ja nav konfigurēts neviens, Send poga dokumenta skatā ir pilnīgi paslēpta. Jūs nevarat sūtīt dokumentus no entītijas vai darbvietas bez webhook.

Svarīgs izņēmums: Ja entītijai ir ieslēgts "Use custom outbound webhook", bet URL nav iestatīts, dokumenta nosūtīšana neizdodas ar skaidru kļūdas ziņojumu — tā automātiski nepāriet uz darbvietas webhook. Tas ir apzināti izstrādāts tā, lai novērstu dokumentu nosūtīšanu uz nepareizu sistēmu.

Darbvietas webhook konfigurēšana

Nepieciešama Admin vai Owner loma.

Darbvietas webhook ir noklusējuma webhook visām entītijām, kurām nav sava pielāgota webhook.

1. Navigējiet uz Workspace Settings → API cilni.
2. Sadaļā Workspace Webhook ievadiet Webhook URL — jūsu grāmatvedības sistēmas webhook galapunkta adresi.
3. Ja jūsu webhook prasa autentifikāciju, ievadiet API Key. Finpilo to nosūtīs kā Bearer token Authorization galvenē katrā pieprasījumā.
4. Ieslēdziet Webhook enabled slēdzi.
5. Noklikšķiniet Save.

API Key lauks vienmēr ir tukšs, kad atverat lapu. Atstājiet tukšu, lai saglabātu esošo atslēgu, vai ievadiet jaunu vērtību, lai to aizstātu.

Entītijas webhook konfigurēšana

Nepieciešama Admin vai Owner loma.

Izmantojiet entītijas līmeņa webhook, kad konkrētai entītijai jāsūta uz citu grāmatvedības sistēmu nekā pārējai darbvietai.

1. Navigējiet uz Entity Management un noklikšķiniet uz entītijas.
2. Atlasiet cilni Integrations.
3. Ieslēdziet slēdzi Use custom outbound webhook.
4. Ievadiet Webhook URL.
5. Ja nepieciešama autentifikācija, ievadiet API Key.
6. Ieslēdziet slēdzi Webhook enabled zemāk, lai aktivizētu sūtīšanu.
7. Noklikšķiniet Save.

Izslēdzot Use custom outbound webhook un saglabājot, entītija atgriežas pie darbvietas webhook izmantošanas. Slēdža izslēgšana bez saglabāšanas atmet visas nesaglabātās izmaiņas.

Webhook pārbaude

Vienkāršākais veids, kā pārbaudīt webhook, ir validēt dokumentu un noklikšķināt Send:

• Ja nosūtīšana ir veiksmīga, dokumenta statuss mainās uz Sent un galvenē parādās laika zīmogs.
• Ja nosūtīšana neizdodas, parādās kļūdas ziņojums. Biežākās kļūdas:
  • Webhook URL atgrieza HTTP kļūdu.
  • Pieprasījumam iestājies noildzis (Finpilo gaida 30 sekundes uz atbildi).
  • Nav konfigurēts webhook vai entītijas webhook ir ieslēgts bez URL.

Grāmatvedības atsauces ID

Ja jūsu webhook galapunkts atgriež JSON datus, kas satur vienu no laukiem accountingReferenceId, AccountingReferenceId vai id, Finpilo saglabā šo vērtību dokumentā kā atpakaļatsauci uz ierakstu jūsu grāmatvedības sistēmā.

Webhook atbildes piemērs:

{
  "accountingReferenceId": "INV-2026-0042"
}

Atsauces ID tiek attēlots dokumenta galvenē kā Ref: INV-2026-0042. Tas ļauj ātri atrast attiecīgo ierakstu ārējā sistēmā.

Grāmatvedības atsauces ID atgriešana ir neobligāta. Tukšs 200 OK atbildes ziņojums arī ir derīgs.

Drošība

• API atslēgas tiek šifrētas glabāšanas laikā.
• Pilnā webhook API atslēga nekad netiek parādīta pēc saglabāšanas — tiek rādīts tikai maskēts vietturis.
• Webhook pieprasījumi vienmēr tiek sūtīti caur HTTPS. Konfigurējiet savu galapunktu ar derīgu HTTPS sertifikātu.