Formato das respostas #
Toda resposta é JSON. Campos que podem aparecer em qualquer rota:
| Campo | Significado |
|---|---|
retorno | true = a operação foi feita. false = não foi. Sempre confira este campo, mesmo com HTTP 200. |
status | O código HTTP, repetido no corpo. |
msg | Mensagem de sucesso. |
msg_erro | Motivo da recusa. |
msg_alerta | Aviso: a operação foi feita, mas algo merece atenção (ex.: itens descartados, vendedor não encontrado). |
cod_erro | Código do erro de limite (limite_requisicoes_dia, limite_requisicoes_segundo). |
Códigos HTTP #
| HTTP | Quando | Tentar de novo? |
|---|---|---|
200 com retorno: true | Sucesso. | — |
200 com retorno: false | Recusa de regra de negócio em algumas rotas (ex.: foto já enviada, cliente já existente). | Não. Leia msg_erro. |
400 | Dados inválidos, campo faltando, registro não encontrado. | Não sem corrigir o envio. |
401 | Token inválido ou ainda não ativo. | Não. Confira o token. |
409 | Cadastro 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_segundo | Mais de 1 requisição no mesmo segundo. | Sim, depois de 1 segundo. |
429 + cod_erro: limite_requisicoes_dia | Limite diário da loja atingido. | Só no dia seguinte. |
500 | Erro 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 #
| Limite | Valor |
|---|---|
| Requisições por segundo | 1 |
| Requisições por dia | 2.500 por loja, somando todos os tokens da loja |
| Itens por lote | 20 |
| Registros por página nas consultas | 20 (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
429por segundo, espere e tente de novo; em429por 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).