[{"data":1,"prerenderedAt":630},["ShallowReactive",2],{"seite-\u002Fit\u002Fratgeber\u002Fbexio-api-wordpress\u002F":3},{"id":4,"title":5,"body":6,"description":621,"extension":622,"meta":623,"navigation":624,"path":625,"robots":626,"seo":627,"stem":628,"__hash__":629},"seiten_it\u002Fratgeber\u002Fbexio-api-wordpress.md","Collegare l’API di bexio a WordPress, guida con OAuth, token ed endpoint",{"type":7,"value":8,"toc":611},"minimark",[9,14,18,23,28,60,67,71,93,96,100,107,222,229,240,244,251,263,266,270,273,312,315,445,449,515,519,575,578,582,585,601,607],[10,11,13],"h1",{"id":12},"collegare-lapi-di-bexio-a-wordpress","Collegare l’API di bexio a WordPress",[15,16,17],"p",{},"Una richiesta dal modulo del sito deve arrivare in bexio come contatto, un ordine come fattura,\nun cliente del negozio come indirizzo. Per questo WordPress deve parlare con l’API di bexio.\nQuesta guida mostra il percorso dall’app nel Developer Portal al primo contatto creato, le\ninsidie lungo la strada e quando un plugin pronto conviene più di codice proprio.",[19,20],"produkt-ablauf",{":schritte":21,"titel":22},"[{\"ort\":\"Modulo del sito\",\"text\":\"Un visitatore invia una richiesta\"},{\"ort\":\"WordPress\",\"text\":\"Plugin o codice proprio con token\",\"eigen\":true},{\"ort\":\"auth.bexio.com\",\"text\":\"Token via OAuth 2, rinnovato regolarmente\"},{\"ort\":\"api.bexio.com\",\"text\":\"Cercare o creare il contatto, aggiungere una nota\"}]","Svolgimento: il modulo del sito invia la richiesta a WordPress, WordPress ottiene un token da auth.bexio.com e crea contatto e nota tramite api.bexio.com",[24,25,27],"h2",{"id":26},"che-cosè-lapi-di-bexio","Che cos’è l’API di bexio",[15,29,30,31,35,36,39,40,43,44,47,48,51,52,59],{},"L’API di bexio è un’interfaccia REST in JSON. Tutti gli endpoint si trovano sotto\n",[32,33,34],"code",{},"https:\u002F\u002Fapi.bexio.com",", i percorsi iniziano secondo l’ambito con ",[32,37,38],{},"\u002F2.0\u002F",", ",[32,41,42],{},"\u002F3.0\u002F"," o più recenti,\nper esempio ",[32,45,46],{},"\u002F2.0\u002Fcontact"," per i contatti e ",[32,49,50],{},"\u002F3.0\u002Fusers\u002Fme"," per l’utente connesso. Il riferimento\nè su ",[53,54,58],"a",{"href":55,"rel":56},"https:\u002F\u002Fdocs.bexio.com\u002F",[57],"nofollow","docs.bexio.com",". Secondo la sua documentazione, bexio non offre una\ndescrizione OpenAPI; un client si scrive quindi a mano.",[15,61,62,63,66],{},"Ogni accesso richiede un access token nell’intestazione ",[32,64,65],{},"Authorization: Bearer …",". Come WordPress\nottiene questo token è il vero lavoro.",[24,68,70],{"id":69},"passo-1-creare-unapp-nel-developer-portal","Passo 1: creare un’app nel Developer Portal",[72,73,74,84,87,90],"ol",{},[75,76,77,78,83],"li",{},"Accedere al ",[53,79,82],{"href":80,"rel":81},"https:\u002F\u002Fdeveloper.bexio.com\u002F",[57],"Developer Portal"," con l’account bexio.",[75,85,86],{},"Leggere e accettare le condizioni d’uso, in particolare la cifra 4.4 sull’uso commerciale\n(vedi le insidie).",[75,88,89],{},"Creare una nuova app e inserire l’URL di reindirizzamento a cui bexio rimanda dopo l’accesso,\nper esempio la pagina delle impostazioni del plugin nell’amministrazione WordPress. Sono\npossibili fino a dieci indirizzi, per esempio per test e produzione.",[75,91,92],{},"Leggere Client ID e Client Secret sotto «App Details».",[15,94,95],{},"Il Client Secret resta sul server, mai in JavaScript nel browser.",[24,97,99],{"id":98},"passo-2-accedere-con-oauth-2","Passo 2: accedere con OAuth 2",[15,101,102,103,106],{},"bexio gestisce l’accesso con OpenID Connect su ",[32,104,105],{},"auth.bexio.com",", con l’«Authorization Code Flow».\nWordPress manda l’utente alla pagina di accesso di bexio:",[108,109,114],"pre",{"className":110,"code":111,"language":112,"meta":113,"style":113},"language-bash shiki shiki-themes github-light github-dark","https:\u002F\u002Fauth.bexio.com\u002Frealms\u002Fbexio\u002Fprotocol\u002Fopenid-connect\u002Fauth\n  ?client_id=\u003CClient ID>\n  &redirect_uri=\u003CURL di reindirizzamento registrato>\n  &response_type=code\n  &scope=openid offline_access contact_edit note_edit\n  &state=\u003Cvalore casuale>\n","bash","",[32,115,116,125,149,175,186,206],{"__ignoreMap":113},[117,118,121],"span",{"class":119,"line":120},"line",1,[117,122,124],{"class":123},"sScJk","https:\u002F\u002Fauth.bexio.com\u002Frealms\u002Fbexio\u002Fprotocol\u002Fopenid-connect\u002Fauth\n",[117,126,128,131,135,139,142,145],{"class":119,"line":127},2,[117,129,130],{"class":123},"  ?client_id",[117,132,134],{"class":133},"sZZnC","=",[117,136,138],{"class":137},"sVt8B","\u003CClient ",[117,140,141],{"class":133},"I",[117,143,144],{"class":137},"D",[117,146,148],{"class":147},"szBVR",">\n",[117,150,152,155,158,161,164,167,170,173],{"class":119,"line":151},3,[117,153,154],{"class":137},"  &redirect_uri",[117,156,157],{"class":147},"=\u003C",[117,159,160],{"class":133},"URL",[117,162,163],{"class":123}," di",[117,165,166],{"class":133}," reindirizzamento",[117,168,169],{"class":133}," registrat",[117,171,172],{"class":137},"o",[117,174,148],{"class":147},[117,176,178,181,183],{"class":119,"line":177},4,[117,179,180],{"class":137},"  &response_type",[117,182,134],{"class":147},[117,184,185],{"class":133},"code\n",[117,187,189,192,194,197,200,203],{"class":119,"line":188},5,[117,190,191],{"class":137},"  &scope",[117,193,134],{"class":147},[117,195,196],{"class":133},"openid",[117,198,199],{"class":123}," offline_access",[117,201,202],{"class":133}," contact_edit",[117,204,205],{"class":133}," note_edit\n",[117,207,209,212,214,217,220],{"class":119,"line":208},6,[117,210,211],{"class":137},"  &state",[117,213,157],{"class":147},[117,215,216],{"class":133},"valore",[117,218,219],{"class":123}," casuale",[117,221,148],{"class":137},[15,223,224,225,228],{},"L’utente accede e conferma i diritti. bexio rimanda con un codice, che WordPress scambia, insieme\na Client ID e Secret, presso l’endpoint del token ",[32,226,227],{},"\u002Frealms\u002Fbexio\u002Fprotocol\u002Fopenid-connect\u002Ftoken","\ncon un access token e un refresh token.",[15,230,231,232,235,236,239],{},"Sugli scope: un diritto di scrittura include quello di lettura, quindi ",[32,233,234],{},"contact_edit"," basta anche\nper cercare. ",[32,237,238],{},"offline_access"," serve per il refresh token. E l’API lavora sempre con i diritti\ndell’utente che ha creato il collegamento: se in bexio non può vedere i contatti, non può\nneanche l’app.",[24,241,243],{"id":242},"passo-3-salvare-e-rinnovare-i-token","Passo 3: salvare e rinnovare i token",[15,245,246,247,250],{},"L’access token scade presto. Prima, WordPress ne ottiene uno nuovo con il refresh token e\n",[32,248,249],{},"grant_type=refresh_token",", tutti i valori nel corpo della richiesta, non nell’URL. Da tenere\npresente:",[252,253,254,257,260],"ul",{},[75,255,256],{},"Salvare sempre il nuovo refresh token restituito al rinnovo.",[75,258,259],{},"Se un collegamento resta un anno senza rinnovo, bexio chiude la sessione; poi qualcuno deve\naccedere di nuovo.",[75,261,262],{},"Salvare i token in opzioni WordPress senza autoload, perché non vengano caricati a ogni pagina.",[15,264,265],{},"Per i propri script esistono anche i token di accesso personali (PAT). Hanno accesso completo a\ntutti i dati dell’azienda e valgono 60 giorni. Comodi per uso personale, non sono adatti a un\nplugin installato sul sito di un cliente.",[24,267,269],{"id":268},"passo-4-creare-contatto-e-nota","Passo 4: creare contatto e nota",[15,271,272],{},"Uno svolgimento tipico per una richiesta dal modulo richiede quattro chiamate:",[72,274,275,289,295,306],{},[75,276,277,280,281,284,285,288],{},[32,278,279],{},"GET \u002F3.0\u002Fusers\u002Fme"," restituisce l’ID dell’utente. È obbligatorio alla creazione, come\n",[32,282,283],{},"user_id"," e ",[32,286,287],{},"owner_id",".",[75,290,291,294],{},[32,292,293],{},"POST \u002F2.0\u002Fcontact\u002Fsearch"," cerca tramite l’indirizzo e-mail se il contatto esiste già.",[75,296,297,298,301,302,305],{},"Altrimenti: ",[32,299,300],{},"POST \u002F2.0\u002Fcontact"," lo crea, ",[32,303,304],{},"contact_type_id"," 1 per le aziende, 2 per le\npersone.",[75,307,308,311],{},[32,309,310],{},"POST \u002F2.0\u002Fnote"," aggiunge il testo del modulo come nota al contatto.",[15,313,314],{},"La chiamata per creare un’azienda è così:",[108,316,320],{"className":317,"code":318,"language":319,"meta":113,"style":113},"language-json shiki shiki-themes github-light github-dark","{\n  \"contact_type_id\": 1,\n  \"name_1\": \"Esempio SA\",\n  \"street_name\": \"Via Nassa\",\n  \"house_number\": \"1\",\n  \"postcode\": \"6900\",\n  \"city\": \"Lugano\",\n  \"mail\": \"info@esempio.ch\",\n  \"user_id\": 1,\n  \"owner_id\": 1\n}\n","json",[32,321,322,327,342,354,366,378,390,403,416,428,439],{"__ignoreMap":113},[117,323,324],{"class":119,"line":120},[117,325,326],{"class":137},"{\n",[117,328,329,333,336,339],{"class":119,"line":127},[117,330,332],{"class":331},"sj4cs","  \"contact_type_id\"",[117,334,335],{"class":137},": ",[117,337,338],{"class":331},"1",[117,340,341],{"class":137},",\n",[117,343,344,347,349,352],{"class":119,"line":151},[117,345,346],{"class":331},"  \"name_1\"",[117,348,335],{"class":137},[117,350,351],{"class":133},"\"Esempio SA\"",[117,353,341],{"class":137},[117,355,356,359,361,364],{"class":119,"line":177},[117,357,358],{"class":331},"  \"street_name\"",[117,360,335],{"class":137},[117,362,363],{"class":133},"\"Via Nassa\"",[117,365,341],{"class":137},[117,367,368,371,373,376],{"class":119,"line":188},[117,369,370],{"class":331},"  \"house_number\"",[117,372,335],{"class":137},[117,374,375],{"class":133},"\"1\"",[117,377,341],{"class":137},[117,379,380,383,385,388],{"class":119,"line":208},[117,381,382],{"class":331},"  \"postcode\"",[117,384,335],{"class":137},[117,386,387],{"class":133},"\"6900\"",[117,389,341],{"class":137},[117,391,393,396,398,401],{"class":119,"line":392},7,[117,394,395],{"class":331},"  \"city\"",[117,397,335],{"class":137},[117,399,400],{"class":133},"\"Lugano\"",[117,402,341],{"class":137},[117,404,406,409,411,414],{"class":119,"line":405},8,[117,407,408],{"class":331},"  \"mail\"",[117,410,335],{"class":137},[117,412,413],{"class":133},"\"info@esempio.ch\"",[117,415,341],{"class":137},[117,417,419,422,424,426],{"class":119,"line":418},9,[117,420,421],{"class":331},"  \"user_id\"",[117,423,335],{"class":137},[117,425,338],{"class":331},[117,427,341],{"class":137},[117,429,431,434,436],{"class":119,"line":430},10,[117,432,433],{"class":331},"  \"owner_id\"",[117,435,335],{"class":137},[117,437,438],{"class":331},"1\n",[117,440,442],{"class":119,"line":441},11,[117,443,444],{"class":137},"}\n",[24,446,448],{"id":447},"insidie-tipiche","Insidie tipiche",[252,450,451,458,464,480,490,503,509],{},[75,452,453,457],{},[454,455,456],"strong",{},"URL di reindirizzamento:"," deve figurare esattamente così nel Developer Portal, altrimenti\nl’accesso si interrompe con un messaggio d’errore.",[75,459,460,463],{},[454,461,462],{},"Nuovi scope:"," i diritti di un collegamento non cambiano al rinnovo. Se l’app ha bisogno di\npiù, l’utente deve accedere di nuovo.",[75,465,466,469,470,473,474,284,477,288],{},[454,467,468],{},"Campi indirizzo:"," il campo ",[32,471,472],{},"address"," è obsoleto alla creazione. Via e numero vanno in\n",[32,475,476],{},"street_name",[32,478,479],{},"house_number",[75,481,482,485,486,489],{},[454,483,484],{},"A capo nelle note:"," bexio mostra il testo di una nota senza a capo. Per i paragrafi usare\n",[32,487,488],{},"\u003Cbr>"," e codificare i valori in HTML.",[75,491,492,495,496,284,499,502],{},[454,493,494],{},"Limite di richieste:"," con troppe richieste al minuto l’API risponde con lo stato 429. Le\nintestazioni ",[32,497,498],{},"RateLimit-Remaining",[32,500,501],{},"RateLimit-Reset"," dicono quanto attendere.",[75,504,505,508],{},[454,506,507],{},"Moduli lenti:"," chiamare bexio all’invio fa aspettare il visitatore e perde la richiesta se\nbexio non risponde. Meglio trasmettere in background e riprovare in caso di errore.",[75,510,511,514],{},[454,512,513],{},"Uso commerciale:"," secondo la cifra 4.4 delle condizioni, deve informare bexio chi gestisce\nsull’API un proprio modello di business a cui sono collegati almeno cinque account bexio.",[24,516,518],{"id":517},"tre-approcci-a-confronto","Tre approcci a confronto",[520,521,522,538],"table",{},[523,524,525],"thead",{},[526,527,528,532,535],"tr",{},[529,530,531],"th",{},"Approccio",[529,533,534],{},"Adatto se",[529,536,537],{},"Da considerare",[539,540,541,553,564],"tbody",{},[526,542,543,547,550],{},[544,545,546],"td",{},"Sviluppare in proprio",[544,548,549],{},"ci sono sviluppatori e il processo è molto particolare",[544,551,552],{},"accesso, rinnovo dei token, gestione degli errori e aggiornamenti restano lavoro vostro nel tempo",[526,554,555,558,561],{},[544,556,557],{},"Zapier o Make",[544,559,560],{},"lì girano già altri processi",[544,562,563],{},"un servizio in più da cui passano i dati del modulo, corrispondenze e duplicati a mano",[526,565,566,569,572],{},[544,567,568],{},"Plugin pronto",[544,570,571],{},"il processo segue uno schema comune",[544,573,574],{},"meno libero del codice proprio",[15,576,577],{},"Make e Zapier offrono bexio come app propria. Il plugin del modulo invia la richiesta via webhook\ne un’azione bexio crea il contatto.",[24,579,581],{"id":580},"soluzioni-pronte","Soluzioni pronte",[15,583,584],{},"Per i due casi più frequenti ci sono i miei collegamenti:",[252,586,587,594],{},[75,588,589,593],{},[53,590,592],{"href":591},"\u002Fit\u002Fbexio-formular-connector\u002F","Connettore moduli bexio",": plugin WordPress, le richieste dal\nmodulo del sito diventano contatti con nota in bexio, i duplicati vengono riconosciuti\ndall’e-mail. Ogni gestore collega il proprio bexio con una propria app, i dati vanno\ndirettamente dal sito a bexio.",[75,595,596,600],{},[53,597,599],{"href":598},"\u002Fit\u002Fbexio-hubspot\u002F","bexio ↔ HubSpot",": un deal vinto in HubSpot diventa offerta o fattura in\nbexio, lo stato del pagamento torna nel deal.",[15,602,603],{},[53,604,606],{"href":605},"\u002Fit\u002Fratgeber\u002F","Tutte le guide",[608,609,610],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}",{"title":113,"searchDepth":127,"depth":127,"links":612},[613,614,615,616,617,618,619,620],{"id":26,"depth":127,"text":27},{"id":69,"depth":127,"text":70},{"id":98,"depth":127,"text":99},{"id":242,"depth":127,"text":243},{"id":268,"depth":127,"text":269},{"id":447,"depth":127,"text":448},{"id":517,"depth":127,"text":518},{"id":580,"depth":127,"text":581},"Collegare l’API di bexio a WordPress: creare un’app nel Developer Portal, accedere con OAuth 2, rinnovare i token, creare contatti e note. Con le insidie tipiche e tre approcci a confronto.","md",{},true,"\u002Fratgeber\u002Fbexio-api-wordpress",null,{"title":5,"description":621},"ratgeber\u002Fbexio-api-wordpress","kTXpccRzteslBXdCw-8ZJ3C8SJ4S5vaPORzZ1M9ytes",1791126634710]