Tratamento de dados no ZIM (gravação no X-Adm)

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-11

O X-Adm roda sobre ZIM (Zim Databases), um 4GL/BD com um modelo de dados diferente de um Postgres comum. Este documento existe porque o ponto de maior risco da integração é a gravação final no ZIM feita pelo cliente Java (ps-java, via zimrtmu): se os valores chegarem no formato errado, o cadastro no X-Adm falha ou grava sujo. Aqui está como o ZIM trata os dados e a regra de representação adotada no pipeline.

1. Como o ZIM trata os dados

Tipos (fonte: Zim Databases):

Tipo ZIM	Comportamento
Character	String de comprimento variável; ignora brancos à direita (trailing), mas espaço à esquerda / embutido é significativo; case-sensitive em ordenação/comparação.
NUMERIC	Número armazenado em forma de caractere; pode ter sinal e ponto decimal.
INT / LONGINT / VASTINT	Inteiros de 2 / 4 / 8 bytes. VASTINT guarda até 15 dígitos significativos com casas decimais — é um inteiro escalado. O VastInt 0-3 dec / 0-5 dec do MAXSUL2025_610110 é isso: valor com escala fixa (3 ou 5 casas).

Máscara ≠ valor armazenado — a distinção que costuma confundir:

• O ZIM separa o valor gravado do valor exibido (mascarado). A máscara 9 preenche com zeros à esquerda, Z com espaços, sempre justificando à direita; separadores (/, -, ,) são só exibição, não fazem parte do valor.
• Exemplo: data gravada 20140628 é exibida como 28/06/2014 com a máscara DD/MM/YYYY; um código de 5 dígitos é gravado como 00123 e exibido conforme a máscara.

Consequência prática: aquele " 001" que se vê numa tela é a exibição mascarada, não o que está gravado. Não se deve enviar o valor mascarado ao gravar — envia-se o valor de armazenamento. E esse valor depende do tipo ZIM do campo:

Campo (exemplos)	Tipo ZIM	Valor de armazenamento
NatOp (5.101), CodRetorno (001)	Character	a string literal — trailing blank irrelevante; espaço à esquerda é significativo.
ChaveUnid (" 1 29"), CodMat (" 1 0 134")	Character	chave interna do X-Adm com espaços embutidos significativos — vai byte a byte.
VlTot, Qtde, Valor	VastInt (N dec)	número com escala fixa — o perigo é float (arredondamento binário), não padding.
DtEm, DataInc	Date (8)	AAAAMMDD, sem separadores.

2. Regra de representação no pipeline (decisão)

Decisão: ao longo do pipeline (Postgres → PowerSync → SQLite → cliente Java), os campos viajam como valores tipados/semânticos — não pré-formatados para o ZIM. A formatação para o formato de armazenamento do ZIM acontece no cliente, na fronteira com o zimrtmu (onde a equipe do ERP conhece largura, escala e máscara exatas de cada campo).

• Vantagem: o pipeline carrega dados limpos; a lógica específica do ZIM fica num único ponto (o cliente/ERP), que já tem esse contexto.
• Contrapartida (o risco a mitigar): o cliente precisa aplicar corretamente as regras da §3. Este documento é a especificação dessas regras para a equipe do ERP.

Alternativa considerada e não adotada: guardar tudo já pré-formatado como TEXT verbatim (o transform do maxsul-pied formataria e o cliente só repassaria). Rejeitada nesta fase — concentra a formatação onde há menos conhecimento do alvo ZIM. Pode ser reavaliada se o cliente acumular lógica de formatação demais.

3. Como cada tipo deve ser representado e formatado

Origem (Postgres)	Tipo Postgres	Regra no cliente (→ ZIM)
Código de texto (NatOp, CodRetorno, ClassForma)	TEXT	Repassar literal; preservar espaços à esquerda/embutidos. Se o campo ZIM for Character de largura fixa, ajustar largura conforme o contrato do zimrtmu.
Chave interna do X-Adm (ChaveUnid, CodMat, Chave*)	TEXT	Verbatim, byte a byte — nunca “limpar” espaços.
Valor monetário / quantidade (VlTot, Valor, Qtde, TaxaFrete)	NUMERIC	Usar BigDecimal/NUMERIC fim a fim (nunca double/float). Aplicar a escala fixa do campo (ex.: Valor = 5 casas) na hora de gravar.
Data (DtEm, DataInc)	DATE	Formatar como AAAAMMDD (sem separadores).
Hora (HoraInc)	TEXT	HHMM (Char 4).
Campo não informado	—	Gravar em branco, não em nulo (regra X-Adm — Mapeamento §1).

4. Armadilhas conhecidas (checklist para o cliente/ERP)

• Float em valor/quantidade → arredondamento. Use decimal com escala fixa fim a fim.
• Perder espaço à esquerda/embutido de chave Character (ChaveUnid, CodMat) → chave inválida no X-Adm. Trate como opaco.
• Confundir mascarado com armazenado (enviar " 001" em vez de 001/1 conforme o tipo).
• Nulo em vez de branco em campo Character não informado.
• Escala errada de VastInt (3 vs 5 casas) entre entidades.

5. Pendências (confirmar com a equipe X-Adm)

• Contrato de entrada do zimrtmu: ele recebe o valor de armazenamento ou o mascarado? Qual o formato de ingestão (JSON, string ;-separada)?
• Largura / escala / padding por campo de cada uma das cinco tabelas espelho.
• Código Origem para os writes originados da PIED no Integrador (ver API do Integrador — hoje o KNOWN_ORIGENS não tem um).

---

Fontes (Zim Databases): How To Use Data Types · Number Data Types · Mask.