Introdução
Seja bem-vindo a nossa documentação!Referência da API
A esquerda estão listados todos os recursos disponíveis e cada um de seus endpoints determinando o que será consumido pela API.Todas as chamadas precisam ser enviadas com um token de acesso para (fornecido por nós) cliente e encaminhado para o integrador.
Toda a comunicação desta API será representada por objetos JSON.
Chamando a API
Veja como funciona a estrura de URL desta API.{URL_BASE_API}/via/{RECURSO}/{ENDPOINT}/{TOKEN}
-
{RECURSO}
Nome do recurso que deseja consumir. Por exemplo: produto, pedido...
-
{ENDPOINT}
Ação em si que determinará o que será consumido. Por exemplo: atualizar, cadastrar, consultar...
-
{TOKEN}
Substituir {TOKEN} pelo token único do cliente.
Respostas (responses)
- 429 Too Many Requests: Seu token de acesso estourou o limite diário de chamadas. Consulte abaixo sobre os limites.
- 401 Unauthorized: O token utilizado é inválido ou ainda não esta ativo.
- 400 Bad Request: A solicitação não foi bem sucedida e o item msg_erro será retornado.
- 200 OK: A solicitação foi realizada, porém o item retorno dirá se deu tudo certo através de um true ou false.
Para todas as duas situações acima o item status será retornado o código da resposta e o msg_alerta poderá ser retornado alertando que a chamada pode ser otimizada de alguma forma.
Limites de Requisições
Os limites de requisições existem para garantir a estabilidade, disponibilidade e desempenho da API, tanto para a sua integração quanto para os demais sistemas que utilizam a plataforma.
Uma integração pode realizar várias operações ao longo do dia, consumindo recursos de processamento, banco de dados, rede e outros recursos da infraestrutura.
Por esse motivo, a API possui limites que devem ser considerados durante o desenvolvimento e a operação da integração:
- 1 requisição por segundo;
- 2.500 requisições por dia;
- 20 registros por requisição para processamento em lote;
- 20 registros por página em cada consulta, consulte: Paginação de resultados.
Importante
Esses limites são compartilhados entre os tokens de uma mesma loja. Portanto, caso sua loja possua mais de um token de acesso, as requisições realizadas por todos os tokens serão contabilizadas conjuntamente. Dessa forma, o uso intensivo de um token pode consumir o limite disponível e impactar as demais integrações da loja.
O limite de requisições faz parte das condições técnicas de utilização da API e deve ser considerado desde o desenvolvimento da integração.
Caso a integração necessite de um volume de requisições superior aos limites padrão, entre em contato com nossa equipe para avaliarmos a necessidade e apresentarmos as opções disponíveis para ampliação do limite.
Paginação de resultados
Quando uma consulta retornar mais de 20 resultados será criado o item total_registros dentro de cabecalho como no exemplo abaixo:
Este padrão se aplica para qualquer tipo de consulta.
Para acessar as demais páginas basta adicionar o parâmetro ?pagina, por exemplo pagina=2, no GET da requisição.
{
"cabecalho": {
"paginacao": {
"total_registros": 52,
"limite_paginas": 20,
"total_paginas": 3,
"pagina_atual": 1,
"ultima_pagina": false
}
},
"item_solicitado": [...],
}
-
total_registros
Informa o total de registros sua busca possui desconsiderando a paginação.
-
limtie_paginas
Limite de registros por página.
-
total_paginas
Quantas páginas sua busca obteve.
-
pagina_atual
Em qual página está sua consulta.
-
ultima_pagina
Informa se a página atual é a ultima página ou não através de um true ou false
Webhook
A ViaShop notifica o ERP automaticamente sempre que ocorrerem eventos relevantes na plataforma, por meio de webhooks.
Webhook é uma forma de automatizar a comunicação entre dois sistemas, permitindo que um aplicativo envie informações em tempo real para outro sempre que um evento específico ocorre.
Sua utilização evita o polling, prática de realizar sucessivas requisições GET para verificar status de pedidos e/ou pagamentos. Por ser considerado uma má prática devido ao alto consumo de recursos, recomendamos fortemente a utilização dos nossos webhooks.
A não utilização de webhooks e a implementação de consultas periódicas (polling) gera consumo desnecessário de processamento, banda e infraestrutura, aumentando significativamente os custos operacionais da plataforma. Em cenários com alto volume de requisições, esse impacto pode se tornar relevante.
Caso o integrador opte por não utilizar webhooks e implemente consultas recorrentes à API (polling), deverá observar rigorosamente os limites de requisição definidos. Caso seja necessário ultrapassar os limites padrão para viabilizar o funcionamento da integração, poderá haver geração de custos adicionais de infraestrutura para a loja vinculada à integração.
Por esse motivo, a utilização de webhooks é considerada requisito técnico recomendado para integrações em ambiente de produção.
Acesse nossa documentação de webhook