Sincronizar o catálogo

O ERP é a origem do catálogo. A loja lê, nunca escreve: não há endpoint para criar produto, preço ou estoque. Este guia mostra a ordem de leitura que evita referência quebrada e como manter a loja atualizada sem reler a base inteira.

Todos os exemplos usam os cabeçalhos de autenticação, omitidos aqui por brevidade.

A ordem

Cada entidade referencia as anteriores por código. Lida nesta ordem, nada aponta para o que a loja ainda não tem:

#	Endpoint	Traz	Referenciado por
1	/grupos	Grupos de produto, com hierarquia	produto
2	/marcas	Marcas	produto
3	/grades e /cores	Cadastros de grade (tamanho, volume) e de cor	produto, estoque, pedido
4	/tabelas-preco	Tabelas de preço	preço do produto, item do pedido
5	/promocoes	Promoções e vigência	preço do produto
6	/produtos	Produtos com grades, cores, preços, imagens, fornecedores e composição	estoque, pedido
7	/codigos-barras	Código de barras por produto, grade e cor	busca na loja
8	/estoque	Quantidade por produto, grade e cor	reposição

/filiais e /fornecedores são cadastros de apoio. /filiais lista todas as filiais da empresa; a credencial vale para uma delas, cujo código vem em GET /integracao. Os fornecedores já vêm dentro de cada produto.

Grupos

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/grupos?pagina=1&tamanhoPagina=200&ordenarPor=hierarquia"

hierarquia é o nível, com 1 no topo, e codigoPai aponta para o grupo acima. Para montar a árvore de categorias da loja, leia todos e ligue cada grupo ao codigoPai; um grupo com codigoPai nulo é raiz. O filtro hierarquia=1 traz só as raízes.

Grades e cores

O ERP trata grade e cor como dois eixos independentes: a grade representa tamanho ou volume, e a cor é um segundo nível dentro da grade. Um produto tem uma ou mais grades na filial, e cada grade pode ter cores ou não.

Os cadastros em /grades e /cores são só nome e código. O que importa para a loja é a combinação que cada produto tem, e ela vem dentro de /produtos.

Produtos

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/produtos?exportarParaEcommerce=true&ativo=true&pagina=1&tamanhoPagina=100"

Um produto vem inteiro em uma resposta. O exemplo abaixo omite alguns campos; a lista completa está na referência.

{
  "codigo": 10,
  "descricao": "CAMISETA BÁSICA",
  "nomeProduto": "Camiseta básica de algodão",
  "sku": "CAM-BAS",
  "grupo": 3,
  "grupoDescricao": "VESTUÁRIO",
  "marca": 7,
  "marcaDescricao": "MARCA PRÓPRIA",
  "unidade": "UN",
  "exportarParaEcommerce": true,
  "dataUltimaAtualizacao": "2026-09-20T14:05:11",
  "ativo": true,
  "grades": [
    {
      "linhaId": 5501,
      "codigo": 2,
      "descricao": "M",
      "quantidade": 12,
      "cores": [
        { "codigo": 1, "descricao": "BRANCO", "quantidade": 8 },
        { "codigo": 4, "descricao": "PRETO", "quantidade": 4 }
      ]
    },
    { "linhaId": 5502, "codigo": 3, "descricao": "G", "quantidade": 3, "cores": [] }
  ],
  "precos": [
    { "tabelaPreco": 1, "tabelaPrecoDescricao": "VAREJO", "valorVenda": 59.90, "quantidade": 0, "promocao": null }
  ],
  "imagens": [ { "codigo": 1, "titulo": "Frente", "textoAlternativo": null, "principal": true } ],
  "fornecedores": [],
  "composicao": []
}

O que cada bloco significa:

