Pular para conteúdo

Compatibilidade Veicular

Use a API de compatibilidade para associar anúncios de autopeças aos veículos em que a peça pode ser aplicada. O fluxo é por anúncio, canal e conta, não por produto ou SKU.

Todas as rotas deste guia começam com /integration/v1/compatibilities. As respostas são objetos ou listas JSON. A única resposta paginada é a lista de anúncios pendentes (GET /pending).

O fluxo típico em lote é:

  1. GET /platforms: canais, contas e regras do funil de cada canal.
  2. GET /pending: anúncios que o canal marcou como pendentes de compatibilidade.
  3. GET /categories/{categoryId}: a categoria desses anúncios aceita compatibilidade?
  4. POST /filters/options: percorra o funil, um filtro por vez.
  5. POST /vehicles/search: veículos que casam com os filtros escolhidos.
  6. POST no caminho base: aplique aos adIds obtidos no passo 2.

Antes de começar

  • Obtenha um token OAuth2 seguindo o guia do desenvolvedor.
  • Solicite ad:view para consultas e ad:edit para alterações. Para executar o fluxo inteiro, solicite ambos; não presuma que escrita inclui leitura.
  • Tenha uma conta ativa no canal e anúncios já publicados nessa conta.
  • Use o adId da Gubee, não o SKU nem o ID do anúncio no marketplace. Veja Anúncio vs Produto.

Nos exemplos, $GUBEE_API é a URL base da API e $JWT é o token de acesso. Todos os identificadores de exemplo são ilustrativos: substitua pelos valores retornados para sua conta. Não envie sellerId: o lojista é identificado pelo token.

Operações e permissões

Os caminhos abaixo são relativos a /integration/v1/compatibilities. Todas as operações retornam 200 quando bem-sucedidas; PUT e DELETE não retornam corpo.

Método Caminho Escopo Finalidade
GET /platforms ad:view Descobrir canais, contas e filtros
GET /pending ad:view Listar anúncios pendentes de compatibilidade
GET /categories/{categoryId} ad:view Consultar regras da categoria
POST /filters/options ad:view Consultar opções de um filtro
POST /vehicles/search ad:view Buscar veículos
GET /positions ad:view Consultar posições/aplicações
GET /ads/{adId} ad:view Ler compatibilidades de um anúncio
POST /search ad:view Ler compatibilidades em lote
POST caminho base ad:edit Aplicar compatibilidades em lote
PUT /ads/{adId} ad:edit Substituir compatibilidades de um anúncio
DELETE /ads/{adId} ad:edit Remover compatibilidades por ID

Os três POSTs de consulta são somente leitura, apesar do método HTTP.

1. Descobrir canais e contas

curl "$GUBEE_API/integration/v1/compatibilities/platforms" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json"

Exemplo de resposta para um lojista com conta ativa no Mercado Livre:

[
  {
    "platform": "MERCADOLIVRE",
    "requiredFilters": ["BRAND", "MODEL"],
    "optionalFilters": ["VEHICLE_YEAR", "TRIM", "ENGINE", "FUEL_TYPE", "POWER", "VEHICLE_BODY_TYPE", "TRANSMISSION"],
    "noteSemantics": "OBSERVATION",
    "accountIds": ["conta-ml-01"],
    "pendingTag": "incomplete_compatibilities"
  }
]

A lista contém apenas canais suportados em que o lojista possui conta ativa. Uma lista vazia significa que não há contas disponíveis para esse fluxo. Selecione o accountId dessa resposta e mantenha o mesmo par platform + accountId nas chamadas seguintes.

Canal Filtros obrigatórios Filtros opcionais Significado de note
MERCADOLIVRE BRAND, MODEL VEHICLE_YEAR, TRIM, ENGINE, FUEL_TYPE, POWER, VEHICLE_BODY_TYPE, TRANSMISSION OBSERVATION: observação
SHOPEE BRAND, MODEL, VEHICLE_YEAR TRIM OBSERVATION: observação
MAGALU BRAND, MODEL, VEHICLE_YEAR TRIM PART_NUMBER: código da peça

