Attivare e usare la sincronizzazione nativa con Zoho

Obiettivo

Sincronizzare fatture e note di credito generate da POP con Zoho Invoice o Zoho Books, senza dover gestire tu stesso un webhook o un workflow n8n.

Prerequisiti

• Un account Zoho Invoice o Zoho Books attivo.
• Su WordPress: nessun piano minimo, la sincronizzazione è disponibile su ogni piano (incluso Free), a consumo di crediti. Su Shopify serve invece il piano Basic o superiore.

Attivazione (due passaggi)

1. Account POP — vai su popapi.io > Il mio account > Integrazioni API e completa l’autorizzazione OAuth verso Zoho. Da qui in poi Zoho è uno dei canali di invio disponibili: attivarlo come canale principale disattiva automaticamente ogni altro canale già attivo (SdI via POP, PEPPOL, KSeF, Fatture in Cloud, Aruba, SdI via PEC — sono tutti mutuamente esclusivi).
2. Lato plugin/app — l’autorizzazione sull’account POP non basta da sola: va abilitata anche localmente.

WordPress

Nella tab Integrazioni, trova la card “Zoho (via POP)” e clicca Activate. Se l’account POP non ha ancora completato l’autorizzazione, la card mostra il messaggio “Activate and connect Zoho in your POP account first.” — torna al passaggio 1.

Shopify

Vai su Impostazioni > Invoice Channel e seleziona l’opzione “Zoho via POP” tra i canali disponibili (selezione a radio button). Se l’opzione risulta disabilitata con l’etichetta “(unavailable)”, compare un banner che spiega il motivo (es. account POP non pronto, o il connector attivo lato POP non è Zoho).

Invio manuale e automatico

WordPress:

• Manuale — pulsanti “Create Zoho Invoice” / “Create Zoho Credit Note” sull’ordine; dopo l’invio diventano “Zoho invoice created” / “Zoho credit note created”.
• Automatico — usa la stessa impostazione di invio automatico già presente per gli altri canali (stato ordine che attiva l’invio, con eventuale ritardo in ore).

Shopify:

• Manuale — pulsanti “Send invoice to Zoho” / “Send credit note to Zoho” nella pagina Ordini.
• Stato mostrato in tabella: “Zoho: sent” oppure “Zoho: pending”.

Note di credito: serve prima la fattura Zoho

Una nota di credito non può essere inviata a Zoho se l’ordine collegato non ha già una fattura sincronizzata su Zoho con successo:

• WordPress — il pulsante resta bloccato con il messaggio: “Zoho credit notes require a Zoho parent invoice reference on the original order. Create the Zoho invoice first.”
• Shopify — stesso blocco, messaggio: “Send the parent invoice through Zoho before generating or sending the credit note.”

Fix: invia prima la fattura originale a Zoho, poi la nota di credito.

Sandbox

• WordPress — un invio in sandbox non crea nulla su Zoho: restituisce una conferma di prova, “Zoho sandbox dry run succeeded. No document was created in Zoho.” — non è un errore, è il comportamento atteso.
• Shopify — l’invio automatico in coda viene bloccato con: “Zoho auto-send is disabled while POP sandbox mode is active. Switch the environment back to live to process queued invoices.”

Verifica

Dopo l’attivazione, controlla nel plugin/app che lo stato Zoho risulti connesso e che il prodotto collegato (Zoho Invoice o Zoho Books) sia indicato correttamente, non “not available”.

Errori comuni

• Il prodotto risulta “not available” — l’autorizzazione OAuth non è stata completata o è scaduta: ripeti il passaggio 1 dal pannello account.
• Ho attivato Zoho e un altro canale si è disattivato da solo — comportamento atteso: i canali principali sono mutuamente esclusivi.
• Il pulsante di invio nota di credito resta bloccato — vedi la sezione sopra: manca la fattura Zoho collegata all’ordine originale.
• “The previous Zoho send may have timed out…” (WordPress) — l’invio precedente potrebbe non aver ricevuto risposta in tempo: se il documento risulta creato su Zoho, conferma e salva manualmente l’ID restituito; altrimenti annulla e riprova.
• La sincronizzazione fallisce per un contatto mancante — verifica l’opzione di auto-creazione contatti; se disattivata, il contatto deve già esistere su Zoho prima della sincronizzazione.

Configurazione correlata

Per scegliere tra questo canale e gli altri disponibili, vedi choosing-an-invoicing-integration. Per i dettagli endpoint, vedi api/zoho.