Gravity Forms Teamleader Add‑On

Koppelt Gravity Forms inzendingen aan Teamleader Focus. Maakt optioneel een contact, bedrijf en/of deal aan op basis van een feed met veldenmapping en templates.

Vereisten

• WordPress + Gravity Forms
• Teamleader Focus OAuth2 client (Client ID/Secret)

Installatie & Configuratie

1. Activeer de plugin: Gravity Forms Teamleader Add-On.
2. Ga naar Forms > Settings > Teamleader en vul in:
   • Client ID en Client Secret
   • Redirect URI (gelezen uit de plugin; whitelist in Teamleader)
   • Optioneel: Standaard Pipeline ID voor deals
   • Optioneel: Debug logging
3. Klik “Connect met Teamleader” om OAuth te voltooien.

Feed instellen (per formulier)

• Ga naar Forms > (jouw formulier) > Settings > Teamleader en maak een feed aan.

• Kies acties: Contactpersoon, Bedrijf, Deal.

• Contact mapping:

  • Minimaal Achternaam vereist bij Contact aanmaken.
  • Optioneel: e‑mail, telefoons, adres.

• Bedrijf mapping:

  • Bedrijfsnaam en optioneel BTW, e‑mail, telefoons, website, adres.

• Deal

  • Deal titel (template) (deal_title_tpl): vrije tekst met merge tags (zie hieronder).
  • Koppel dealvelden: Deal waarde (€), Deal valuta.
  • Deal beschrijving (template) (deal_description_tpl): vrije tekst met merge tags.

Templates & Merge Tags

• Ondersteunt standaard GF merge tags (bv. {1}, {Field Label:1}, {all_fields}).
• Extra: eenvoudige {label_slug} tokens op basis van (sub)veldlabels; spaties en speciale tekens worden _.
• Voorbeelden:
  • Titel: Offerte {first_name} {last_name}
  • Beschrijving: Aantal: {aantal_deelnemers}\nOpmerking: {opmerking}

Validatiegedrag (frontend)

• De plugin valideert voor feed‑processing en toont fouten in het formulier:
  • Telefoon (vast/mobiel, contact en bedrijf)
    • Genormaliseerd naar internationaal formaat; vereist uiteindelijk E.164 (+ en 8–15 cijfers).
    • Tip: map het landveld zodat nationale nummers automatisch een landcode krijgen.
  • BTW‑nummer (bedrijf)
    • Basisland‑specifieke checks (BE, NL, DE, FR, IT, ES), anders een generieke controle.
• Bij validatiefouten: inzending faalt en er wordt niets naar Teamleader verzonden.

Performance & asynchrone verwerking

• Feeds worden asynchroon verwerkt (is_asynchronous = true).
  • Resultaat: het formulier kan direct bevestigen/redirecten en notificaties versturen.
  • De Teamleader‑calls draaien op de achtergrond via de Gravity Forms background process (WP‑Cron).
• Fouten tijdens de achtergrondtaak worden gelogd (Debug logging inschakelen voor details).

Fouten & notificaties

• Bij blijvende API-fouten (na soft-fail pogingen) ontvangt de site‑admin een e‑mail met context (formulier, feed, entry, foutmelding).

Fallbacks & API‑gedrag

• Soft‑fail BTW: als Teamleader vat_number afkeurt, wordt automatisch opnieuw geprobeerd zonder vat_number zodat de flow doorgaat.
• Soft‑fail Telefoon: als Teamleader een telefoonnummer afkeurt, wordt opnieuw geprobeerd zonder telephones.
• Deal endpoint: deals.create met fallbacks naar deals.add en opportunities.add.
• Andere endpoints: contacts.add, contacts.update, contacts.list, companies.add, companies.list.

Logging

• Schakel Debug logging in de plugininstellingen in.
• De plugin logt requests en responses (handig voor troubleshooting).

Tips voor testen

• Controleer feed‑acties en mappings met kleine tests (naam, e‑mail, land, telefoon, BTW).
• Let op E.164 formaat voor telefoons of map een landveld.
• Bij BTW‑issues: kijk naar de foutmelding; bij soft‑fail wordt btw niet meegestuurd.

Changelog (samenvatting)

• Nieuw: deal_title_tpl (vrije titel met merge tags, zelfde resolutie als beschrijving).
• Nieuw: frontend validatie voor telefoons en BTW met duidelijke foutmeldingen.
• Verbeterd: soft‑fail bij ongeldig vat_number (retry zonder btw).

Plugin updates (PUC)

Deze plugin kan updates ophalen via [YahnisElsts/plugin-update-checker]. We bundelen de lib niet; je kunt die installeren via Composer of handmatig.

1. Installeer de library in de plugin:

• Plaats plugin-update-checker.php onder: web/app/plugins/gravityformsteamleader/includes/plugin-update-checker/plugin-update-checker.php

2. Configureer constants (bijv. in config/application.php of wp-config.php):

   define('GFTL_UPDATER_REPO', 'https://github.com/your-org/your-repo');
   define('GFTL_UPDATER_BRANCH', 'main'); // optioneel
   define('GFTL_UPDATER_TOKEN', 'ghp_xxx'); // optioneel voor private repos

De plugin zoekt automatisch naar de PUC‑library en initialiseert updates op basis van de repo‑instellingen.

Onderdeel van Bedrock: pluginpad web/app/plugins/gravityformsteamleader.