pendingTag é a tag que o canal aplica aos anúncios que ainda precisam de compatibilidade. É o mesmo marcador usado por GET /pending (próximo passo).

Consuma os metadados de /platforms em vez de fixar essa tabela no seu sistema. O suporte a compatibilidade não abrange necessariamente todos os canais do catálogo de plataformas.

2. Listar anúncios pendentes de compatibilidade

Descubra quais anúncios da conta o canal marcou como pendentes de compatibilidade. É o mesmo conjunto exibido pelo filtro rápido "pendente de compatibilidade" do painel do lojista.

curl --get "$GUBEE_API/integration/v1/compatibilities/pending" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01" \
  --data-urlencode "page=0" \
  --data-urlencode "size=20"
Parâmetro Obrigatório Descrição
platform sim Canal retornado por /platforms
accountId sim Conta do lojista nesse canal, retornada por /platforms
categoryIds não Restringe a categorias do canal. Repita o parâmetro para enviar várias
page não Página, começando em 0 (padrão 0)
size não Itens por página (padrão 20)

Exemplo de resposta:

{
  "content": [
    {
      "adId": "anuncio-01",
      "marketplaceId": "ITEM-EXEMPLO",
      "sku": "SKU-EXEMPLO",
      "name": "Pastilha de freio dianteira",
      "categoryId": "CATEGORIA-EXEMPLO",
      "accountId": "conta-ml-01"
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalElements": 1,
  "totalPages": 1,
  "first": true,
  "last": true
}
  • adId: ID do anúncio na Gubee, o valor que você envia em adIds ao aplicar.
  • marketplaceId: ID do anúncio no canal, apenas informativo.
  • categoryId: categoria do anúncio no canal; use-a no passo seguinte.

Avance page até last ser true. Como o funil de veículos é por categoria, agrupe os anúncios por categoryId ou filtre com categoryIds para montar um lote por categoria:

curl --get "$GUBEE_API/integration/v1/compatibilities/pending" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01" \
  --data-urlencode "categoryIds=CATEGORIA-EXEMPLO"

A marcação de pendência é feita pelo canal. Depois de aplicar compatibilidades, o anúncio pode continuar na lista até o canal atualizar a tag; não use a presença na lista como indicação de falha da aplicação. Confira o resultado com GET /ads/{adId} ou POST /search (passo 8).

Alternativa: filtrar pela busca de anúncios

Se sua integração já usa a busca de anúncios, filtre diretamente pela tag em POST /integration/ads/list/search/{platform}, enviando no corpo {"tags": ["incomplete_compatibilities"], "accountIds": ["conta-ml-01"]}. Use o valor de pendingTag retornado por /platforms em vez de fixar a string. A resposta traz o anúncio completo; /pending devolve só os campos necessários para o fluxo de compatibilidade.

3. Consultar a categoria

Use o categoryId do anúncio no canal, retornado por /pending:

curl --get "$GUBEE_API/integration/v1/compatibilities/categories/CATEGORIA-EXEMPLO" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01"

Exemplo de resposta:

{
  "id": "CATEGORIA-EXEMPLO",
  "domainId": "DOMINIO-EXEMPLO",
  "required": true,
  "noteSupported": true,
  "restrictionsSupported": true
}
  • domainId: domínio usado na consulta de posições.
  • required: o canal exige compatibilidade para anunciar nessa categoria.
  • noteSupported: a categoria aceita note.
  • restrictionsSupported: a categoria aceita restrições de aplicação.

required: false não significa, sozinho, que compatibilidade não é suportada. Não existe um campo supported nessa resposta. Quando não há categoria de compatibilidade retornada, id e domainId ficam nulos e os booleanos ficam false; não prossiga para posições sem um domainId válido.

4. Percorrer os filtros

Comece consultando as marcas, sem filtros anteriores:

curl -X POST "$GUBEE_API/integration/v1/compatibilities/filters/options" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "filterId": "BRAND",
    "knownFilters": []
  }'

Cada opção é um par id/name:

[
  {"id": "marca-01", "name": "Marca de exemplo"}
]

Para abrir modelos, acumule a marca escolhida em knownFilters:

curl -X POST "$GUBEE_API/integration/v1/compatibilities/filters/options" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "filterId": "MODEL",
    "knownFilters": [
      {"id": "BRAND", "valueIds": ["marca-01"]}
    ]
  }'

