Conectarea Business Central online
Ghid pentru administratori — cum permiți agentului de sincronizare Magic CRM să ajungă la Business Central online și cum instalezi agentul pe un server Windows.
Magic CRM se sincronizează cu Business Central printr-un program mic, agentul de sincronizare, pe care îl instalezi pe un calculator al tău. Ghidul acesta este pentru Business Central online: îl deschizi la https://businesscentral.dynamics.com/… cu un cont Microsoft. Pentru un Business Central pe un server al tău sau al partenerului tău, vezi Business Central on-premises.
Agentul se autentifică în Business Central ca o aplicație înregistrată în Microsoft Entra. Nu trebuie deschis nimic spre internet: agentul face doar conexiuni HTTPS de ieșire, către Business Central, către serviciul de autentificare Microsoft și către Magic CRM. Datele de acces la Business Central rămân în configurația agentului, pe calculatorul tău; Magic CRM nu le vede niciodată.
Ce schimbă sincronizarea este descris în Ce trimite sincronizarea cu Business Central.
Înainte să începi
Ai nevoie de drepturile a doi administratori, care pot fi aceeași persoană:
- În Microsoft Entra: Global Administrator, Privileged Role Administrator sau (Cloud) Application Administrator, în directorul în care se află Business Central.
- În Business Central: dreptul de a adăuga aplicații Microsoft Entra și de a le da seturi de permisiuni.
- În Magic CRM: proprietar sau administrator al organizației.
La final vei avea cinci valori: adresa API, ID-ul companiei, ID-ul tenantului, ID-ul aplicației (client) și un secret de client.
1. Înregistrează o aplicație în Microsoft Entra
În portalul Azure, ca administrator al directorului în care se află Business Central:
- Microsoft Entra ID → App registrations → New registration. Dă-i un nume, de exemplu Magic CRM sync, și alege Accounts in this organizational directory only. La Redirect URI, alege Web și introdu
https://businesscentral.dynamics.com/OAuthLanding.htm. Agentul nu îl folosește, dar butonul Grant Consent din Business Central, de la pasul 2, nu funcționează fără el. - Din pagina de prezentare, notează Application (client) ID și Directory (tenant) ID.
- API permissions → Add a permission → Dynamics 365 Business Central → Application permissions → API.ReadWrite.All → Add. Asta îi permite aplicației să ceară acces; ce poate atinge se hotărăște la pasul 2.
- Tot în API permissions, alege Grant admin consent for tenantul tău. Coloana Status arată apoi o bifă verde. Dacă butonul e inactiv, contul tău nu are rol de administrator în acest director, chiar dacă deține abonamentul Business Central: verifică Users → utilizatorul tău → Assigned roles și verifică, în dreapta sus, că ești în directorul potrivit și nu ca invitat.
- Certificates & secrets → New client secret. Copiază acum Value (nu Secret ID): este afișat o singură dată. Notează când expiră: în ziua aceea sincronizarea se oprește, iar jurnalul agentului spune că secretul a expirat.
2. Primește aplicația în Business Central
În Business Central (întâi într-un mediu sandbox, dacă ai unul), caută Microsoft Entra Applications și alege New:
-
Client ID: ID-ul aplicației de la pasul 1, plus o descriere. Lasă deocamdată State pe Disabled.
-
Adaugă seturi de permisiuni în tabelul User Permission Sets de pe aceeași fișă, câte un rând pentru fiecare set. Tabelul poate fi modificat doar cât timp State este Disabled. Dă doar ce atinge sincronizarea:
Sincronizarea Are nevoie de citește și scrie clienți, contacte citește și creează la cerere articole, oferte de vânzare citește comenzi de vânzare cu liniile lor, intrări în registrul de articole De obicei se pornește de la
D365 BASICplus seturile pentru clienți, articole și documente de vânzare; numele exacte diferă după versiune și localizare. Prin sincronizare nu se șterge niciodată nimic.Pentru prima rulare, dă doar permisiuni de citire. O scriere încercată de sincronizare eșuează atunci vizibil în Magic CRM, în loc să modifice un client, iar citirile sunt cele care trebuie verificate mai întâi.
-
Pune State pe Enabled și acceptă mesajul că se creează un utilizator pentru aplicație. O aplicație nu are nevoie de licență de utilizator.
-
Alege Grant Consent din partea de sus a fișei. Un administrator al directorului se autentifică și acceptă, iar Business Central confirmă acordul. Eroarea
AADSTS500113: No reply address is registeredînseamnă că lipsește Redirect URI de la pasul 1.
3. Găsește mediul și compania
- Mediul apare în bara de adrese a Business Central, după ID-ul tenantului:
…/<tenant id>/<mediu>?company=…. Când între ID-ul tenantului și?company=nu e nimic, este mediul implicit, de obiceiProduction. Numele exacte sunt la Environments, în centrul de administrare Business Central. - Adresa API este atunci
https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<mediu>/api/v2.0. - ID-ul companiei: un agent sincronizează o singură companie. Ca să vezi companiile cu ID-urile lor și să verifici că totul funcționează, de pe orice calculator cu
curlșijq:
TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token" \
-d grant_type=client_credentials \
-d client_id=<client id> \
--data-urlencode client_secret=<client secret> \
-d scope=https://api.businesscentral.dynamics.com/.default | jq -r .access_token)
BASE="https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<mediu>/api/v2.0"
curl -H "Authorization: Bearer $TOKEN" "$BASE/companies"
curl -H "Authorization: Bearer $TOKEN" "$BASE/companies(<id companie>)/customers?\$top=1"
| Răspuns | Înseamnă |
|---|---|
TOKEN este null |
Tenant, ID de aplicație sau secret greșit. Rulează prima comandă fără | jq și citește error_description |
AADSTS700016: Application … was not found in the directory |
Unul dintre cele două ID-uri e greșit. Client ID trebuie să fie Application (client) ID, nu Object ID sau Secret ID; tenantul trebuie să fie cel din bara de adrese a Business Central |
401 de la Business Central |
Pasul 2 nu a fost făcut în acest mediu sau aplicația nu este Enabled |
403 sau o eroare care numește o permisiune |
Seturile de permisiuni nu acoperă acel tip de înregistrare |
404 |
Numele mediului sau ID-ul companiei |
200 și un client |
Partea din Business Central este gata |
4. Obține un cod de asociere
În Magic CRM, ca proprietar sau administrator: Admin → ERP, apoi Conectează (o singură dată pentru organizație), apoi Adaugă un agent. Denumește-l după locul unde rulează, de exemplu „serverul contabilității”. Copiază codul de asociere: este afișat o singură dată și funcționează pentru o singură asociere. Dacă îl pierzi, revocă acel agent și adaugă altul.
5. Instalează agentul pe Windows
Agentul rulează pe orice calculator cu acces HTTPS de ieșire. Pe un server Windows:
- Pe aceeași pagină, Admin → ERP, alege Descarcă agentul pentru Windows. Este un program de instalare MSI. Verifică-l cu SHA-256-ul afișat pe pagină, în PowerShell:
Get-FileHash .\<fișier>.msi -Algorithm SHA256. - Rulează programul de instalare. Îți cere un singur lucru, portul paginii de configurare: 7050, dacă nu îl folosește deja alt program.
- Din meniul Start, deschide Configure Magic CRM Agent. Windows cere permisiunea unui administrator, iar pagina se deschide în browser, accesibilă doar de pe acest calculator:
- Pairing: lipește codul.
- The ERP: adresa API, ID-ul companiei, ID-ul tenantului, ID-ul aplicației și secretul ei.
- Check: ambele rânduri trebuie să aibă bifă.
- Lasă deocamdată The service oprit, până după verificările de mai jos.
Agentul se instalează în C:\Program Files\Magic CRM Agent și rulează ca serviciul Windows Magic CRM Agent, care pornește odată cu Windows și este repornit dacă se oprește. Folderul lui este închis pentru toți în afară de administratori și de serviciul însuși, iar secretele lui sunt criptate, astfel încât o copie a fișierului de configurare nu poate fi folosită pe alt calculator.
Fără interfață grafică, sau pe mai multe servere, programul de instalare rulează silențios: msiexec /i .\<fișier>.msi /qn (adaugă UI_PORT=7051 pentru alt port). Apoi, într-un PowerShell pornit ca administrator, în folderul de instalare:
.\agent.exe pair <cod> # asociază agentul cu organizația ta
.\agent.exe configure -auth oauth # cere adresa, compania, tenantul, ID-ul aplicației și secretul
.\agent.exe status # ambele rânduri trebuie să spună ok
6. Înainte de prima sincronizare
- Verifică opțiunile din Admin → ERP → Conexiune, care hotărăsc ce poate scrie prima sincronizare:
- Companiile noi devin clienți în ERP ar trebui să fie oprită la început: contabilul tău hotărăște mai întâi ce primește un client nou în Business Central.
- Clienții pe care ERP-ul îi are și noi nu devin companii aici este pornită implicit: prima sincronizare face o companie din fiecare client al tău care nu corespunde niciunei companii din Magic CRM.
- Rulează o tură manual:
.\agent.exe onceîn folderul de instalare, apoi uită-te în Admin → ERP → Activitate la rulare și la sarcinile ei. Cu permisiuni doar de citire în Business Central, orice scriere încercată eșuează, cum e normal. - Pornește-l: Start pe pagina de configurare sau
Start-Service MagicCRMAgent. În cel mult un minut, Admin → ERP arată agentul ca văzut și de atunci pornește odată cu calculatorul. - Clienții al căror nume corespunde unei companii de-ale tale așteaptă în Admin → ERP → Te așteaptă. Nu li se întâmplă nimic până nu răspunde cineva.
Când citirile sunt în regulă, dă aplicației permisiunile de scriere în Business Central (pune State pe Disabled, schimbă seturile de permisiuni, apoi din nou Enabled).
Când ceva nu merge
Ce spune status, sau Check de pe pagina de configurare, când rândul pentru Business Central eșuează:
| Mesaj | Înseamnă |
|---|---|
the sign-in service refused the application, with 401: invalid_client … |
Tenantul, ID-ul aplicației sau secretul; cuvintele Microsoft de după spun care |
answered 401 to GET /customers |
Aplicația nu este în Microsoft Entra Applications pentru acel mediu |
| Niciun status | Business Central nu poate fi accesat de pe acest calculator |
O sarcină refuzată de Business Central apare ca Eșuată în Admin → ERP → Activitate, cu mesajul Business Central. O sarcină care nu a reușit după cinci încercări este Oprită. Reîncearcă le repune pe amândouă în coadă.
Actualizare, oprire și dezinstalare
- Actualizare: rulează noul program de instalare. Configurația și portul se păstrează, iar serviciul este pornit din nou.
- Oprire oricând, cu Stop pe pagina de configurare sau
Stop-Service MagicCRMAgent: nu se pierde nimic și nimic nu se aplică de două ori. Modificările făcute între timp în Magic CRM așteaptă și pleacă atunci când agentul revine. - Dezinstalare: dezinstalează Magic CRM Agent din Settings → Apps în Windows. Configurația și jurnalele se păstrează, cu excepția cazului în care dezinstalarea este rulată cu
PURGE=1. Apoi alege Revocă lângă agent în Admin → ERP, ceea ce îi încheie accesul imediat.