Listings APIListings API
Entrar

Faça sua primeira chamada à API

Autentique-se, liste seus locais, entenda a estrutura da resposta, percorra as páginas de resultados e saiba como os IDs funcionam.

Este guia pressupõe que você tem uma conta e uma chave de API obtidas em Primeiros passos. Todas as requisições usam a API de produção em https://listingsapi.com, portanto, uma chamada de escrita com uma chave de API comum altera dados reais. Para testar a API sem afetar plataformas de publicação reais, use o passe diário gratuito do sandbox.

1. Configure sua chave de API

Copie a chave de Chaves de API no painel e exporte-a uma vez no seu shell:

bash
export LISTINGSAPI_KEY="your-api-key"

As chaves têm um nível de acesso. Uma chave Read (leitura) permite todas as consultas e todos os relatórios destes guias. Criar ou atualizar qualquer recurso, responder a uma avaliação ou publicar uma postagem exige uma chave Write (escrita). Quando você envia uma chave Read a um endpoint de escrita, o endpoint retorna HTTP 400 com o código de erro SY90016.

2. Liste seus locais

Outros endpoints fazem referência a um local pelo ID, então comece listando os locais que você tem. O cabeçalho Authorization da API REST usa o esquema API, seguido de um espaço e da sua chave de API: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Leia a resposta

A API REST retorna uma resposta com estrutura aninhada em vez de apenas um array. O nome da operação fica em data, os resultados da listagem são retornados como uma conexão de edges, e cada edge contém um node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

O Python SDK retorna uma página iterável de objetos. O Node SDK retorna locations e pageInfo. Quando você chama a API REST diretamente, leia data.allLocations.edges[].node.

4. Percorra as páginas de resultados

Os endpoints de listagem de locais e avaliações usam paginação por cursor. Solicite uma página com first e depois passe pageInfo.endCursor como after para obter a próxima página. Os SDKs podem ler todas as páginas para você.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Nem todos os endpoints usam esse formato de paginação. Contas conectadas, resumos de duplicatas e postagens usam page e perPage com um array records. Cada guia informa qual formato de paginação seus endpoints usam.

5. Dois tipos de ID

Cada registro tem dois identificadores. id é uma string em base64, como TG9jYXRpb246MTgwMDI4OQ==, que, ao ser decodificada, resulta em Location:1800289. databaseId é o número sem codificação, 1800289.

Armazene o id em base64. Todos os endpoints de escrita exigem IDs codificados em base64, e esses são os valores retornados nos payloads dos webhooks. Muitos endpoints de leitura que recebem um local no caminho também aceitam o número sem codificação, e os dois SDKs aceitam qualquer uma das formas e fazem a codificação para você.

6. Erros e limites de requisições

As respostas de falha retornam o status HTTP correspondente com um array errors. A mensagem começa com um código de erro SY, listado em Códigos de erro:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Os limites de requisições variam por plano, e as requisições são contadas por minuto, hora e dia. O plano Launch permite 10 requisições por minuto. Quando você excede um limite, a API retorna 429 com um cabeçalho Retry-After; aguarde a quantidade de segundos indicada antes de tentar novamente. Os SDKs lançam RateLimitError e disponibilizam o mesmo valor. Os detalhes completos estão em Limites de requisições.

Próximos passos