Webhook-uri (de ieșire)

Webhook-urile sunt jumătatea «push» a integrărilor: în loc ca sistemul dvs. să interogheze FreeMaint, FreeMaint trimite un POST către URL-ul dvs. imediat ce se întâmplă ceva. Se configurează din Setări companie > Webhook-uri (/company-settings/webhooks). Disponibile de la pachetul Starter (100 livrări/zi; nelimitat de la Business).

Evenimente disponibile

• work_order.created — a fost creată o comandă de lucru
• work_order.completed — o comandă de lucru a trecut în Finalizată
• work_order.status_changed — o comandă de lucru a trecut în orice stare; payload-ul conține new_status. Se declanșează pe lângă work_order.completed, care rămâne neschimbat
• request.created — a fost trimisă o solicitare de mentenanță
• request.status_changed — o solicitare a fost aprobată, respinsă sau anulată
• part.low_stock — o piesă a scăzut la pragul de reaprovizionare sau sub acesta
• part.out_of_stock — o piesă a ajuns la zero
• part.low_stock_summary — un rezumat zilnic pe companie cu piesele aflate la pragul de reaprovizionare sau sub acesta, inclusiv cele care nu s-au mișcat niciodată
• part.out_of_stock_summary — același rezumat zilnic, pentru piesele ajunse la zero
• part.consumed — o piesă a fost consumată pe o comandă de lucru sau returnată
• compliance.chain_divergence — lanțul de hash-uri de audit s-a rupt (Enterprise)
• asset.downtime_started — a fost deschisă o oprire de mașină
• asset.downtime_ended — a fost închisă o oprire de mașină; durata poate fi acum contabilizată
• report.daily_summary — lucrările finalizate ale zilei, o dată pe zi, la ora pe care o alegeți
• purchase_order.created — a fost creată o comandă de achiziție; conținutul poartă comanda (reference, status, total_cost, currency, expected_date, erp_reference) și furnizorul
• purchase_order.status_changed — o comandă de achiziție și-a schimbat starea (aprobată, comandată, anulată…); conținutul poartă previous_status și new_status
• purchase_order.received — a fost recepționată o livrare pe o comandă de achiziție (trimis la fiecare livrare, inclusiv parțială); încărcătura listează fiecare linie cu quantity_ordered, quantity_received (această livrare), quantity_received_total și quantity_remaining, plus receipt_id, fully_received și closed_short; new_status este PARTIALLY_RECEIVED cât timp se mai așteaptă marfă și RECEIVED când comanda este completă sau închisă

part.consumed — oglindirea stocului într-un ERP

Acesta este evenimentul la care vă abonați când un alt sistem (ERP, facturare, stocuri, contabilitate) trebuie să reflecte ce a consumat efectiv mentenanța. Câmpul quantity are semn: negativ când piesa iese către lucrare, pozitiv când este returnată prin scoaterea ei din comanda de lucru — astfel o stornare în FreeMaint produce documentul de retur corespunzător în celălalt sistem. Câmpul stock_movement_id rămâne stabil între reîncercări și retrimiteri: folosiți-l drept cheie de idempotență și nu veți înregistra niciodată de două ori aceeași ieșire. Un lucru de știut când traficul circulă în ambele sensuri: mutația GraphQL adjustStock NU declanșează acest eveniment. Este intenționat — o corecție de stoc pe care propriul dumneavoastră sistem o scrie în FreeMaint nu trebuie să vă revină ca un ecou și să fie înregistrată de două ori. Doar consumul înregistrat pe o comandă de lucru în FreeMaint generează part.consumed. Piesa conține și custom_reference: propriul dumneavoastră cod pentru ea, adică customReference setat prin createPart sau updatePart, astfel încât un sistem care gestionează catalogul să potrivească fiecare linie fără un tabel al ID-urilor FreeMaint.

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "Rulment 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "buc" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "Înlocuire rulment" }, "asset": { "id": 91, "name": "Separator 2" }, "location": { "id": 7, "name": "Depozit uzină" }, "user": { "id": 5627, "name": "A. Tehnician" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

Livrare și semnătură

Fiecare livrare este un POST cu corp JSON și un antet X-FreeMaint-Signature de forma t=<secunde unix>,v1=<hex>, unde v1 este HMAC-SHA256 al șirului «<t>.<corp brut>» cu cheia egală cu secretul webhook-ului dvs. Verificați pe corpul BRUT, înainte de orice parsare JSON sau reserializare. Trimitem și X-FreeMaint-Event și X-FreeMaint-Delivery-Id. Un 2xx marchează livrarea ca reușită; erorile de rețea și 5xx se reîncearcă de până la 3 ori cu retragere exponențială (aproximativ 2 s, 4 s, 8 s); un 4xx este tratat ca refuz definitiv și NU se reîncearcă.

Retrimiterea unei livrări

Fiecare încercare rămâne în istoricul de livrări al webhook-ului, cu starea și codul de răspuns. Orice livrare încheiată poate fi retrimisă de acolo: se retrimite exact aceeași sarcină utilă stocată, deci cheile de business din ea (inclusiv stock_movement_id) rămân identice, iar un receptor care deduplică corect nu va înregistra de două ori. Așa recuperați ce s-a pierdut cât timp endpoint-ul dvs. a fost căzut sau a respins o cerere din greșeală.

Fotografii (opțional)

Când „Include fotografii” este activat pe un webhook (dezactivat implicit), obiectele "work_order" și "request" conțin o listă "photos": până la 4 linkuri HTTPS către imagini JPG, PNG, GIF sau WebP, cele mai recente primele. Fiecare link deschide imaginea fără autentificare timp de 7 zile, așa că salvați fișierul la dumneavoastră dacă aveți nevoie de el mai mult timp. O retrimitere trimite aceleași linkuri. Celelalte evenimente și webhookuri nu se schimbă. Pentru "work_order.created" și "request.created", un webhook cu „Include fotografii” este trimis la 90 de secunde după eveniment (câmpul "timestamp" păstrează ora evenimentului), ca să includă fotografiile încărcate imediat după înregistrare.

Cerințe pentru URL

• Doar https:// — http simplu este respins
• Doar portul 443 sau 8443
• Gazda trebuie să fie accesibilă public — intervalele loopback, private și CGNAT sunt respinse
• Fără credențiale în URL (https://user:pass@host este respins)
• Un sistem care există doar în rețeaua dvs. internă are nevoie de un endpoint public sau de un releu (n8n, Make, Zapier) în față

Plafoane

• Starter — 100 livrări/zi per companie
• Business — nelimitat
• Enterprise — nelimitat
• Contorul numără încercările de livrare: trei webhook-uri abonate la același eveniment consumă trei unități
• Contorul zilnic se resetează la 00:00 UTC