Documentação

Operações massivas de Pedidos

Boas Práticas para massividade em Pedidos na API Pública

Suggest Edits

Boas Práticas para massividade em Pedidos na API Pública

Esta seção é um guia técnico com as melhores práticas para desenvolvedores que utilizam a API de Pedidos da plataforma, com o objetivo de otimizar a performance, gerenciar os limites de requisições e garantir a estabilidade da sua integração.

Endpoints de Consulta Massiva (Bulk)

Estes endpoints são a maneira recomendada de realizar a baixa de um grande volume de dados. A utilização inadequada pode resultar em sobrecarga do sistema.

EndpointDescrição
GET /pedidosPermite a consulta de uma listagem de pedidos, com diversos filtros como data, situação e forma de pagamento.
GET /pedidos/naoIntegradosRetorna uma lista dos pedidoId de pedidos que ainda não foram marcados como integrados ("complete").

Recomendações:

  • Paginem as Requisições: Para evitar a sobrecarga do servidor, utilize sempre os parâmetros de paginação pagina (padrão: 1) e quantidadeRegistros (máximo: 50).
  • Limite de 10.000 Registros: A API de consulta de pedidos tem um limite de 10.000 registros por requisição. Para não exceder este limite, segmente as consultas em intervalos de tempo menores usando os filtros de data (dataInicial e dataFinal).
  • Contagem Total: Para planejar a paginação de forma programática, use o cabeçalho de resposta x-total-count, que informa a quantidade total de registros que correspondem aos filtros aplicados.

Endpoints de Operação Unitária (Unidade)

Estes endpoints são otimizados para operações em um único recurso. Utilize-os de forma pontual e estratégica, evitando sobrecarregar a API com requisições desnecessárias.

EndpointDescrição
GET /pedidos/{pedidoId}Retorna dados completos de um pedido específico.
PUT /pedidos/{pedidoId}/status'Atualiza a situação de um pedido, com base no pedidoId e no situacaoPedidoId.
POST /pedidosInsere um novo pedido externo na plataforma.
POST /pedidos/{pedidoId}/rastreamentoInsere um rastreamento e status em um pedido.
POST /pedidos/{pedidoId}/observacaohttps://wakecommerce.readme.io/docs/inserindo-uma-observacao-em-um-pedido
POST /pedidos/estorno/{pedidoId}Efetua um estorno total ou parcial de um pedido.

Recomendações:

  • Uso Direto por ID: Utilize estes endpoints quando já tiver o ID do recurso em questão (pedidoId, transacaoId, produtoVarianteId, etc.).
  • Evite Loops de Requisição: Nunca itere sobre uma lista de IDs para buscar detalhes de cada pedido individualmente. Prefira uma consulta massiva com filtros de data e paginação ou utilize o endpoint GET /pedidos/naoIntegrados para obter uma lista de pedidos pendentes.

Estratégias de Sincronização e Fluxo de Trabalho

A combinação inteligente dos endpoints massivos e unitários é a chave para uma integração robusta e eficiente.

Sincronização Inicial de Dados

Para a primeira baixa de dados, ou para reconstruir o estado local após uma falha, siga este fluxo:

  1. Use o endpoint [GET /pedidos](https://wakecommerce.readme.io/docs/consultando-uma-listagem-de-pedidos) com filtros de data (dataInicial, dataFinal) e paginação.
  2. Segmentem as consultas em períodos curtos (por dia ou por hora) para evitar o limite de 10.000 registros por chamada.
  3. Processem a lista retornada de forma assíncrona.
  4. Continuem a paginação até que todas as páginas do período sejam processadas, monitorando o cabeçalho x-total-count.

Sincronização Diária (Batch)

Para a manutenção diária do seu sistema, use o endpoint GET /pedidos/naoIntegrados. Este endpoint retorna uma lista leve de IDs que precisam ser processados.

  1. Consulte o endpoint [GET /pedidos/naoIntegrados](https://wakecommerce.readme.io/docs/consulta-pedidos-nao-integrados) para obter a lista de pedidos pendentes.
  2. Itere sobre esta lista e use os endpoints unitários para buscar detalhes, atualizar o status ou inserir informações de rastreamento.
  3. Após a conclusão do processamento, use [POST /pedidos/complete](https://wakecommerce.readme.io/docs/setando-um-pedido-como-integrado) para marcar o pedido como integrado.

Atualizações em Tempo Real

A melhor abordagem para atualizações em tempo real é através de Webhooks. Isso elimina a necessidade de consultas em massa constantes e reduz o risco de exceder os limites de requisição.

  1. Configure um webhook para o tópico de pedidos.
  2. Ao receber a notificação, o payload conterá o pedidoId do pedido que foi alterado.
  3. Use o pedidoId para chamar o endpoint unitário GET /pedidos/{pedidoId} e buscar os dados atualizados.
  4. Sempre processe as atualizações de forma assíncrona, garantindo que o seu endpoint de webhook responda rapidamente para evitar timeouts.

Estratégias possíveis para consumo de pedidos de uma loja

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

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 about 2 hours ago