Sua lista

A lista é a entrada de tudo: são os itens que você quer monitorar. Ela é sua e você mesmo manda - pelo console, subindo a planilha, ou pela API, quando o envio faz parte de uma rotina do seu sistema.

O que é uma linha da lista

Cada linha precisa de duas coisas: a página que a gente vai ler, e o seu código do item.

• url ou catalog_id - a página do item numa loja que a gente lê, ou o código do marketplace (MLB…/MLBU…), que a gente converte na página. Prefira a url: a leitura segue o redirecionamento da própria loja, então uma url que envelhece se conserta sozinha; um código digitado errado aponta para outro anúncio em silêncio.
• external_id - o seu código do item. É o de/para: volta em toda leitura, e é o que faz aquela linha ser sua.

ean, sku, name, brand, model e curve são opcionais: enriquecem o dado e ajudam você a se achar, mas não identificam o item.

Por que a url (ou o código) é obrigatória: o serviço é leitura - a gente lê o anúncio que você indica. Descobrir a que anúncio corresponde um item que chega só com EAN, código interno ou nome é correspondência de catálogo: comparação item a item com verificação, um serviço à parte. Linha sem os dois volta no relatório, nomeada, para você completar.

Por que o external_id é obrigatório: item que a gente guarda sem código seu chega de volta - na entrega e na fatura - como uma linha que ninguém do seu lado consegue dizer o que é. A regra vale nos dois sentidos: item que nós cadastrarmos sem código seu não entra na entrega nem na cobrança.

Mandar a mesma linha de novo não duplica. A identidade acima é a chave da linha, então reenviar a planilha corrigida adiciona só o que é novo - as repetidas voltam contadas em duplicated. Isso vale para os dois caminhos abaixo.

Pelo console (CSV)

Em console.geth.app, seção Lista de itens: escolha o arquivo e envie. Aceita , ou ; como separador e nomes de coluna em inglês (o do modelo) ou em português (link, nome, marca, modelo, curva, id_externo).

url;catalog_id;external_id;ean;name;curve
https://www.mercadolivre.com.br/produto-x/p/MLB1234567890;;SEU-COD-1;7891461329723;Produto X;A
;MLB1234567891;SEU-COD-2;7891461329730;Produto Y;B

A caixa substituir a lista atual troca a lista inteira pelo arquivo: o que não estiver nele sai de circulação. Desmarcada (o padrão), o arquivo é adição.

Pela API

Precisa de uma Secret key com a permissão catalog:write. Chave criada por você no console já vem com ela; chave antiga (só leitura) continua só de leitura - crie uma nova no console ou fale com a gente.

curl -X POST https://api.geth.app/v1/catalog/items \
  -H "Authorization: Bearer gk_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "append",
    "items": [
      { "external_id": "SEU-COD-1",
        "url": "https://www.mercadolivre.com.br/produto-x/p/MLB1234567890",
        "ean": "7891461329723", "name": "Produto X", "curve": "A" },
      { "external_id": "SEU-COD-2", "catalog_id": "MLB1234567891", "name": "Produto Y" }
    ]
  }'

mode é obrigatório

Não tem padrão, e é de propósito: só você sabe se aquele envio é uma adição ou a lista inteira, e chutar sai caro dos dois lados.

• append - junta: o que já está na lista fica como está.
• replace - aquele envio É a lista: o que não vier nele sai de circulação (fica inativo, não é apagado - dá para voltar atrás, e o histórico do que já foi coletado continua explicável). Um replace que não trouxe nenhuma linha aproveitável não retira nada: arquivo errado não zera a sua lista.

Até 20.000 itens por chamada. Lista maior vai em páginas com append, ou de uma vez como CSV pelo console.

A resposta

{
  "mode": "append",
  "received": 2,
  "inserted": 1,             // linhas novas
  "duplicated": 1,           // já estavam na lista - não é erro
  "skipped": 0,              // linhas que ficaram de fora (a soma das duas abaixo)
  "missing_identity": 0,      // sem url e sem catalog_id
  "missing_external_id": 0,   // sem o seu código do item
  "deactivated": 0,          // só se mode=replace
  "read_items_created": 1,   // linhas com url que já viraram item de leitura
  "unmatched_hosts": [],     // urls de loja que a gente não lê
  "errors": []               // problemas linha a linha (primeiros 20)
}

unmatched_hosts é a linha do relatório que ninguém pensa em pedir: a url apontava para uma loja que não está na sua configuração de coleta. A linha entrou na lista, mas não vira leitura enquanto aquela loja não existir para você.

Da lista para a leitura

Enviar não é o fim: a linha vira item de leitura para depois ser lida.

• Linha com url entra sozinha, na loja daquele link - a url já diz qual é.
• Linha só com código (EAN/SKU) precisa ser procurada em cada concorrente que você acompanha, e quais concorrentes é configuração do seu plano. Essas ficam aguardando - o relatório abaixo mostra quantas são.

{
  "catalog_items": 24500,        // linhas ativas da sua lista
  "catalog_without_read": 1200,  // ainda não viraram item de leitura
  "stores": [
    { "store_id": 468, "store_name": "Mercado Livre",
      "total": 23300, "resolved": 21100, "standalone": 1900,
      "failed": 100, "pending": 200 }
  ]
}

resolved = item identificado no catálogo da loja. standalone = existe, mas não tem página de catálogo (é anúncio avulso) - é resposta, não falha. pending/failed = ainda não identificado. A mesma leitura de identidade roda pela nossa fila, no ritmo dela; não é disparada pelo envio.

A lista como ela está hoje, paginada (envelope total_items/results). Vem só o que está ativo, que é a lista que a gente monitora hoje. Filtros: curve, q (nome/ean/sku) e status - INACTIVE mostra o que saiu num replace (fica guardado, é o que explica leitura antiga) e ALL mostra tudo. Ler a lista e o relatório pede só a chave de leitura.

Cobrança

Mandar a lista, ler a lista e ler o relatório não são cobrados. O faturável nasce na coleta - ver Uso e faturamento.