Carga Incremental por Data de Atualização — Documentação Complementar

1. Introdução

Esta página é uma documentação complementar da API do ERP Spalla. Ela se dirige ao integrador (ou ao agente de IA) que lê dados do ERP para outro sistema — um painel de BI, um data warehouse, um e-commerce, um CRM — e precisa mantê-lo atualizado sem sobrecarregar a API.

Muitas tabelas do ERP guardam, em cada registro, a data e a hora da última atualização. O servidor preenche esse valor sozinho a cada inclusão e a cada alteração. Com ele, a integração resolve dois problemas de uma vez:

Esta página descreve a estratégia e a ordem das chamadas. Ela não substitui o dicionário oficial da sua instância, que é a fonte autoritativa dos nomes de tabela, de coluna e da chave primária.

2. Onde encontrar o dicionário oficial da sua API

Cada empresa que opera o ERP Spalla expõe o seu próprio dicionário automático em um endereço próprio. Para acessá-lo, abra no navegador a URL no formato abaixo, substituindo os placeholders pelos valores da sua instância:

https://<host>:<porta>/root/dicionario?userToken=<token>

• <host> — endereço do servidor que hospeda a API.
• <porta> — porta de comunicação configurada no servidor.
• <token> — token de identificação (userToken) fornecido pela equipe responsável pela API.

Para esta página, o dicionário responde três perguntas sobre cada tabela: qual é a coluna de data de atualização, quais colunas formam a chave primária e quais colunas o seu sistema realmente precisa.

3. Como a API funciona

Todas as leituras desta página passam pelo mesmo endpoint da API, com a arquitetura unificada: o verbo HTTP não determina a operação; o campo "method" do corpo JSON determina.

Os parâmetros da consulta que fazem a carga incremental:

Três termos aparecem em toda a página:

• Pacote — a resposta de uma consulta com limit. Pacote cheio é o que voltou com exatamente limit registros; pacote incompleto, o que voltou com menos.
• Marca — a data e hora a partir da qual o próximo pacote é pedido. O seu sistema guarda uma marca por tabela.
• Ciclo — uma execução da sincronização: pede pacotes a partir da marca até receber um pacote incompleto.

A montagem da requisição — URL base, porta e o header userToken — e as regras de formatação de valores estão na documentação geral da API, em especial Datas, Horas e Data/Hora. Esta página mostra apenas o corpo JSON de cada consulta; os comentários // dos exemplos são explicativos e saem da requisição real.

4. Por que ler em pacotes

Uma consulta aberta sobre uma tabela de movimento obriga o servidor a montar toda a resposta de uma vez, antes de enviar o primeiro registro. A tabela de itens de notas fiscais e de movimentos de estoque, MOVEQ2, tem mais de 200 colunas: algumas dezenas de milhares de linhas completas numa resposta só podem passar de uma centena de megabytes. O tempo de resposta cresce com o volume, e uma falha no meio obriga a recomeçar do zero. O mesmo vale para um filtro de período longo: um ano de notas numa resposta só pesa como a tabela inteira.

A diferença de volume é grande na prática. Numa base real de itens de nota, menos de 5% dos registros foram incluídos ou alterados em 30 dias, e menos de 0,5% nas últimas 24 horas. Nesse ritmo, numa tabela de 1 milhão de itens, reler tudo a cada 15 minutos traria 96 milhões de registros por dia; a carga incremental traria alguns milhares. Entre os itens alterados no mês havia itens de movimentos lançados meses antes: registros antigos que voltaram à fila e que uma leitura pela data de lançamento não traria de volta.

5. Como a data de atualização funciona

O comportamento é o mesmo em todas as tabelas que têm o controle:

• O servidor preenche o valor sozinho, na inclusão e em cada alteração do registro, com data, hora e fração de segundo. A integração não precisa gravar essa coluna: um valor enviado num POST ou PUT é substituído pelo do servidor.
• A alteração de uma única coluna já basta. As inclusões e alterações feitas pela tela do ERP ou pela API atualizam a data do registro.
• Em regra, a data é do registro daquela tabela. Alterar um item não muda a data do cabeçalho, e alterar o cabeçalho não muda a data dos itens. Nos movimentos, o controle fica nos itens (MOVEQ2); o cabeçalho (MOVEQ1) não tem coluna equivalente e se acompanha pela data do movimento (Passo 4). No cadastro de pessoas é o contrário, e a favor de quem integra: alterar um contato ou um endereço da pessoa também atualiza a CF_DTATU da CLIFOR1.
• Exclusões não aparecem na fila. Um registro excluído deixa de existir, e não há data a consultar. O cancelamento de uma nota fiscal, por exemplo, remove os itens dela da MOVEQ2. Quem reflete as exclusões no seu sistema é a releitura dos cabeçalhos recentes (Passo 4) e a reconciliação (Passo 6).

