Listings APIListings API
Entrar

Adicionar um local

Crie um local com os campos necessários para as plataformas de publicação, trate erros de validação e confirme que ele foi colocado na fila para envio.

Listagens, avaliações, publicações e análises são vinculadas a um ID de local. POST /api/v4/locations cria o local e coloca na fila uma listagem para cada plataforma de publicação do seu plano.

1. Reúna os campos obrigatórios

Dez campos são obrigatórios. Uma empresa que atende em uma área de serviço também envia o endereço completo: com hideAddress: true, ListingsAPI armazena o endereço, mas não o envia às plataformas de publicação. As plataformas de publicação exibem os campos opcionais omitidos em branco, então envie todas as informações que você tiver.

CampoObrigatórioObservações
nameSimDe 2 a 150 caracteres.
descriptionSimMínimo de 200 caracteres (SY10005).
countryIsoSimCódigo de duas letras de um país compatível (SY10036).
citySimObrigatório quando o hasCity do país é true (SY10126). Quando é false, a cidade que você enviar será descartada.
subCategoryIdSimdatabaseId numérico da lista de subcategorias.
streetSimDe 5 a 100 caracteres (SY10011).
stateIsoSimObrigatório quando o stateRequired do país é true e deve ser um dos states desse país (SY10010). Omita esse campo quando stateRequired for false.
postalCodeNãoOpcional, mas envie esse campo sempre que o hasPostalCode do país for true. O valor que você enviar deve corresponder ao formato do país (SY10014).
phoneSimValidado de acordo com o país (SY10015).
bizUrlSimPublicado como o site. Algumas plataformas de publicação recusam uma listagem sem site.
storeIdNãoSeu próprio código de loja, exclusivo em toda a conta. Use-o para encontrar o local novamente sem armazenar nossos IDs.
businessHoursNãoUma entrada por dia da semana. Consulte o formato em Atualizar um local.

2. Crie o local

POST /api/v4/locations recebe os campos em um objeto input no corpo JSON da requisição. O método locations.add() do Python SDK recebe os mesmos campos como argumentos nomeados e valida os obrigatórios antes de enviar a requisição. O método createLocation() do Node SDK recebe o objeto camelCase diretamente.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Leia a resposta

Uma criação bem-sucedida retorna success: true e o novo local em data.createLocation.location. Guarde os dois identificadores: id é o valor em base64 recebido por todas as operações de gravação posteriores, e databaseId é o valor numérico exibido nos painéis e nos payloads de webhook.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

status é PENDING enquanto o local é validado e colocado na fila. Esse valor avança sem uma nova chamada à API.

4. Trate os erros de validação

Uma criação pode falhar em dois pontos. Uma requisição malformada ou uma chave inválida retorna 4xx com um array errors no nível superior. Uma requisição bem formada com um campo que a API rejeita retorna 200 com success: false e o problema dentro de data.createLocation.errors, então verifique o corpo da resposta de cada operação de gravação, não apenas o código de status.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Ambos os SDKs lançam exceções em caso de falha. O locations.add() do Python verifica os campos obrigatórios localmente e lança ValidationError antes de enviar a requisição. O createLocation() do Node lança ValidationError quando a API rejeita os dados de entrada, e é por isso que o exemplo acima não verifica nenhum indicador de sucesso.

Os códigos que você encontrará com mais frequência:

CódigoCausaCorreção
SY10005Descrição ausente ou com menos de 200 caracteres.Escreva uma descrição mais completa.
SY10011street ausente ou com menos de 5 caracteres.Envie street.
SY10010stateIso ausente ou inválido para o país.Envie um código de estado obtido no endpoint de países.
SY10036countryIso não é um país compatível.Use um código obtido no endpoint de países.
SY10126city ausente para um país que exige esse campo.Envie city.
SY90016A chave é somente Read.Use uma chave Write.

5. Confirme que o envio foi iniciado

A criação do local coloca na fila uma listagem por plataforma de publicação do seu plano. Cada listagem começa em AVAILABLE ou IN_PROGRESS e passa para SYNCED com um listingUrl assim que a plataforma de publicação a aceita.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

Com os webhooks configurados, não é necessário fazer consultas periódicas. Um evento profile.created é disparado quando o registro existe, e um evento listing.submission é disparado para cada plataforma de publicação conforme seu status muda.

Próximos passos