Documentação Akrus · v1 em prévia
Sincronize registros e reconcilie alterações.
Uma carga inicial não mantém os dados atualizados. Planeje paginação, retomada e releitura dos registros antigos.
Nesta página
Carga inicial
Separe o contexto
Identifique conta, recurso e execução no seu sistema. Não compartilhe dados ou checkpoints entre produtores.
Leia a primeira página
Envie limit entre 1 e 100, sem cursor. Valide o status e o envelope antes de consumir data.
Persista com segurança
Atualize ou insira cada registro pelo id. Salve os campos originais e o horário da observação na sua aplicação.
Confirme o checkpoint
Grave next_cursor somente depois de persistir toda a página. Use uma transação local quando registros e checkpoint precisarem avançar juntos.
Continue até o fim
Envie exatamente o cursor recebido. next_cursor null encerra a varredura, inclusive quando data está vazio.
Retomada após falha
| Falha | O que fazer |
|---|---|
| Antes de persistir a página | Repita a leitura a partir do último checkpoint confirmado. |
| Após persistência parcial | Reprocesse a página com escrita idempotente por id. |
| Cursor inválido | Interrompa a repetição; confira o checkpoint e reinicie a varredura de forma controlada. |
| Cursor repetido ou envelope inesperado | Interrompa a execução e registre o diagnóstico sem credenciais. |
| 401 ou 403 | Suspenda o processo e revise credencial, plano e escopo. |
| 429 ou indisponibilidade temporária | Aplique espera e limite de tentativas sem avançar o checkpoint. |
Reconciliação recorrente
Defina varreduras completas compatíveis com seu volume e sua tolerância a atraso. A API não publica filtros updated_since, período ou status; filtragens locais exigem primeiro ler os registros necessários.
Registre o início, o fim e o resultado de cada execução. Exiba quando os dados foram atualizados pela última vez e diferencie sincronização concluída, incompleta e indisponível. Uma falha não deve zerar um relatório que já contém dados.
Não marque registros como removidos porque uma execução interrompida não os encontrou. A API não declara um snapshot imutável nem um fluxo de exclusões. Divergências de ausência exigem nova conferência antes de ações destrutivas no seu sistema.
Consistência entre recursos
| Regra | Aplicação prática |
|---|---|
| Sem leitura atômica entre coleções | Uma venda e sua concessão podem ser observadas em momentos diferentes. |
| Sem histórico completo de transições | Salve observações locais se necessário, sem tratá-las como todos os eventos ocorridos. |
| Ordem decrescente com desempate por id | Use o cursor do servidor em vez de fabricar um a partir do último horário. |
| Cota compartilhada por credencial | Coordene cargas de produtos, vendas e acessos no mesmo orçamento de chamadas. |
Implemente e valide
Paginação
Use limit e next_cursor para percorrer uma coleção.
Limites de uso
Cota por credencial, Retry-After e tentativas posteriores.
Erros
Códigos HTTP e tratamento de falhas da API v1.
Homologação
Cenários de teste e critérios para iniciar a operação.
Referência conferida em 8 de outubro de 2026. Relatar uma dúvida na documentação.