• grades: as variações do produto nesta filial, com a quantidade destinada ao e-commerce em cada uma. codigo é o código do cadastro de grades, o mesmo que o pedido informa em grade. Uma grade com cores vazia é vendida sem cor; com cores, o pedido precisa informar qual.
• precos: um por tabela de preço. quantidade é a partir de quantos itens aquela tabela vale; zero é o preço unitário comum. Quando há promoção aplicada, promocao e promocaoDescricao vêm preenchidos e valorVenda já é o valor promocional; o percentual e a vigência estão em /promocoes.
• imagens: só os identificadores, o título e o texto alternativo. O arquivo vem em outro endpoint, abaixo.
• exportarParaEcommerce: a marcação feita no ERP. Filtre por true para trazer só o que a filial decidiu vender online.
• Campos para a vitrine: nomeProduto é o nome comercial, quando preenchido; descricao é a do cadastro; detalhes é o texto de apresentação; tags, altura, largura e profundidade vêm como o ERP os guarda.

Grade única

Produto sem variação ainda tem uma grade cadastrada na filial. A loja não precisa mostrá-la, mas ela existe: é o que permite omitir grade no pedido desse produto.

Imagens

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/produtos/10/imagens/1" -o camiseta.jpg

O segundo número da rota é o codigo da imagem na lista imagens do produto. A resposta é o arquivo, com Content-Type da imagem e Content-Disposition: inline. A URL não serve num <img src>: o navegador não envia os cabeçalhos de autenticação. Baixe do lado do servidor e hospede no seu CDN.

Sincronização incremental

dataUltimaAtualizacao muda quando o cadastro do produto é alterado no ERP. Guarde o maior valor da leitura e, na próxima, peça só o que mudou:

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/produtos?alteradoApartirDe=2026-09-20T14:05:11&ordenarPor=dataUltimaAtualizacao"

O filtro é inclusivo, então o último produto da leitura anterior volta; ignore-o pelo código. Preço e estoque não movem essa data: são lidos pelos endpoints próprios.

Preços e promoções

O preço de venda já vem dentro do produto, por tabela. /tabelas-preco serve para a loja saber o nome e o código de cada tabela, e é o código que o item do pedido informa em tabelaPreco.

/promocoes?vigentesEm=2026-09-25 lista as promoções válidas numa data, com o percentual e o período. O produto já traz o preço promocional em valorVenda; a lista serve para exibir o preço original, o percentual e até quando a promoção vale, cruzando pelo código em promocao.

Estoque

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/estoque?comSaldo=true&pagina=1&tamanhoPagina=100"

Uma linha por produto e grade, com as cores dentro, igual ao bloco grades do produto, mas sem o resto do cadastro. É o endpoint para atualização frequente: devolve menos dados que /produtos e aceita produto= para consultar um só.

quantidade é a quantidade que o ERP destina ao e-commerce, não o saldo físico da filial. O recebimento do pedido não baixa esse número: a baixa acontece quando o ERP fatura. Entre o pedido e o faturamento, a loja precisa descontar do lado dela o que já vendeu.

Códigos de barras

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/codigos-barras?codigoProduto=10"

Cada código aponta para produto, grade e cor. É como a loja identifica a variação a partir do código de barras; /produtos?codigoBarras= faz o caminho inverso, trazendo o produto inteiro.

Clientes

/clientes lista os clientes da filial, com endereços, e-mails e telefones. A loja normalmente não precisa dele: o pedido cadastra o comprador quando o CPF/CNPJ ainda não existe. Serve para conciliação e para obter o código do cliente usado no filtro cliente= de /pedidos.

Um ciclo típico

1. Carga inicial, uma vez: as oito leituras acima, na ordem, paginando até temProxima: false.
2. A cada poucos minutos: /estoque?comSaldo=true.
3. A cada hora: /produtos?alteradoApartirDe=... e /promocoes?vigentesEm=hoje.
4. Uma vez por dia: grupos, marcas, grades, cores e tabelas de preço, que mudam pouco.

Com páginas de 100 e uma filial de 5.000 produtos, a carga inicial fica em torno de 60 requisições, dentro da cota de um minuto.