Estratégias para o Consumo de Pedidos
Boas práticas para consumir informações de pedidos da API
Existem diversas estratégias possíveis para consumir os pedidos de uma loja que utiliza a tecnologia da Wake Commerce, cada uma com características, benefícios e níveis de dificuldade de implementação distintos.
Abaixo, separamos 2 principais estratégias:
- API Pooling: consulta em massa de pedidos com intervalo de consultas
- Web Hooks: consulta de pedidos específicos sob demanda
Representação da diferença entre as estratégias
A seguir, detalharemos as duas estratégias e as obrigações dos integradores em relação à implementação dos controles de “rate-limit”.
API Pooling
API Pooling é o processo onde o intermediador realiza consultas repetidamente a cada intervalo de tempo, que pode ser de alguns segundos ou minutos.
Na API da Wake, o endpoint GET /pedidos pode ser utilizado para buscar pedidos por data, utilizando os parâmetros “dataInicial” e “dataFinal”. A resposta dessa API é paginada, retornando até 50 pedidos por página e o total de registros em um header chamado “x-total-count”.
Existem diversos parâmetros possíveis nesta API, todos documentados no artigo consultando uma listagem de pedidos.
Vantagens
A grande vantagem dessa estratégia é a capacidade de buscar grandes quantidades de pedidos, chegando a até 360 mil pedidos por hora. Isso pode ser necessário na importação de dados históricos, construção de relatórios, BIs, Data Warehouses, entre outros.
Outra vantagem dessa estratégia é a simplicidade, já que é uma integração onde o integrador não precisa expor APIs Públicas para receber Web Hooks, o que geralmente reduz a complexidade do desenvolvimento.
Desvantagens
A desvantagem dessa estratégia é que ela não é uma estratégia de tempo-real, ou seja, os pedidos estarão sempre com um _delay _de atualização no sistema que estiver consumindo (ERP e demais integradores). Esse atraso será definido pelo intervalo de tempo que o integrador executa a busca de pedidos. Apesar disso, essa característica nem sempre é um problema, dependendo muito do tipo de negócio de cada cliente.
Por isso, é importante mapear previamente as necessidades do seu cliente antes de escolher o método que será utilizado na integração de pedidos.
Outra característica dessa estratégia, é a obrigatoriedade de considerar o “deep pagination”, que é explicado em detalhes a seguir:
Deep Pagination
Na consulta de dados paginada, consideramos “Deep Pagination” a tentativa de busca de pedidos na página de número 200 ou superior. Como o retorno de cada página é de 50 pedidos, isso significa que o resultado do intervalo de pesquisa necessariamente precisa ser inferior a 10000 registros, ou 200 páginas.
O objetivo deste limite é manter a performance e escalabilidade da API de Pedidos.
A estratégia recomendada para evitar o “Deep Pagination”, é realizar a busca de pedidos utilizando intervalos de tempo curtos, por exemplo, a cada 30 minutos ou 1 hora ao invés de dias, ou meses.
Dessa forma, a probabilidade de ocorrer o deep-pagination praticamente se extingue.
Exemplo de Consumo
int intervaloBuscaMinutos = 30; // busca de 30 em 30 min para evitar deep-pagination
// busca todos os pedidos de um dia específico
void baixarPedidosWake(DateTime dia) {
var intervaloInicial = dia;
var intervaloFinal = dia.AddMinutes(intervaloBuscaMinutos);
var pagina = 1;
while (day(intervaloFinal) == day(dia))
{
do
{
var response = get("https://api.fbits.net/pedidos?datainicial={intervaloInicial}&dataFinal={intervaloFinal}&direcaoOrdenacao=ASC&pagina={pagina}");
if (response == 200) {
var pedidos = parse(response);
importar(pedidos); // lógica de importação do integrador
} else if (response == 429) {
sleep_segundos(response.headers["retry-after"]);
}
// próxima página dentro do intervalo de 30 min
pagina++;
} while (response.pedidos.count == 50) // menos de 50 registros indica que não existe próxima página para esse consulta.
// próximo intervalo de busca
intervaloInicial.AddMinutes(intervaloBuscaMinutos);
intervaloFinal.AddMinutes(intervaloBuscaMinutos);
pagina = 1;
}
}
Web Hooks
Na estratégia de consumo via Web Hooks, a Wake avisa o sistema integrador que determinado evento aconteceu na loja virtual.
Vantagens
Essa estratégia tem como principal vantagem a velocidade da importação dos pedidos. Em poucos segundos após o consumidor realizar o pedido na loja virtual, a Wake notificará o integrador via chamadas HTTPs e o integrador poderá importar o registro da venda.
Para o consumo de pedidos via web-hooks, os principais tópicos são:
pedido.novo.indexado: enviado quando um novo pedido foi realizado na loja virtual.
pedido.indexado: enviado quando um pedido sofreu alguma alteração.
A Wake tem políticas de performance definidas para os endpoints cadastrados e realiza várias tentativas de envio para cada notificação. Os tempos de conexão e retentativas estão disponíveis no artigo sobre timeout e retentativas.
Desvantagens
Uma desvantagem dessa estratégia é que o integrador precisa fornecer um endpoint público para receber as notificações pela Wake e manter esse sistema rápido, seguro e escalável. Esse endpoint também precisa ter a caraterística de idempotência, explicada na seção abaixo.
Idempotência
Na computação, idempotência é a propriedade que indica que uma operação pode ser realizada várias vezes sem que o resultado seja alterado.
Na integração de pedidos, significa que o integrador pode receber várias vezes a notificação de um mesmo pedido.
Atenção:
É de responsabilidade do integrador processar o mesmo pedido sem prejudicar o resultado da importação (ex.: sem duplicar os pedidos)
Essa característica é necessária porque em um sistema de notificações, existe a possibilidade de falhas de comunicação via rede, o que resultará em retentativas de conexão e possivelmente a mesma conexão ser realizada múltiplas vezes em cenários específicos.
Rate Limit
Uma boa prática de toda API Pública, é definir limites de consumo com objetivo de manter a consistência de performance e escalabilidade da aplicação. Na Wake Commerce, o limite é de 120 requisições por minuto, por token e por grupo de endpoints, confirma mais detalhes no artigo sobre limite de requisições.
Em um cenário de API Pooling, considerando apenas requisições de busca de pedidos, com esse limite de 120 reqs/min é possível baixar:
- 6000 pedidos por minuto
- 360000 pedidos por hora
- 8640000 pedidos por dia
Em um cenário de Web Hooks, considerando apenas requisições de busca de pedidos específicos, com esse limite de 120 reqs/min é possível baixar até:
- 120 pedidos por minuto
- 7200 pedidos por hora
- 172800 pedidos por dia
O tratamento do rate-limit por parte do integrador é requisito essencial para o bom funcionamento da busca de pedidos.
A API da Wake retornará o código 429 - Too Many Requests, quando o integrador atingir o limite de requisições. Nesse momento, é mandatório que o integrador aguarde a quantidade de segundos retornada no _header “retry-after”.
Atenção:
Caso o integrador não respeite o limite e exceda 500 requisições por segundo, o token do integrador será bloqueado por 1 hora, prejudicando a experiência do lojista.
Updated 5 months ago