Repita para os demais filtros, acrescentando as escolhas anteriores. Na Shopee ou no Magalu, consulte também VEHICLE_YEAR, com marca e modelo já escolhidos. Use IDs retornados pelo catálogo em valueIds, não os nomes de exibição.

5. Buscar veículos

Envie os filtros escolhidos em filters, não em knownFilters:

curl -X POST "$GUBEE_API/integration/v1/compatibilities/vehicles/search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "filters": [
      {"id": "BRAND", "valueIds": ["marca-01"]},
      {"id": "MODEL", "valueIds": ["modelo-01"]}
    ]
  }'

Exemplo de resposta:

[
  {
    "id": "veiculo-01",
    "attributes": [
      {
        "id": "MODEL",
        "name": "Modelo",
        "valueId": "modelo-01",
        "valueName": "Modelo de exemplo",
        "hasValue": true
      }
    ]
  }
]

Guarde o id do veículo: ele será enviado como vehicleId na aplicação. Preencha todos os requiredFilters do canal. Filtros incompletos podem resultar em lista vazia, em vez de erro de validação; confira o funil antes de concluir que não existem veículos compatíveis.

6. Consultar posições e montar restrições

Se restrictionsSupported for true, consulte o domínio da categoria:

curl --get "$GUBEE_API/integration/v1/compatibilities/positions" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01" \
  --data-urlencode "domainId=DOMINIO-EXEMPLO"

A resposta é uma lista de grupos de valores:

[
  {"values": [{"id": "posicao-01", "name": "Dianteira"}]}
]

Uma restrição no corpo de aplicação ou atualização tem esta estrutura:

{
  "attributeId": "ATRIBUTO-DE-POSICAO-DO-CANAL",
  "attributeValues": [
    {"values": [{"id": "posicao-01", "name": "Dianteira"}]}
  ]
}

attributeId identifica o atributo de restrição aceito pelo canal; não é o domainId nem o ID da posição. A resposta de /positions fornece grupos de valores, mas não informa esse atributo. Não invente um ID genérico: confirme-o para o canal ou preserve o atributo de uma compatibilidade existente consultada em /ads/{adId}. Se não precisar de restrições, envie restrictions: [].

7. Aplicar aos anúncios

Envie os adIds obtidos em /pending, até 100 adIds por chamada. O mesmo conjunto de veículos, notas e restrições será enviado para todos os anúncios válidos do lote.

curl -X POST "$GUBEE_API/integration/v1/compatibilities" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "adIds": ["anuncio-01", "anuncio-02"],
    "compatibilityProducts": [
      {"vehicleId": "veiculo-01", "note": "Aplicável à versão informada", "restrictions": []}
    ]
  }'

Inclua note apenas quando a categoria permitir. No Magalu, esse campo representa o part number, não uma observação livre.

Exemplo de sucesso parcial (200):

{
  "appliedAdIds": ["anuncio-01"],
  "invalidAds": [
    {"adId": "anuncio-02", "reason": "AD_NOT_PUBLISHED"}
  ]
}

appliedAdIds identifica os anúncios enviados ao canal. Não é um relatório individual de validação de cada veículo. Consulte as compatibilidades depois da alteração para conferir o resultado; não trate somente o HTTP 200 como sucesso de todos os itens.

8. Consultar o resultado

