Manual de integração

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-25

Aplica-se a: equipe X-Adm (ERP/ZIM, suporte técnico e quem opera a nuvem).

Este manual responde a uma pergunta prática: como o dado sai do X-Adm e chega à nuvem, e como o dado de fora entra no X-Adm. Ele é o roteiro de trabalho — o que configurar, em que ordem, e como conferir que funcionou. O porquê do desenho está em Plataforma de Integração; aqui fica o como.

Os três cenários

Toda integração de cliente cai em um (ou mais) destes três cenários. Descubra o seu antes de começar — os passos são diferentes.

	Cenário 1 — tempo real	Cenário 2 — relatórios	Cenário 3 — entrada no X-Adm
Direção	X-Adm → nuvem	X-Adm → nuvem	fora → nuvem → X-Adm
O que viaja	registros do ERP (nota, pedido, BL, estoque…) em JSON, a cada gravação	planilhas XLSX (ou CSV) geradas por relatório	pedidos/eventos de um parceiro, importados no ERP
Quando	na hora em que o usuário grava no X-Adm	por agenda (de hora em hora, madrugada) ou sob demanda	quando o parceiro publica; o ERP importa em ciclos
Recebe na nuvem	int.<cliente>.xadm.biz (integrador)	app de planilha excel.<cliente>.xadm.biz	app do parceiro (ex.: pied.<cliente>.xadm.biz) → integrador
Credencial do lado do cliente	token INTEGRADOR_API_TOKEN	token do app de planilha (ou chave SSH, no modo antigo)	token + par de chaves do integrador-client
Clientes hoje	Sulplata, OnPetro Trading	Thoms (hora em hora), OnPetro (4h e sob demanda), Vantroba (sob demanda)	Maxsul (PIED); MDF-e/Sascar em Vantroba e Pontual
Roteiro	Cenário 1	Cenário 2	Cenário 3

Os três compartilham a mesma base na nuvem — o banco do cliente e a instância de sincronização (PowerSync). Cliente que ainda não tem essa base passa antes pelo Cliente novo na nuvem.

flowchart TB
    subgraph cliente["Servidor do cliente"]
        erp["ERP X-Adm"]
        ag["Agente de envio<br/>(Java, equipe X-Adm)"]
        ic["integrador-client<br/>(Java, entrada)"]
    end
    subgraph nuvem["Nuvem X-Adm"]
        int["int.&lt;cliente&gt;<br/>integrador"]
        xls["excel.&lt;cliente&gt;<br/>app de planilha"]
        par["pied.&lt;cliente&gt;<br/>app do parceiro"]
        pg[("banco do cliente")]
        ps["ps.&lt;cliente&gt;<br/>PowerSync"]
    end
    usr["Apps Web e Mobile"]
    parceiro["Parceiro (PIED)"]

    erp -- "1. JSON a cada gravação" --> ag
    ag -- "PUT /api/v1/xadm" --> int
    erp -- "2. relatório .xlsx (zip)" --> xls
    parceiro -- "3. webhook / consulta" --> par
    par -- "REST" --> int
    int --> pg
    xls --> pg
    pg --> ps
    ps --> usr
    ps -- "3. pendentes" --> ic
    ic -- "importa (pAbast)" --> erp

Quem é dono de cada parte

A integração atravessa duas equipes. Saber quem responde por cada trecho evita procurar o problema no lugar errado.

Trecho	Dono	Onde está documentado
Gerar o .json a cada gravação e o agente Java que o envia	Equipe X-Adm (ERP/ZIM)	Cenário 1 §Lado do X-Adm
Gerar os relatórios e disparar o envio (tarefa agendada, rotina do ERP)	Equipe X-Adm (ERP/ZIM)	Cenário 2 §Lado do X-Adm
Rotina pAbast do ZIM que importa no ERP	Equipe X-Adm (ERP/ZIM)	Cenário 3 §Importação no ERP
Integrador, apps na nuvem, banco, PowerSync	Nuvem (Gustavo)	as páginas deste manual e o repo de cada app
integrador-client (programa Java que roda no cliente)	Nuvem (Gustavo); instalação junto com a equipe X-Adm	Cenário 3 §Instalação

Regras que valem para todos os cenários

• Um banco por cliente. Nenhum dado de um cliente passa pelo banco de outro.
• Todo endereço é <servico>.<cliente>.xadm.biz. O DNS tem um curinga (*.xadm.biz): não é preciso criar registro para endereço novo.
• HTTPS é automático. O certificado do site é emitido pela própria nuvem (Let's Encrypt). Nenhum certificado é instalado na máquina do cliente — a credencial do cliente é um token (e, no cenário 3, um par de chaves).
• Token vai por canal seguro, nunca por e-mail aberto ou chat. Cada cliente tem os seus tokens; eles nunca se repetem entre clientes.
• "200" não quer dizer "deu certo" no integrador. O int.<cliente> responde sempre 200 e diz o resultado no corpo (SUCESSO, ERRO, PENDENTE). Quem envia tem de ler o corpo.
• Reenviar é seguro. Todos os pontos de entrada identificam o registro pela chave de negócio do X-Adm (ou pelo conteúdo do arquivo) — mandar de novo atualiza, não duplica.

Links deste manual

Os links para docs.xadm.biz/aplicacoes/…/dev/ levam à documentação mais recente de cada app. Os links para o Forgejo (fonte.xadm.biz) pedem login.

Glossário rápido

Termo	Significa
Integrador (int.<cliente>.xadm.biz)	O serviço na nuvem que guarda a cópia fiel do X-Adm no banco do cliente. Uma instância por cliente.
Espelho	As tabelas do banco na nuvem com o mesmo nome e as mesmas chaves das tabelas do X-Adm (contratos, estoque, itensped…).
PowerSync (ps.<cliente>.xadm.biz)	O serviço que entrega o conteúdo do banco para os apps (celular, web) e para o integrador-client, e recebe as alterações de volta.
Sync rules	A lista de tabelas (e filtros) que o PowerSync entrega. Fica no repo <cliente>-powersync.
App de planilha (excel.<cliente>.xadm.biz)	O serviço que recebe os relatórios em XLSX, lê e grava as tabelas de BI.
integrador-client	Programa Java que roda no servidor do cliente e importa no ERP o que veio de fora (cenário 3).
Coolify	O painel onde cada serviço da nuvem é criado e configurado (admin.xadm.biz).
Central (central.xadm.biz)	O painel da X-Adm: cadastro de clientes, deploys, saúde das instalações.