Pular para o conteúdo principal

Por Onde Começar

Este guia explica o processo completo para enviar uma integração de anúncio para um portal.

Pré-requisitos​

Antes de começar, certifique-se de que:

  1. ✅ O processo de autenticação/liberação do portal já foi realizado - Consulte o guia Como Autenticar em um Portal para mais detalhes
  2. ✅ Você possui um anúncio criado - O anúncio deve ter sido criado previamente através do endpoint /v3/inventory/{dealer_id} (consulte o guia Como Criar um Novo Anúncio)

Passo a Passo​

Passo 1: Consultar Portais Liberados​

Primeiro, você precisa consultar quais portais estão liberados para sua loja:

GET /dealer/{dealer_id}/portal

Este endpoint retorna uma lista de portais disponíveis para integração. Cada portal contém informações sobre:

  • ID do portal (portal.id)
  • Planos disponíveis (listing_type)
  • Categorias habilitadas (category)

Exemplo de Resposta:

[
  {
    "id": 1,
    "portal": {
      "id": 5,
      "name": "Webmotors",
      "logo": "https://media.integradordeanuncios.com.br/media/logo/webmotors.webp",
      ...
    },
    "listing_type": [
      {
        "id": 1,
        "name": "Plano Básico",
        "total": 100,
        "published": 50,
        "available": 50,
        ...
      }
    ],
    "category": [1, 2]
  }
]

Passo 2: Verificar Disponibilidade do Plano​

No objeto listing_type, verifique:

  • available: Quantidade de anúncios disponíveis para publicação no plano
  • total: Total de anúncios permitidos no plano
  • published: Quantidade já publicada
aviso

Certifique-se de que o campo available seja maior que 0 antes de tentar integrar um anúncio.

Exemplo:

{
  "id": 1,
  "name": "Plano Básico",
  "total": 100,
  "published": 50,
  "available": 50,  // ← Deve ser > 0
  "percentage_used": 50.0
}

Passo 3: Verificar Categoria Habilitada​

No array category, verifique se a categoria do seu anúncio está presente:

  • 1 = Automóvel
  • 2 = Motocicleta
  • 3 = Caminhão
  • 4 = Implemento
aviso

O portal só aceitará integrações de anúncios cuja categoria esteja presente no array category.

Exemplo:

{
  "category": [1, 2]  // Portal aceita apenas Automóvel e Motocicleta
}

Se você tentar integrar um anúncio de Caminhão (categoria 3) neste portal, a integração falhará.

Passo 4: Selecionar o Plano​

Utilize o campo id do objeto em listing_type como o plan_id que será enviado na requisição de integração.

Exemplo:

Se você escolher o plano "Plano Básico" com id: 1, esse será o plan_id a ser usado.

Passo 5: Criar a Integração​

Envie um POST para o endpoint /integration com o seguinte payload:

Endpoint:

POST /integration

Payload:

{
  "ad_id": 12345,
  "site_id": 5,
  "plan_id": 1,
  "price": 85000
}

Campos do Payload​

CampoTipoDescrição
ad_idintegerID do anúncio criado anteriormente (obtido ao criar o anúncio via /v3/inventory/{dealer_id})
site_idintegerID do portal (obtido de portal.id no endpoint /dealer/{dealer_id}/portal)
plan_idintegerID do plano escolhido (obtido de listing_type[].id no endpoint /dealer/{dealer_id}/portal)
priceintegerPreço do anúncio em reais (número inteiro, sem centavos)
dica

O ad_id é retornado quando você cria um anúncio através do endpoint /v3/inventory/{dealer_id}. Guarde esse ID para usar nas integrações.

Exemplo Completo​

Vamos supor que você:

  1. Criou um anúncio de automóvel e recebeu ad_id: 12345
  2. Consultou os portais e encontrou o Webmotors (site_id: 5)
  3. Verificou que o portal aceita categoria 1 (Automóvel) ✅
  4. Escolheu o "Plano Básico" com id: 1 e available: 50 ✅
  5. O preço do anúncio é R$ 85.000,00

Requisição:

POST /integration
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ad_id": 12345,
  "site_id": 5,
  "plan_id": 1,
  "price": 85000
}

Resposta de Sucesso​

Status Code: 201 Created

{
  "status": true,
  "message": "Integração criada com sucesso",
  "data": {
    "id": 67890,
    "portal": 5,
    "portal_name": "Webmotors",
    "status": 1,
    "plan": 1,
    "plan_name": "Plano Básico",
    "link": "https://www.webmotors.com.br/anuncio/12345",
    "title": "Chevrolet Onix 1.0 2023/2024",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Possíveis Retornos de Erro​

400 Bad Request​

Tipo de Anúncio Inválido​

Retornado quando o plan_id informado não é válido para o portal ou não está disponível.

{
  "message": "Tipo de anúncio inválido para o portal",
  "status": false,
  "error": "O plano informado não está disponível para este portal"
}

Validação de Campos​

Retornado quando há erros de validação nos dados enviados.

{
  "ad_id": ["Este campo é obrigatório."],
  "site_id": ["Este campo é obrigatório."],
  "plan_id": ["Este campo é obrigatório."],
  "price": ["Este campo é obrigatório."]
}

401 Unauthorized​

Erro de Autenticação no Portal​

Retornado quando há problema na autenticação da loja no portal.

{
  "message": "Erro ao autenticar loja no portal",
  "status": false,
  "error": "Credenciais inválidas ou expiradas"
}

Token JWT Inválido​

Retornado quando o token de autenticação não foi fornecido ou é inválido.

{
  "detail": "As credenciais de autenticação não foram fornecidas."
}

ou

{
  "detail": "Token inválido ou expirado."
}

403 Forbidden​

Retornado quando o usuário autenticado não tem permissão para acessar este recurso.

{
  "detail": "Você não tem permissão para executar essa ação."
}

500 Internal Server Error​

Retornado quando ocorre um erro interno no servidor durante o processamento da integração.

{
  "message": "Erro ao criar integração",
  "status": false,
  "error": "Erro interno do servidor"
}

Checklist Antes de Integrar​

Antes de enviar uma integração, verifique:

  • O portal está liberado para a loja (/dealer/{dealer_id}/portal)
  • O portal aceita a categoria do anúncio (category contém a categoria do anúncio)
  • O plano escolhido tem disponibilidade (available > 0)
  • O ad_id corresponde a um anúncio válido e ativo
  • O site_id corresponde ao ID do portal escolhido
  • O plan_id corresponde ao ID do plano escolhido
  • O price está em reais, sem centavos (número inteiro)

Próximos Passos​

Após criar a integração com sucesso:

  • Consulte o status da integração através do endpoint GET /integration?ad_id={ad_id}
  • Monitore as integrações ativas através dos relatórios disponíveis
  • Atualize ou remova integrações conforme necessário