--- title: Integrações slug: integracoes docTags: createdAt: 2026-08-15T03:41:52.237Z --- :::BlockQuote Consulte o catálogo de contratos que conectam o Agility ao ERP, acompanhe cada tentativa de leitura e reprocesse uma operação quando ela falhar. ::: :::hint{type="info"} **Pré-requisito: ** Você precisa estar dentro de um Workspace e ter acesso à opção Integrações na seção Sistema da barra lateral. ::: *** A tela Integrações é o catálogo de adapters do ERP para o Workspace ativo. Ela mostra quais leituras estão publicadas, o domínio e a versão de cada contrato, o endpoint que pode ser auditado e a procedência do dado. A tela não altera fatos no ERP: são operações de consulta, e qualquer correção deve ser feita no sistema de origem. No ambiente de demonstração, o cabeçalho identifica explicitamente o Adapter de demonstração. Os contratos usam o mesmo contrato HTTP do produto, mas são atendidos por um adapter determinístico; portanto, nenhum dado desta tela deve ser interpretado como uma sincronização viva com o ERP. Quando o modo ERP real estiver ligado, a própria tela passa a informar que as consultas são feitas ao ERP corporativo e cada leitura registra uma execução. *** ### Passo a passo ::::WorkflowBlock :::WorkflowBlockItem **Abrir o catálogo do Workspace** Na barra lateral, expanda o grupo Sistema e clique em Integrações. A página mostra o título Integrações e o subtítulo Integrações configuradas para este workspace. O catálogo é contextualizado pelo Workspace selecionado no topo; se o identificador do Workspace não puder ser resolvido, a página informa que o Workspace não foi encontrado em vez de exibir contratos de outro contexto. ::: :::WorkflowBlockItem **Conferir a procedência da conexão** Leia o cartão superior antes de interpretar qualquer contrato. No ambiente usado neste manual, o cartão diz Adapter de demonstração e explica que os contratos são atendidos por um adapter determinístico, com o mesmo contrato HTTP do produto, mas sem dados vindos do ERP. Em uma instalação ligada ao ERP, o cartão muda para Integração ao vivo com o ERP e informa que as leituras consultam o ERP corporativo e registram uma execução. ::: :::WorkflowBlockItem **Identificar os contratos disponíveis** Cada cartão de contrato apresenta o nome funcional, o selo de disponibilidade e o estado de sincronização. No Workspace Portal de Serviços, o catálogo povoado exibe Projetos (dimensão do ERP), Parceiros (clientes e fornecedores), Centros de custo, Títulos a pagar e a receber, Saldo de orçamento por projeto e Posição de aging e ciclo de caixa. O estado Sem sincronização e a frase Nunca sincronizado significam que ainda não houve uma execução bem-sucedida para aquele contrato; não significam que o contrato está indisponível. ::: :::WorkflowBlockItem **Auditar domínio, versão e endpoint** Abaixo do nome de cada contrato, confira o endpoint publicado, o domínio e a versão. Os contratos de registro usam GET /api/registry/projects e GET /api/registry/partners, no domínio registry, contrato v1. Os contratos financeiros usam GET /api/finance/cost-centers e GET /api/finance/financial-documents, no domínio finance, contrato v1. O saldo por projeto usa GET /api/costing/budget-consumptions/balance-by-dimension, no domínio costing, contrato v1; aging informa GET /api/finance/aging/kpis + /aging/top-debtors, no domínio finance, contrato v1. ::: :::WorkflowBlockItem **Interpretar os selos de estado** O selo Disponível indica que o contrato está publicado para consulta. Ao lado dele, o selo de frescor diferencia o dado atual, simulado, defasado ou desconhecido. No adapter de demonstração, um resultado determinístico correto continua sendo identificado como simulado — não como atual. Quando a última tentativa falha, o cartão mostra a mensagem da falha e, se o dado estiver defasado, avisa que as telas continuam exibindo o último dado conhecido marcado como defasado. ::: :::WorkflowBlockItem **Ver o histórico de tentativas** No contrato desejado, clique em Ver tentativas. A tela abre uma tabela abaixo dos botões com as colunas Quando, Resultado, Itens, Duração e Correlação. Cada linha informa a data e hora de conclusão, OK ou Erro, a quantidade de itens retornados, a duração em milissegundos e o correlation ID. O histórico é somente de acompanhamento e é cumulativo: uma nova execução não apaga a tentativa anterior. ::: :::WorkflowBlockItem **Localizar uma falha para reprocessamento** Se a última execução falhar, leia o texto ao lado do ícone de alerta no cartão e abra Ver tentativas para conferir o erro, a quantidade e o correlation ID. Use essas informações para diferenciar uma falha transitória de uma resposta sem itens. A tentativa que falhou permanece visível depois de qualquer nova tentativa, o que permite comparar o resultado anterior com o reprocessamento. ::: :::WorkflowBlockItem **Passo 8 — Reprocessar uma operação sem parâmetros** Para contratos que não dependem de uma dimensão específica, clique em Reprocessar. O botão fica desabilitado durante o processamento e troca seu texto para Reprocessando…. Ao terminar, o Agility recarrega o contrato e as tentativas; o cartão atualiza o último resultado e a lista ganha uma nova linha. O reprocessamento repete a leitura do contrato, não edita o fato correspondente no ERP. ::: :::WorkflowBlockItem **Tratar o saldo de orçamento por projeto** No cartão Saldo de orçamento por projeto, o botão Reprocessar aparece desabilitado e vem acompanhado da explicação de que a consulta exige informar projeto e data. Não tente contornar essa restrição clicando repetidamente: esta tela não tem os campos necessários para montar esses parâmetros. Abra a superfície que solicita projeto e data para uma consulta parametrizada, ou corrija o dado no ERP de origem conforme a regra do processo. ::: :::WorkflowBlockItem **Verificar o resultado** Depois de uma execução concluída, confirme a nova data em última sincronização bem-sucedida em… e abra Ver tentativas para localizar a linha mais recente. Um resultado OK, sua quantidade de itens, duração e correlation ID são a evidência operacional da leitura. Se a execução continuar em erro, o cartão mantém a mensagem de falha e o estado defasado quando aplicável; isso é uma informação para investigação, não uma confirmação de atualização. ::: :::: ![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/10-integracoes-catalogo.webp "Catálogo de Integrações do Workspace com o adapter de demonstração, contratos ERP disponíveis, endpoints e botões Ver tentativas e Reprocessar") :::hint{type="success"} :FontAwesome[]{icon="fa-solid fa-check"} **Verificação** - O cabeçalho identifica explicitamente se a conexão é um Adapter de demonstração ou uma Integração ao vivo com o ERP. - Cada contrato mostra nome, disponibilidade, frescor, domínio, versão, endpoint e última sincronização (ou Nunca sincronizado). - Ver tentativas revela data/hora, resultado, quantidade de itens, duração e correlation ID sem apagar linhas anteriores. - Após um reprocessamento permitido, uma nova execução aparece no histórico e o cartão atualiza o último resultado; o contrato parametrizado permanece corretamente bloqueado sem projeto e data. ::: :::hint{type="warning"} :FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns** **O catálogo mostra erro de carregamento** Confira se você está dentro de um Workspace válido e recarregue a página. A rota interrompe o carregamento quando não recebe workspaceId ou quando a consulta de contratos falha; ela mostra uma mensagem de erro em vez de apresentar uma lista parcial. **Um contrato aparece como defasado** Leia a mensagem da última tentativa e abra o histórico. Defasado significa que a última leitura não confirmou um dado novo, embora o último dado conhecido possa continuar sendo exibido. Reprocesse apenas contratos sem parâmetros e confirme o novo resultado; para o saldo por projeto, informe projeto e data na consulta apropriada. **O botão Reprocessar está desabilitado** No contrato Saldo de orçamento por projeto isso é intencional: a operação requer projeto e data e a tela de catálogo não os coleta. Em outros contratos, aguarde o processamento terminar; o botão também fica desabilitado enquanto a chamada está em andamento. **A execução foi bem-sucedida, mas o dado continua marcado como simulado** Esse é o comportamento honesto do adapter de demonstração. Simulado descreve a procedência do resultado, não a qualidade da resposta. Somente a configuração de uma integração ERP real muda o modo indicado no cabeçalho. **O histórico não abre** A tabela de tentativas é carregada separadamente do catálogo. Se a consulta falhar, a lista não é exibida e a mensagem Falha ao carregar as tentativas aparece no cartão; registre o erro e tente novamente, sem interpretar a ausência da tabela como ausência de execuções. :::