6. Tabelas com o controle

As tabelas abaixo são as mais procuradas em integrações de leitura e têm a coluna de atualização preparada para consulta por faixa de data, que é exatamente a consulta desta página:

O mesmo controle existe em muitas outras tabelas do ERP. Para usar a estratégia numa tabela fora desta lista, confirme a coluna no dicionário e alinhe com o gestor do ERP Spalla o volume e o horário das cargas.

7. Diagrama das três rotinas

A integração é organizada em três rotinas com frequências diferentes: a carga inicial (Passo 2) roda uma vez; a sincronização incremental (Passos 3 a 5) roda a cada poucos minutos; a reconciliação (Passo 6) roda com pouca frequência, fora do horário de pico.

Convenção visual: azul (Retaguarda do ERP) · verde (Via API) · cinza (no seu sistema).

8. Aviso sobre liberação na retaguarda

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ2"
    // Só a coluna de atualização
    ,"fields": ["ME_DTATU"]
    // A maior data primeiro
    ,"orderBy": ["ME_DTATU DESC"]
    ,"limit": 1
}

{
    "ME_DTATU": "2026-09-30T08:14:57.321"
}

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ2"
    // Só as colunas que o seu sistema usa, com a chave e a data de atualização
    ,"fields": ["FL_COD", "CF_TIPO", "FT_COD", "ME_COD", "ME_ITM", "PD_COD", "ME_QTD", "ME_PRC", "ME_VALOR", "ME_DTATU"]
    // Ordem estável: a chave primária completa
    ,"orderBy": ["FL_COD ASC", "CF_TIPO ASC", "FT_COD ASC", "ME_COD ASC", "ME_ITM ASC", "PD_COD ASC"]
    // Tamanho do pacote
    ,"limit": 500
    // Número da página: 1, 2, 3...
    ,"offset": 1
}

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ2"
    ,"fields": ["FL_COD", "CF_TIPO", "FT_COD", "ME_COD", "ME_ITM", "PD_COD", "ME_QTD", "ME_PRC", "ME_VALOR", "ME_DTATU"]
    ,"where": [
        {
            // Início do ciclo: a marca menos a margem, com espaço entre a data e a hora
            "type": "expression"
            ,"value": "ME_DTATU >= '2026-09-30 08:09:57'"
        }
    ]
    // Só pela data de atualização
    ,"orderBy": ["ME_DTATU ASC"]
    // Tamanho do pacote; sem offset
    ,"limit": 500
}

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ2"
    ,"fields": ["FL_COD", "CF_TIPO", "FT_COD", "ME_COD", "ME_ITM", "PD_COD", "ME_QTD", "ME_PRC", "ME_VALOR", "ME_DTATU"]
    ,"where": [
        {
            // Só o segundo do empate
            "type": "expression"
            ,"value": "ME_DTATU >= '2026-09-30 08:14:57' AND ME_DTATU < '2026-09-30 08:14:58'"
        }
    ]
    ,"orderBy": ["FL_COD ASC", "CF_TIPO ASC", "FT_COD ASC", "ME_COD ASC", "ME_ITM ASC", "PD_COD ASC"]
    ,"limit": 500
    // Aqui, sim, página a página: 1, 2, 3...
    ,"offset": 1
}

marca  = ler_marca("MOVEQ2")               // guardada no seu sistema, uma por tabela
inicio = marca - 5 minutos                 // margem (Passo 5)
repetir:
    linhas = GET where ME_DTATU >= inicio, orderBy ME_DTATU, limit N
    linhas = normalizar(linhas)            // objeto: lista de um item; 404 rowCount:0: lista vazia
    se linhas vazia: parar
    gravar_pela_chave(linhas)              // Passo 4
    maior  = truncar_segundo(max(ME_DTATU das linhas))
    guardar_marca("MOVEQ2", max(marca, maior))
    se quantidade(linhas) < N: parar      // pacote incompleto: ciclo encerrado
    se maior == inicio:                    // empate
        ler o segundo 'inicio' por páginas, na ordem da chave
        inicio = inicio + 1 segundo
    senão:
        inicio = maior

