Integrazione nativa Zoho

both2026-09-01

L’integrazione nativa Zoho è uno dei canali di invio POP (come SdI via POP, PEPPOL, KSeF): sincronizza direttamente un documento verso Zoho Invoice o Zoho Books via OAuth, senza passare da un webhook n8n gestito dall’utente. È un canale distinto dal connector generico, che invece inoltra il payload a un webhook n8n che tu stesso configuri e gestisci — usa questa pagina se ti serve la sincronizzazione diretta, l’altra se vuoi instradare tramite un tuo workflow n8n.

Endpoint

GET /wp-json/api/v2/integration/zoho/status — stato della connessione (regione, prodotto, org ID, scadenza token, stato fattura di default, auto-creazione contatti).
POST /wp-json/api/v2/integration/zoho/sync — sincronizza un documento verso Zoho.
GET /wp-json/api/v2/integration/oauth/callback — callback OAuth usato durante l’autorizzazione (gestito automaticamente dal flusso di connessione, non da chiamare manualmente).

Cosa serve

Attivazione del canale Zoho dal pannello account POP (è uno dei canali di invio mutuamente esclusivi: attivarlo disattiva automaticamente gli altri).
Autorizzazione OAuth completata — lo stato “connected” in integration/zoho/status deve risultare true prima di poter sincronizzare.
Nessun piano a pagamento richiesto su WordPress, API diretta, n8n o MCP: la sincronizzazione usa i crediti disponibili. Su Shopify serve ancora il piano Basic o superiore.

Da sapere

Ogni documento sincronizzato in ambiente live consuma 1 credito.
zoho_product indica se l’account è collegato a Zoho Invoice o Zoho Books.
zoho_create_contact_if_missing controlla se un contatto Zoho mancante viene creato automaticamente durante la sincronizzazione, invece di fallire.
payment_terms viene derivato automaticamente da payment_data.payment_due_days.
I metadati fiscali/di pagamento senza un campo Zoho dedicato (nature, ref_normative e i valori chiave di payment_data) vengono copiati automaticamente nelle notes della fattura Zoho.
Per mappare quegli stessi valori su campi personalizzati Zoho, passa integration.custom_fields_map (oggetto con label o customfield_id per campo) — l’integrazione nativa crea solo documenti, non aggiorna contatti Zoho esistenti.
Note di credito — richiedono che l’ordine collegato abbia già una fattura sincronizzata con successo su Zoho; senza quel riferimento la richiesta fallisce con errore 422 (“Zoho credit notes require a Zoho parent invoice reference on the original order.”).
Sandbox — una richiesta con environment: sandbox non crea nulla su Zoho: restituisce una risposta di successo con conferma di dry-run, senza toccare l’account Zoho reale.

Errori comuni

Codice	Causa
`no_connector_configured`	Nessun connector nativo attivo sull’account
`unsupported_doc_type`	`doc_type` diverso da `TD01`/`TD04`
`missing_connected_invoice`	Nota di credito senza `connected_invoice_data.id`
`tax_not_found`	Un’aliquota di `order_items[].rate` non è configurata su Zoho
`contact_not_found`	Cliente non trovato e auto-creazione disattivata
`contact_ambiguous`	Più contatti Zoho corrispondono alla stessa P.IVA/email/nome
`zoho_region_not_configured` / `zoho_organization_not_configured`	Regione o Organization ID mancanti nelle impostazioni account
`zoho_api_error`	Errore generico restituito da Zoho e inoltrato da POP

Configurazione correlata

Per l’attivazione lato pannello account e lo stato mostrato nel plugin/app, vedi integrations/zoho.