EN
Ultima actualizare

Conectarea Business Central on-premises

Ghid pentru administratori — cum pregătești un Business Central on-premises pentru agentul de sincronizare Magic CRM ș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 în rețeaua ta. Ghidul acesta este pentru Business Central on-premises: rulează pe un server al tău sau al partenerului tău, la o adresă de genul https://bc.example.ro/BC. Pentru Business Central online, vezi Business Central online.

Agentul se autentifică în Business Central ca un utilizator Business Central, cu cheia de acces la serviciile web a acelui utilizator. Nu trebuie deschis nimic spre internet: agentul face doar conexiuni HTTPS de ieșire, către Business Central și către Magic CRM. Instalat chiar pe serverul Business Central, nu are nevoie de niciun port deschis. Datele de acces la Business Central rămân în configurația agentului, pe serverul tău; Magic CRM nu le vede niciodată.

Ce schimbă sincronizarea este descris în Ce trimite sincronizarea cu Business Central.

Înainte să începi

  • Pașii 1–3 îi face cine administrează serverul Business Central, de obicei partenerul tău, în Business Central Administration Shell, ca administrator. BC de mai jos este numele instanței de server; al tău poate fi altul.
  • Pașii 4 și 5 se fac în clientul Business Central, de un administrator Business Central.
  • Restul are nevoie de un proprietar sau administrator al organizației tale din Magic CRM și de un administrator al calculatorului Windows pe care va rula agentul, de obicei chiar serverul Business Central.

