Scegli come integrare

Confronta l'API REST, gli SDK Python e Node, il server MCP e i webhook in base all'architettura della tua applicazione e ai requisiti di integrazione.

Tutti i metodi di integrazione usano la stessa chiave API e lo stesso URL di base: https://listingsapi.com/api/v4. Puoi usare l'API REST o un SDK per le richieste API, i webhook per gli aggiornamenti basati su eventi e il server MCP per integrare con l'aiuto di un agente AI.

1. Scegli come chiamare l'API

API REST. Usa l'API REST per accedere a tutti gli endpoint direttamente tramite HTTP. La tua applicazione deve analizzare la risposta, gestire entrambi i metodi di paginazione ed esaminare l'array errors[] per individuare eventuali errori API.

Python SDK. Installa il Python SDK con pip install listingsapi. L'SDK fornisce classi di risorse tramite interfacce come client.locations e client.reviews. Gestisce la paginazione basata su cursore con auto_paging_iter(), riprova le richieste che restituiscono risposte 429 o 5xx e convalida i payload delle sedi in locations.add() prima di inviare la richiesta API. Leggi Python SDK.

Node SDK. Installa il Node SDK con npm install listingsapi-js. Richiede Node.js 18 o versioni successive, include definizioni di tipo TypeScript e non ha dipendenze di runtime. I metodi dell'SDK sono esposti direttamente sull'istanza del client, ad esempio client.fetchAllLocations(). Imposta fetchAll: true per recuperare tutti i risultati paginati in un'unica risposta. Gli ID numerici vengono codificati automaticamente in Base64 prima dell'invio delle richieste API. Leggi Node SDK.

Server MCP. Collega client AI come Claude, ChatGPT, Cursor e Gemini al server MCP di ListingsAPI all'indirizzo https://listingsapi.com/mcp tramite Streamable HTTP. Non è richiesta l'installazione di un server MCP locale. Il server espone strumenti per cercare nella documentazione di ListingsAPI, individuare gli endpoint REST ed eseguire le operazioni API supportate. L'autenticazione usa una chiave API oppure OAuth. Apri /dashboard/mcp per visualizzare la configurazione del client, gli strumenti MCP disponibili e il livello di autorizzazione della chiave API richiesto per ciascuno strumento. Collega un agente AI con MCP.

Webhook. Usa i webhook con l'API REST, gli SDK o il server MCP per ricevere aggiornamenti basati su eventi. Quando una sede, una scheda, una recensione o un post cambia, ListingsAPI invia una richiesta HTTP POST all'URL del webhook configurato per il tuo account. Questo consente alla tua applicazione di elaborare le modifiche senza interrogare periodicamente l'API per verificare la presenza di aggiornamenti. Leggi Panoramica dei webhook.

2. Comprendi il modello di autenticazione

L'API REST e gli SDK autenticano le richieste tramite una chiave API. Passa la chiave nell'header Authorization della richiesta HTTP usando lo schema di autenticazione API:

Authorization: API <YOUR_API_KEY>

Le chiavi API hanno accesso Read (lettura) oppure Write (scrittura). Una chiave Read consente di accedere alle operazioni di lettura, incluse ricerche e report. Per le operazioni che creano o aggiornano risorse è necessaria una chiave Write. Se invii una chiave Read a un endpoint di scrittura, l'endpoint restituisce lo stato HTTP 400 con il codice di errore SY90016.

Le chiavi API sono limitate a un account. Le richieste effettuate con chiavi dello stesso account consumano la stessa quota del limite di frequenza a livello di account.

Il server MCP supporta anche l'autenticazione OAuth. I client MCP possono autenticarsi tramite il browser usando OAuth anziché fornire una chiave API. Le richieste all'API REST e quelle effettuate tramite gli SDK si autenticano usando l'header Authorization. Consulta la documentazione Autenticazione per i dettagli di configurazione.

3. Comprendi i modelli di paginazione

Gli endpoint REST che restituiscono elenchi usano la paginazione basata su cursore o su offset. Gli SDK astraggono questi modelli di paginazione.

Gli endpoint basati su cursore accettano first e after. I risultati vengono restituiti tramite edges[].node e pageInfo.endCursor fornisce il cursore per la richiesta successiva.

Gli endpoint basati su offset accettano page e perPage. I risultati vengono restituiti in records[] e pageInfo.totalRecords indica il numero totale di record disponibili.

Gli esempi seguenti eseguono la stessa operazione di recupero dell'elenco delle sedi usando tre metodi di integrazione. L'implementazione cURL richiede che l'applicazione analizzi direttamente la struttura della risposta dell'API.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Per tutti i metodi di integrazione, gli errori dell'API vengono restituiti nell'array errors[], con ciascun messaggio di errore preceduto da un codice di errore SY. Le richieste di scrittura possono restituire HTTP 200 con success: false, quindi il corpo della risposta deve essere controllato prima di considerare l'operazione riuscita.

Quando l'account supera il proprio limite di richieste, l'API restituisce HTTP 429 con un'intestazione Retry-After. Il piano Launch supporta fino a 10 richieste al minuto. Consulta la documentazione sui Codici di errore e sui Limiti di richieste per maggiori dettagli.

4. Scegli tra webhook e polling

Usa il polling quando la tua applicazione ha bisogno dello stato delle risorse secondo una pianificazione definita, ad esempio per una sincronizzazione notturna di tutte le sedi, oppure quando l'evento richiesto non supporta i webhook. Usa i webhook quando la tua applicazione deve elaborare le modifiche nel momento in cui si verificano, ad esempio la ricezione di una nuova recensione, una modifica dello stato di una scheda o il rifiuto di un post di Google.

Configura un URL webhook per account in /dashboard/webhooks. Ogni richiesta webhook include un'intestazione X-ListingsAPI-Signature nel seguente formato:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

L'endpoint webhook deve restituire una risposta 2xx entro 5 secondi. Le consegne non riuscite non vengono ritentate.

Usa l'evento webhook per attivare il recupero dello stato attuale della risorsa dall'API. Poiché le consegne dei webhook non vengono ritentate, esegui un processo di riconciliazione pianificato per rilevare gli aggiornamenti che potrebbero essere sfuggiti. Consulta Reagire agli eventi con i webhook per un esempio di implementazione.

5. Confronta a colpo d'occhio

Passaggi successivi

• Aggiungere una sede: la tua prima chiamata di scrittura, con l'opzione che hai scelto.
• Reagire agli eventi con i webhook: configura un ricevitore con verifica della firma.
• Python SDK e Node SDK: installa, configura e leggi le tabelle dei metodi.
• Autenticazione, Limiti di richieste e Codici di errore: i tre riferimenti comuni a tutte le opzioni.