Escolha como integrar

Compare a API REST, os SDKs Python e Node, o servidor MCP e os webhooks com base na arquitetura e nos requisitos de integração da sua aplicação.

Todos os métodos de integração usam a mesma chave de API e URL base: https://listingsapi.com/api/v4. Você pode usar a API REST ou um SDK para fazer requisições à API, webhooks para receber atualizações orientadas a eventos e o servidor MCP para integrar com a ajuda de um agente de IA.

1. Escolha como você fará chamadas à API

API REST. Use a API REST para acessar todos os endpoints diretamente por HTTP. Sua aplicação deve analisar a resposta, lidar com os dois métodos de paginação e inspecionar o array errors[] em busca de erros da API.

Python SDK. Instale o Python SDK com pip install listingsapi. O SDK fornece classes de recursos por meio de interfaces como client.locations e client.reviews. Ele gerencia a paginação por cursor com auto_paging_iter(), repete requisições que retornam respostas 429 ou 5xx e valida os payloads de locais em locations.add() antes de enviar a requisição à API. Leia Python SDK.

Node SDK. Instale o Node SDK com npm install listingsapi-js. Ele requer Node.js 18 ou posterior, inclui definições de tipos TypeScript e não tem dependências em tempo de execução. Os métodos do SDK são expostos diretamente na instância do cliente, por exemplo, client.fetchAllLocations(). Configure fetchAll: true para obter todos os resultados paginados em uma única resposta. Os IDs numéricos são automaticamente codificados em Base64 antes que as requisições à API sejam enviadas. Leia Node SDK.

Servidor MCP. Conecte clientes de IA como Claude, ChatGPT, Cursor e Gemini ao servidor MCP da ListingsAPI em https://listingsapi.com/mcp usando Streamable HTTP. Não é necessário instalar um servidor MCP local. O servidor expõe ferramentas para pesquisar a documentação da ListingsAPI, descobrir endpoints REST e executar operações de API compatíveis. A autenticação usa uma chave de API ou OAuth. Abra /dashboard/mcp para ver a configuração dos clientes, as ferramentas MCP disponíveis e o nível de permissão da chave de API exigido para cada ferramenta. Conecte um agente de IA com MCP.

Webhooks. Use webhooks com a API REST, os SDKs ou o servidor MCP para receber atualizações orientadas a eventos. Quando um local, uma listagem, uma avaliação ou uma publicação muda, a ListingsAPI envia uma requisição HTTP POST para a URL de webhook configurada para sua conta. Isso permite que sua aplicação processe as alterações sem consultar periodicamente a API em busca de atualizações. Leia Visão geral dos webhooks.

2. Entenda o modelo de autenticação

A API REST e os SDKs autenticam requisições usando uma chave de API. Passe a chave no cabeçalho HTTP Authorization da requisição usando o esquema de autenticação API:

Authorization: API <YOUR_API_KEY>

As chaves de API têm acesso Read (leitura) ou Write (escrita). Uma chave Read pode acessar operações de leitura, incluindo consultas e relatórios. Uma chave Write é necessária para operações que criam ou atualizam recursos. Ao receber uma chave Read, um endpoint de escrita retorna HTTP 400 com o código de erro SY90016.

As chaves de API têm escopo limitado a uma conta. As requisições feitas com chaves da mesma conta consomem a mesma cota de limite de requisições da conta.

O servidor MCP também oferece suporte à autenticação OAuth. Os clientes MCP podem se autenticar pelo navegador usando OAuth em vez de fornecer uma chave de API. As requisições da API REST e dos SDKs são autenticadas usando o cabeçalho Authorization. Consulte a documentação de Autenticação para obter detalhes de configuração.

3. Entenda os modelos de paginação

Os endpoints REST de listagem usam paginação baseada em cursor ou em deslocamento. Os SDKs abstraem esses modelos de paginação.

Os endpoints baseados em cursor aceitam first e after. Os resultados são retornados por meio de edges[].node, e pageInfo.endCursor fornece o cursor para a próxima requisição.

Os endpoints baseados em deslocamento aceitam page e perPage. Os resultados são retornados em records[], e pageInfo.totalRecords informa o número total de registros disponíveis.

Os exemplos a seguir executam a mesma operação de listagem de locais usando três métodos de integração. A implementação com cURL exige que a aplicação analise diretamente a estrutura da resposta da 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.

Em todos os métodos de integração, os erros da API são retornados no array errors[], com cada mensagem de erro prefixada por um código de erro SY. As requisições de escrita podem retornar HTTP 200 com success: false, portanto, o corpo da resposta deve ser verificado antes de considerar a operação bem-sucedida.

Quando a conta excede seu limite de requisições, a API retorna HTTP 429 com um cabeçalho Retry-After. O plano Launch permite até 10 requisições por minuto. Consulte a documentação de Códigos de erro e Limites de requisições para obter detalhes.

4. Escolha entre webhooks e consultas periódicas

Use consultas periódicas quando sua aplicação precisar do estado dos recursos em uma programação definida, como uma sincronização noturna de todos os locais, ou quando o evento necessário não tiver suporte a webhooks. Use webhooks quando sua aplicação precisar processar alterações à medida que elas ocorrem, como o recebimento de uma nova avaliação, uma alteração no status de uma listagem ou a rejeição de uma publicação no Google.

Configure uma URL de webhook por conta em /dashboard/webhooks. Cada requisição de webhook inclui um cabeçalho X-ListingsAPI-Signature no seguinte formato:

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

O endpoint do webhook deve retornar uma resposta 2xx em até 5 segundos. Não há novas tentativas para entregas que falham.

Use o evento do webhook como gatilho para recuperar o estado atual do recurso na API. Como não há novas tentativas de entrega dos webhooks, execute um processo de reconciliação agendado para detectar atualizações que possam ter passado despercebidas. Consulte Reaja a eventos com webhooks para ver um exemplo de implementação.

5. Compare rapidamente

Próximos passos

• Adicione um local: sua primeira chamada de escrita, usando a opção que você escolheu.
• Reaja a eventos com webhooks: coloque em funcionamento um receptor com verificação de assinatura.
• Python SDK e Node SDK: instale, configure e leia as tabelas de métodos.
• Autenticação, Limites de requisições e Códigos de erro: as três referências comuns a todas as opções.