La final vei avea patru valori: adresa API (de exemplu https://bc.example.ro:7048/BC/api/v2.0), ID-ul companiei, un nume de utilizator și cheia de acces la serviciile web a acelui utilizator.

Agentul funcționează cu servere single-tenant. Dacă clientul web Business Central te lasă să intri doar cu ?tenant=… în adresă, serverul este multi-tenant și încă nu poate fi sincronizat.

1. Verifică cum se autentifică instanța

Get-NAVServerConfiguration BC | Where-Object { $_.key -in 'ClientServicesCredentialType','ODataServicesEnabled','ApiServicesEnabled','ODataServicesPort','ODataServicesSSLEnabled','PublicODataBaseUrl' }

ClientServicesCredentialType hotărăște totul:

  • NavUserPassword: continuă.
  • Windows: agentul nu se poate autentifica așa. Nu schimba tipul pe instanța pe care o folosesc oamenii, pentru că asta schimbă felul în care se autentifică fiecare utilizator. Soluția obișnuită este o a doua instanță de server pe aceeași bază de date, setată pe NavUserPassword și folosită doar de API. Decizia îi aparține partenerului tău.
  • Orice altceva: oprește-te și spune-ne ce este, la [YOUR SUPPORT CONTACT].

2. Pornește API-ul

Set-NAVServerConfiguration BC -KeyName ODataServicesEnabled -KeyValue true
Set-NAVServerConfiguration BC -KeyName ApiServicesEnabled   -KeyValue true
Set-NAVServerConfiguration BC -KeyName ODataServicesSSLEnabled -KeyValue true   # necesită un certificat pe instanță
Restart-NAVServerInstance BC
  • Portul este 7048, dacă ODataServicesPort nu spune altceva. Permite-l în Windows Firewall doar de pe calculatorul agentului. Dacă agentul rulează chiar pe serverul Business Central, nu trebuie deschis nimic.
  • Folosește TLS. Fără el, cheia de acces trece prin rețea în clar. Agentul refuză HTTP necriptat către alt calculator, dacă nu i se spune altfel; HTTP necriptat către același calculator este permis, încă un motiv să instalezi agentul pe serverul Business Central.
  • Un API oprit răspunde cu 405.

3. Populează tabelele API-ului

În clientul Business Central, caută API Setup și alege Integrate APIs. Rulează o singură dată și poate dura câteva minute. Până nu a rulat, API-ul răspunde cu liste goale.

4. Creează utilizatorul sincronizării

În clientul Business Central, Alt+Q (sau lupa) → Users → + New:

  1. Un utilizator separat, de exemplu CRMSYNC, nu contul unei persoane. Are nevoie de licență, ca orice utilizator care se autentifică cu o cheie. Folosește în nume doar litere și cifre, fără diacritice: metoda de autentificare nu poate transmite altceva. Dă-i o parolă și pune State pe Enabled.

  2. Seturi de permisiuni, în User Permission Sets pe aceeași fișă, cu Company lăsat gol. 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

    Pentru prima rulare, doar de citire: D365 BASIC și D365 READ. Ca să-i permiți mai târziu să scrie: D365 BUS FULL ACCESS în locul lui D365 READ, sau seturi mai restrânse, ale căror nume le știe partenerul tău. O scriere eșuează atunci vizibil în Magic CRM, în loc să modifice un client, iar citirile sunt cele care trebuie verificate mai întâi. Prin sincronizare nu se șterge niciodată nimic.

  3. Deconectează-te și autentifică-te ca acel utilizator. Deschide-i fișa din Users și, la Web Service Access, alege Web Service Access Key → Key Never Expires (sau o dată pe care o vei ține minte) → OK. Copiază cheia acum: oricărui alt utilizator îi este afișată ca asteriscuri.

O parolă pierdută, inclusiv a administratorului, se resetează din Administration Shell: Get-NAVServerUser BC listează utilizatorii, iar Set-NAVServerUser BC -UserName <nume> -Password (Read-Host -AsSecureString) setează una.

5. Găsește ID-ul companiei și verifică că funcționează

De pe calculatorul pe care va rula agentul (în Windows PowerShell scrie curl.exe, nu curl):

curl -u 'CRMSYNC:<cheie de acces>' 'https://bc.example.ro:7048/BC/api/v2.0/companies'

Răspunsul listează toate companiile, fiecare cu id-ul ei. Un agent sincronizează o singură companie: ia ID-ul celei de sincronizat și cere un client:

curl -u 'CRMSYNC:<cheie de acces>' 'https://bc.example.ro:7048/BC/api/v2.0/companies(<id>)/customers?$top=1'
Răspuns Înseamnă
200 și un client Gata: ai cele patru valori
401, Authentication_InvalidCredentials Numele de utilizator sau cheia sunt greșite (cel mai des numele), sau instanța nu este pe NavUserPassword
405 Pasul 2 nu a avut efect sau instanța nu a fost repornită
200 cu "value": [] Pasul 3 nu a rulat sau compania nu are clienți
Niciun răspuns Portul, firewallul sau certificatul

6. 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 Business Central”. 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.

7. Instalează agentul pe Windows

Pe un calculator Windows din rețeaua care ajunge la Business Central, de obicei chiar serverul Business Central:

  1. 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.
  2. Rulează programul de instalare. Îți cere un singur lucru, portul paginii de configurare: 7050, dacă nu îl folosește deja alt program.
  3. 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:
    1. Pairing: lipește codul.
    2. The ERP: adresa API, ID-ul companiei, utilizatorul și cheia lui.
    3. Check: ambele rânduri trebuie să aibă bifă.
  4. 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               # cere adresa, compania, utilizatorul și cheia
.\agent.exe status                  # ambele rânduri trebuie să spună ok

Pentru un server pe HTTP necriptat, adresa se poate da prin parametri; cheia este cerută în continuare, ca să nu rămână în istoricul consolei: .\agent.exe configure -allow-http -base-url http://<host>:7048/BC/api/v2.0 -company <id> -user CRMSYNC

8. Înainte de prima sincronizare

  1. 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.
  2. 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 un utilizator doar de citire în Business Central, orice scriere încercată eșuează, cum e normal.
  3. 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.
  4. 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ă utilizatorului sincronizării seturile de permisiuni de scriere în Business Central.

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ă
answered 401 to GET /customers Utilizatorul sau cheia
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.
  • O cheie de acces nouă: introdu-o la The ERP pe pagina de configurare.
  • 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.