API ViaShopModa documentação

Erros, limites e paginação

Como interpretar cada resposta de erro, quando tentar de novo e como paginar consultas sem estourar o limite.

Ver como Markdown Atualizado em 18/11/2026

Formato das respostas #

Toda resposta é JSON. Campos que podem aparecer em qualquer rota:

CampoSignificado
retornotrue = a operação foi feita. false = não foi. Sempre confira este campo, mesmo com HTTP 200.
statusO código HTTP, repetido no corpo.
msgMensagem de sucesso.
msg_erroMotivo da recusa.
msg_alertaAviso: a operação foi feita, mas algo merece atenção (ex.: itens descartados, vendedor não encontrado).
cod_erroCódigo do erro de limite (limite_requisicoes_dia, limite_requisicoes_segundo).

Códigos HTTP #

HTTPQuandoTentar de novo?
200 com retorno: trueSucesso.—
200 com retorno: falseRecusa de regra de negócio em algumas rotas (ex.: foto já enviada, cliente já existente).Não. Leia msg_erro.
400Dados inválidos, campo faltando, registro não encontrado.Não sem corrigir o envio.
401Token inválido ou ainda não ativo.Não. Confira o token.
409Cadastro duplicado (ex.: cliente/cadastrar com CPF/e-mail já existente).Não. Use o registro existente (cod_cliente vem na resposta).
429 + cod_erro: limite_requisicoes_segundoMais de 1 requisição no mesmo segundo.Sim, depois de 1 segundo.
429 + cod_erro: limite_requisicoes_diaLimite diário da loja atingido.Só no dia seguinte.
500Erro interno.Uma vez, depois de alguns minutos. Se repetir, envie a resposta para api@viashopmoda.com.br.

Exemplo de recusa:

{
  "retorno": false,
  "status": 400,
  "msg_erro": "Objeto 'pedido' não enviado"
}

Operações em lote #

Rotas que recebem lista (estoque/atualizar, preco/atualizar, cod_barras/atualizar, cod_externo/associar…) processam item a item e respondem com o resultado de cada um:

{
  "retorno": true,
  "qtd_atualizar": 3,
  "qtd_atualizados": 2,
  "qtd_nao_atualizados": 1,
  "atualizados": [ ... ],
  "nao_atualizados": [ ... ]
}

retorno: true significa que o lote foi processado — não que todos os itens deram certo. Sempre leia nao_atualizados (e erros, quando existir) e corrija só esses itens.

Limites #

LimiteValor
Requisições por segundo1
Requisições por dia2.500 por loja, somando todos os tokens da loja
Itens por lote20
Registros por página nas consultas20 (estoque sem filtro: 100)

Consulte o saldo do dia com limites_api/consultar.

Boas práticas #

  • Fila no ERP com no máximo 1 requisição por segundo.
  • Agrupe até 20 itens por lote em vez de 20 requisições de 1 item.
  • Envie só o que mudou.
  • Use webhooks para saber de novidades; deixe consultas periódicas para conferência, com folga.
  • Em 429 por segundo, espere e tente de novo; em 429 por dia, pare e registre.

Paginação #

Consultas com mais de 20 resultados trazem cabecalho.paginacao:

{
  "cabecalho": {
    "paginacao": {
      "total_registros": 52,
      "limite_paginas": 20,
      "total_paginas": 3,
      "pagina_atual": 1,
      "ultima_pagina": false
    }
  }
}

Peça pagina=2, pagina=3… até ultima_pagina ser true. Cada página é uma requisição e conta no limite.

Rotas assíncronas #

imagens/upload, pedido/associar_codexterno e cliente/associar_codexterno não executam na hora: a resposta traz automacao_id, e o resultado final aparece em automacao/consultar (status cadastrado, pendente, enviado ou erro).