Listar marcas | Listings API

Parâmetros

Query

Nome	Tipo	Obrigatório	Descrição	Padrão
filters	string	opcional	JSON-encoded filter object with two fields. `statuses` (array of strings, required inside the object) selects which brand states to return: `ACTIVE` or `ARCHIVED`. `profileName` (string, optional) is a case-insensitive substring match on the brand name. Omit the parameter entirely to return active brands.	—
page	integer	opcional	1-based page number. Defaults to 1.	—
size	integer	opcional	Rows per page. Defaults to 20.	—

Respostas

200A page of brands plus `pageInfo` for paging.

Response

{  "data": {    "listSocialProfiles": {      "profiles": [        {          "id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "profileName": "Jenny Home",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": "https://jennyhome.example",          "countryIso": "US",          "bio": "Handmade furniture for real homes.",          "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",          "categories": ["Furniture Store", "Home Goods"],          "brandHashtags": ["jennyhome", "handmadefurniture"],          "competitorHashtags": [],          "connectedChannelCount": 3,          "timezone": {            "label": "(GMT-05:00) Eastern Time",            "tzCode": "America/New_York",            "name": "Eastern Standard Time",            "utc": "-05:00"          },          "contentPreferredLanguage": "en"        },        {          "id": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33",          "profileName": "Jenny Home Eastside",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": null,          "countryIso": "US",          "bio": null,          "businessIntent": "general",          "categories": [],          "brandHashtags": [],          "competitorHashtags": [],          "connectedChannelCount": 0,          "timezone": {            "label": "(GMT-06:00) Central Time",            "tzCode": "America/Chicago",            "name": "Central Standard Time",            "utc": "-06:00"          },          "contentPreferredLanguage": "en"        }      ],      "pageInfo": {        "total": 11,        "hasNextPage": true,        "totalEngagementPosts": 0,        "totalPublishedPosts": 0      }    }  }}

401Unauthenticated, missing or invalid API key.

Lista as marcas da sua conta, uma página por vez. Cada linha contém o mesmo objeto de marca que GET /social/brands/{brandId} retorna para uma única marca, então uma lista geralmente basta para renderizar um seletor de marcas sem uma segunda chamada.

Caso de uso: um seletor de marcas na sua própria interface. Faça esta chamada uma vez quando o usuário abrir sua tela de publicação e renderize profileName e logo em cada linha. Uma marca cujo connectedChannelCount é 0 ainda não tem nenhuma conta de rede social vinculada e não pode publicar; sinalize isso e direcione o usuário para um link de conexão. Percorra as páginas com page e size enquanto pageInfo.hasNextPage for true.

Caso de uso: conciliar seus registros. Percorra todas as páginas todas as noites e compare id com os IDs de marca que você armazenou no momento da criação. Uma marca que desapareceu da listagem padrão foi arquivada; passe filters={"statuses":["ARCHIVED"]} para vê-la.

Observações.

id é o UUID simples usado como o token de caminho brandId em outras partes da Social API e como socialProfileId nos corpos das requisições.
Os filtros são enviados como uma única string codificada em JSON no parâmetro de consulta filters, e não como parâmetros separados. Aplique a codificação de URL a essa string. Se você enviar filters, ele deverá conter statuses; profileName é opcional junto dele.
A paginação é baseada em offset (page / size), e não em cursor como nos endpoints Locations e Reviews. pageInfo.total é o número total de marcas que correspondem aos critérios, e não o número nesta página. pageInfo.totalEngagementPosts e totalPublishedPosts são contadores de publicações compartilhados com a lista de publicações e têm o valor 0 aqui.
connectedChannelCount conta apenas conexões ativas; um canal desconectado deixa de ser contado imediatamente. Para obter os canais em si, chame GET /social/brands/{brandId}/connections.
timezone.tzCode é o identificador IANA usado como referência para determinar o horário de cada agendamento dessa marca; os outros três campos de fuso horário são rótulos de exibição.
Não há um limite de marcas com o qual comparar a contagem. As marcas são ilimitadas nos planos de API, portanto o tamanho desta lista é informativo. O número limitado é o de conexões: consulte-o em GET /social/limits. O arquivamento de uma marca deixa suas conexões offline imediatamente, mas suas vagas continuam contando para o limite de maxConnections até o fim do período de cobrança, portanto uma marca que saiu desta lista ainda pode ocupar vagas até a renovação.