Planos de anúncio

Consulta os planos (listing types) disponíveis para uma loja em um portal específico: limites contratados, quantidade publicada, vagas disponíveis e identificadores usados na publicação (plan_id em POST /integration).

Há duas rotas com o mesmo formato de plano na lista plans, mas fontes de dados diferentes.

Visão geral

Rota	Fonte dos dados	Quando usar
GET .../listing-type/...	Cadastro local no Loja Conectada	Consulta rápida, sem chamar o portal; dados já sincronizados ou configurados na plataforma.
GET .../listing-type-on-line/...	API online do portal (quando o site suporta)	Saldo e planos em tempo real no portal; exige credenciais válidas e portal que permita consultar planos remotamente.

dica

Antes de publicar, confira available > 0 no plano escolhido. O integrator_plan_id de cada item é o valor típico de plan_id na integração — veja Por Onde Começar.

Autenticação e permissão

Ambas as rotas exigem JWT e que o usuário autenticado tenha acesso à loja informada em dealer_id (ou seja administrador).

Authorization: Bearer {access_token}
X-Client-ID: {client_id do seu app}

(Conforme Como autenticar e demais endpoints v3.)

Parâmetros de URL

Parâmetro	Tipo	Descrição
dealer_id	integer	ID da loja.
portal_id	integer	ID do portal no catálogo de portais ativos.

---

GET /integration/listing-type/{dealer_id}/{portal_id}

Retorna os planos ativos já cadastrados para a loja naquele portal, a partir dos dados persistidos na plataforma.

Comportamento

• Lista apenas planos ativos vinculados à loja e ao portal informados.
• Não chama a API externa do portal.
• next_renew_date vem vazio ("") nesta rota (reservado ao fluxo online).
• updated_at é a data da última atualização conhecida dos planos dessa loja nesse portal (pode ser null se não houver planos).

Resposta — 200 OK

{
  "plans": [
    {
      "name": "Plano Básico",
      "total": 100,
      "published": 50,
      "available": 50,
      "percentage_used": 50.0,
      "integrator_plan_id": 32,
      "is_for_new": false,
      "category": 1,
      "subscription_id": null
    }
  ],
  "next_renew_date": "",
  "updated_at": "2026-05-20T14:30:00Z"
}

Campos de cada item em plans

Campo	Tipo	Descrição
name	string	Nome do plano.
total	integer	Total contratado / limite do plano.
published	integer	Anúncios já publicados nesse plano.
available	integer	Vagas disponíveis para publicação.
percentage_used	number	Percentual de uso do plano.
integrator_plan_id	integer	ID do plano no Loja Conectada; use como plan_id na publicação quando aplicável.
is_for_new	boolean	Se o plano é restrito a veículos 0 km.
category	integer | null	Categoria de veículo associada ao plano, se houver.
subscription_id	string | integer | null	Identificador de assinatura no portal, quando existir.

---

GET /integration/listing-type-on-line/{dealer_id}/{portal_id}

Consulta os planos diretamente no portal, quando o site oferece consulta de planos/saldo em tempo real (veja metadados do portal em Portais ativos (catálogo)).

Comportamento

1. Se o portal não suportar consulta de planos pela API, a resposta tende a vir com lista vazia, sem chamada externa.
2. Caso contrário, autentica a loja no portal e consulta os planos na API do parceiro.
3. Os dados retornados são normalizados para o mesmo formato da rota offline e podem atualizar o cadastro de acesso da loja na plataforma.
4. A resposta traz plans, next_renew_date (quando o portal informar) e updated_at (referência da última atualização local dos planos).

informação

Use esta rota quando precisar do saldo atual no portal (antes de integrar um anúncio). Garanta que a loja já tenha credenciais válidas para o portal_id.

Resposta — 200 OK

Mesma estrutura geral da rota offline; next_renew_date pode vir preenchido conforme retorno do portal.

{
  "plans": [
    {
      "name": "Destaque",
      "total": 20,
      "published": 18,
      "available": 2,
      "percentage_used": 90.0,
      "integrator_plan_id": 45,
      "is_for_new": false,
      "category": 1,
      "subscription_id": "sub-abc-123"
    }
  ],
  "next_renew_date": "2026-06-01",
  "updated_at": "2026-05-20T10:00:00Z"
}

Erros e respostas vazias

Situação	Comportamento típico
Portal sem consulta de planos na API	200 com plans: [] e next_renew_date vazio.
Falha de autenticação no portal ou erro no parceiro	500 Internal Server Error com corpo {} (objeto vazio).
Sem permissão na loja	403 Forbidden.
Credenciais / portal não configurados	Pode resultar em lista vazia ou 500, conforme o portal.

---

Qual rota escolher?

• Listagem em lote de portais com planos embutidos: GET /dealer/{dealer_id}/portal — veja Portais liberados.
• Publicar anúncio após escolher o plano: Por Onde Começar.

Métodos não suportados

Apenas GET está habilitado nessas URLs.