Um anúncio

curl --get "$GUBEE_API/integration/v1/compatibilities/ads/anuncio-01" \
  -H "Authorization: Bearer $JWT" \
  -H "Accept: application/json" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01"

{
  "adId": "anuncio-01",
  "marketplaceId": "ITEM-EXEMPLO",
  "compatibilities": [
    {
      "id": "compatibilidade-01",
      "vehicle": {"id": "veiculo-01", "attributes": []},
      "note": "Aplicável à versão informada",
      "restrictions": []
    }
  ]
}

O id de cada item de compatibilities é o ID da compatibilidade usado para remoção. Ele é diferente de vehicle.id e de adId.

Em lote

curl -X POST "$GUBEE_API/integration/v1/compatibilities/search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "adIds": ["anuncio-01", "anuncio-02"]
  }'

O limite também é de 100 anúncios. A resposta contém compatibilities (lista de objetos com adId, marketplaceId e compatibilities, como acima) e invalidAds. Relacione os resultados pelo adId, não pela posição na lista.

9. Substituir ou remover

Substituir o conjunto de um anúncio

Substituição, não atualização parcial

Envie em compatibilityProducts o conjunto completo que deseja manter. Não use PUT como se fosse uma operação de adicionar apenas um veículo.

curl -X PUT "$GUBEE_API/integration/v1/compatibilities/ads/anuncio-01" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "MERCADOLIVRE",
    "accountId": "conta-ml-01",
    "compatibilityProducts": [
      {"vehicleId": "veiculo-02", "restrictions": []}
    ]
  }'

Resposta: 200, sem corpo.

Remover compatibilidades específicas

Use de 1 a 50 IDs de compatibilidade por chamada, obtidos na leitura do anúncio. Repita o parâmetro compatibilityIds para enviar mais de um:

curl --get -X DELETE "$GUBEE_API/integration/v1/compatibilities/ads/anuncio-01" \
  -H "Authorization: Bearer $JWT" \
  --data-urlencode "platform=MERCADOLIVRE" \
  --data-urlencode "accountId=conta-ml-01" \
  --data-urlencode "compatibilityIds=compatibilidade-01" \
  --data-urlencode "compatibilityIds=compatibilidade-02"

Resposta: 200, sem corpo. Para remover um conjunto maior, divida os IDs em lotes de até 50; não envie IDs de veículos no lugar dos IDs de compatibilidade.

Erros e resultados parciais

HTTP Situação Como tratar
400 Canal sem suporte, accountId em branco, mais de 100 anúncios ou DELETE sem IDs/com mais de 50 IDs Corrija os parâmetros e divida os lotes
400 Em operação individual: anúncio não publicado, de outro canal ou de outra conta Confira publicação, platform e accountId
403 Conta indisponível para o lojista/canal ou escopo insuficiente Confira as contas ativas em /platforms e os escopos do token
404 Em operação individual: anúncio inexistente ou de outro lojista Confira o adId e a identidade autenticada

Em /search e na aplicação em lote, problemas de identificação dos anúncios aparecem em invalidAds, sem impedir o envio dos anúncios válidos:

reason Significado
AD_NOT_FOUND Anúncio inexistente ou não disponível para o lojista
AD_NOT_PUBLISHED Anúncio ainda sem identificador no marketplace
AD_PLATFORM_MISMATCH Anúncio pertence a outro canal
AD_ACCOUNT_MISMATCH Anúncio pertence a outra conta

Essa resposta parcial não cobre qualquer falha do marketplace: uma falha na chamada ao canal pode fazer a requisição falhar. Depois de um timeout de escrita, consulte o estado antes de repetir a operação; não presuma idempotência do POST.

Separe os lotes por canal e conta, registre invalidAds e só reprocesse os itens após corrigir sua causa. Se todos os anúncios forem inválidos, o retorno pode ser 200 com appliedAdIds: [] e os motivos em invalidAds.

Próximos passos