APIs de apoio

APIs de suporte: todos os endpoints com exemplos cURL, Python e Node, países e estados compatíveis, subcategorias e plataformas de publicação do seu plano.

Os endpoints de suporte são os três catálogos de referência usados nas validações do restante da API: quais países e estados são compatíveis, quais categorias de negócios existem e quais diretórios de plataformas de publicação o seu plano cobre. Os três são somente leitura, não têm paginação e retornam o conjunto completo, portanto uma chave Read (leitura) é suficiente e o cache importa mais que a paginação.

Visão geral dos endpoints

Listar países e estados compatíveis

GET /countries

Retorna o catálogo completo em data.supportedCountries. Cada país contém um código ISO, um id em base64, um databaseId numérico, um array states cujas entradas têm seus próprios códigos ISO e três indicadores de endereço: hasCity (cidade obrigatória), stateRequired (estado obrigatório e validado com base em states) e hasPostalCode (o país usa códigos postais). Um país que não tem subdivisões retorna um array states vazio.

Parâmetros

Este endpoint não aceita parâmetros. Ele sempre retorna o conjunto completo.

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

Os dois campos iso contêm os valores de que você precisa. O iso de um país se torna countryIso na criação e na atualização, e o iso de um estado se torna stateIso. Validar ambos com base nesta lista antes de uma operação de escrita transforma um 400 no servidor em uma mensagem clara no seu próprio formulário.

Listar subcategorias

GET /sub-categories

Retorna cerca de 6.000 registros de categorias em data.subcategories, em um único array sem paginação. Essa consulta transforma um tipo de negócio que você conhece como texto livre no id numérico exigido por uma operação de escrita de um local.

Parâmetros

Nenhum. O catálogo inteiro é retornado em cada chamada.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

Cada registro contém cinco campos, e o campo que você usa depende de onde ele será utilizado.

Um local aceita uma categoria principal em subCategoryId e até nove outras em additionalCategoryIds.

Listar sites do plano

GET /plan-sites

Retorna todos os diretórios de plataformas de publicação incluídos no plano da sua conta, em data.planSites. Esta é a lista oficial de ids numéricos de sites, e somente os ids que aparecem aqui são válidos em outras partes da API.

Parâmetros

Nenhum. A resposta se limita ao plano da sua conta.

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

Os dois arrays de países respondem a perguntas diferentes. supportedCountries indica em quais países o site aceita uma listagem, portanto filtre pelo countryIso do seu local antes de oferecer uma plataforma de publicação. hideAddressSupportedCountries indica em quais países o site respeita a configuração de endereço oculto, que é o que uma empresa com área de atendimento precisa. Ambos os arrays podem conter 50 ou mais códigos; o exemplo acima foi abreviado.

Os ids de sites são estáveis e vale a pena conhecê-los: 1 é o Google Maps e 184 é o Facebook, as duas plataformas de publicação às quais se destina a maioria dos fluxos de conexão.

Links de ação do local

Não é um endpoint independente. Os links de ação do local são os botões do Google, como Order online (pedir online), Reserve a table (reservar uma mesa) e Book an appointment (agendar um horário), e a plataforma os gerencia como um campo do local, em vez de um recurso separado. Você os define por meio do array placeActionLinks na criação e na atualização e os consulta em qualquer endpoint de leitura de locais.

Cada entrada precisa de um placeActionType e de um uri, permite uma flag opcional isPreferred com no máximo um link preferencial por tipo e aceita um action de add ou delete na atualização. Os tipos válidos, as regras de exclusão e o comportamento de sincronização estão em Links de ação do local.

Erros que você verá

Nenhum desses endpoints realiza operações de escrita, portanto, uma chave Read nunca retorna SY90016 aqui. A lista completa está em Códigos de erro.

Próximos passos

• Consultar países e categorias: a versão orientada à tarefa, com a transição para a criação de um local explicada passo a passo.
• Adicionar um local: onde countryIso e subCategoryId são utilizados.
• Encontrar e corrigir erros de listagem: usa os sites do plano para distinguir uma plataforma de publicação ausente de uma com falha.
• Referência das APIs de suporte para a lista completa de campos dos três endpoints.