falha temporária (tempo esgotado, 5xx): repetir a mesma requisição, com espera crescente
400 ou 401: parar e registrar — não é temporário

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ1"
    // A chave, a indicação de cancelamento e as colunas que o seu sistema usa
    ,"fields": ["FL_COD", "CF_TIPO", "FT_COD", "ME_COD", "ME_ENT", "ME_CANCEL"]
    ,"where": [
        {
            // Movimentos dos últimos 7 dias
            "type": "expression"
            ,"value": "ME_ENT >= '2026-09-23 00:00:00'"
        }
    ]
    ,"orderBy": ["FL_COD ASC", "CF_TIPO ASC", "FT_COD ASC", "ME_COD ASC"]
    ,"limit": 500
    ,"offset": 1
}

{
    "method": "GET"
    ,"objectType": "TABLE"
    ,"objectName": "MOVEQ2"
    // Só a chave primária
    ,"fields": ["FL_COD", "CF_TIPO", "FT_COD", "ME_COD", "ME_ITM", "PD_COD"]
    ,"orderBy": ["FL_COD ASC", "CF_TIPO ASC", "FT_COD ASC", "ME_COD ASC", "ME_ITM ASC", "PD_COD ASC"]
    ,"limit": 5000
    ,"offset": 1
}

Boas práticas

• Declare sempre o limit. É ele que define o tamanho da resposta. Comece com 500 registros por pacote numa tabela larga como a MOVEQ2 e ajuste pelo tempo de resposta: pacotes que voltam em poucos segundos são o ponto certo. Com poucas colunas em fields, o pacote pode ser maior.
• Peça só as colunas que usa. Nas tabelas de movimento, fields é o que mais reduz o volume trafegado.
• Ordene sempre que paginar. Sem orderBy, a ordem dos registros não é garantida, e páginas seguidas podem repetir ou deixar registros de fora. offset vai sempre junto com limit.
• Normalize a resposta. Um registro chega como objeto, e nenhum registro chega como 404 com rowCount:0 (seção 3).
• Uma requisição por vez para cada tabela. Disparar vários pacotes em paralelo contra a mesma tabela troca uma consulta grande por várias ao mesmo tempo — a carga no servidor é a mesma.
• Respeite o formato de data de cada lugar. No where, a data vai com espaço ('2026-09-30 08:14:57'); a API devolve com T ("2026-09-30T08:14:57.321"). Converta antes de reutilizar o valor como marca.
• Compare com >=, nunca com =. A data de atualização guarda fração de segundo, e uma comparação por igualdade sem a fração não encontra nada. Como limite superior, use < o segundo seguinte, e não <=.
• Deixe as cargas pesadas para fora do pico. A carga inicial e a reconciliação são as rotinas que mais consomem; a sincronização incremental, com pacotes pequenos, pode rodar durante o expediente.

Resultados inesperados e erros

Spalla API Toolkit — deixe a sua IA montar a integração do jeito certo

Se você usa um agente de inteligência artificial para escrever ou operar a integração, o Spalla API Toolkit ensina a ele esta estratégia e as regras da API de que ela depende. Com o toolkit instalado, o agente:

• propõe a carga incremental por conta própria quando a tarefa é extrair volume, sincronizar ou alimentar um painel, em vez de escrever a consulta aberta;
• encontra no dicionário da sua instância a coluna de data de atualização e a chave primária de cada tabela, e confere a coluna antes de usá-la;
• escreve o código de sincronização com as três rotinas desta página: marca inicial, pacotes que avançam pela data, gravação pela chave, tratamento do empate, releitura dos cabeçalhos e reconciliação nos dois sentidos;
• aplica sozinho os formatos de data do filtro e do retorno, o significado correto do offset e a normalização da resposta;
• limita as próprias consultas de exploração, e avisa quando uma leitura ampla de tabela pede a estratégia de pacotes.

Dica — identificar a tabela e o campo a partir da interface do ERP

Relação com os demais guias

• Cadastro de Pessoas — sincronização de clientes e fornecedores pela CF_DTATU. Ver Cadastro de Pessoas.
• Cadastro de Produto — sincronização de produtos pela PD_DATA e dos códigos de barras pela PD_DTMOD. Ver Cadastro de Produto.
• Análise de Vendas — quando o objetivo é um painel de vendas e faturamento, as consultas da Análise de Vendas entregam o dado já consolidado, sem a necessidade de trazer os itens das notas para o seu lado. Ver Análise de Vendas.

Onde aprofundar

Os nomes de tabela, de coluna e da chave primária de cada objeto estão no dicionário oficial da sua instância (seção 2), que é a fonte autoritativa. A montagem da requisição — URL base, porta, autenticação, os parâmetros do GET e o formato dos valores — está na documentação geral da API.