Integração com sistemas externos

integração com sistemas externos (emitir e controlar a chave) pré requisitos 13 — administração esta seção é do perfil administrador do tenant se você é quem vai escrever a integração , esta não é a sua página o contrato, os exemplos de código e o catálogo de operações estão na documentação para desenvolvedores , uma coleção própria no portal introdução quando um sistema externo precisa conversar com o erp — um portal de transparência que puxa empenhos, um aplicativo de campo que devolve medições, o sistema de protocolo que consulta fornecedor — alguém do órgão precisa dizer quem ele é e o que pode fazer é o que esta tela faz a ideia central quem entra de fora entra com uma chave, e a chave já diz o que pode não existe "usuário de integração" com cargo fictício no organograma — o programa não tem cargo, e inventar um servidor fantasma só para pendurar permissão é algo que ninguém consegue auditar depois passo a passo abra "chaves de integração" menu administração → chaves de integração a tela inicial é a grade das chaves já emitidas (nome, prefixo, permissões, situação, último uso), com as ações editar e revogar por linha, o botão "nova chave" e um link para abrir o contrato da api o item só aparece para quem tem a permissão de gerenciar chaves de integração ; sem ela, a lista não carrega — mostra um aviso de acesso negado, com botão de tentar de novo, e não uma tela vazia emita a chave clique em "nova chave" para abrir a tela de emissão informe uma descrição que diga qual integração é — "portal da transparência", "app de medição de obra" — e não apenas "integração" você vai revogar pelo nome daqui a um ano diga o que a chave pode fazer há dois caminhos, e o campo "grupos de acesso" aparece primeiro porque é o recomendado\ as duas regras do escopo logo abaixo valem para os dois caminhos associe um ou mais grupos de acesso (recomendado) um grupo é um conjunto de permissões com nome de negócio — "emissão fiscal", "consulta de cadastros" — em vez de uma lista de códigos técnicos marque um ou mais grupos e a chave passa a poder tudo o que a união deles concede ao marcar um grupo, o campo de operações some as permissões vêm do grupo é a seção grupos de acesso , logo abaixo, que explica como criá los e por que compensam você não precisa decorar nomes de operação ou liste as operações uma a uma (avulso) deixe os grupos sem marcar e o campo "escopo" reaparece, autocompletando com o catálogo de operações comece a digitar e escolha da lista, separando várias por vírgula (ex read registry, read inventory) serve para uma chave pontual que não vale a pena virar grupo copie o segredo ele aparece uma única vez não há recuperação se perder, emita outra e revogue esta entregue a chave ao parceiro o contrato — a lista de operações que o desenvolvedor dele vai programar — é alcançado com a própria chave , e não por um endereço público que você repassa para conferir você mesmo o que ele vai encontrar, abra o "contrato da api" pelo link na tela de chaves é uma troca (você cola a chave uma vez), não um endereço para repassar é o assunto da seção abrir o contrato da api , adiante revogue quando a integração terminar vale na chamada seguinte, inclusive para o acesso à documentação não há período de graça as duas regras do escopo que surpreendem o escopo é uma lista fechada uma operação fora dele é recusada — mesmo que o órgão ainda não tenha definido nenhuma regra de alçada para ela para pessoas, o erp assume que "ainda não configurei" significa liberado, porque o órgão organiza suas alçadas aos poucos para um programa que fala de fora, silêncio significa não uma chave emitida sem nenhuma operação no escopo não faz absolutamente nada — e isso é proposital se valesse a regra das pessoas, ela herdaria tudo que ainda não foi governado em particular, role integration (ou qualquer token que comece com role ) não é uma operação — é papel, não permissão uma chave com só isso no escopo é exatamente o caso "não nomeia operação nenhuma" ela valida, aparece ativa na lista e devolve 403 em tudo por isso o sistema agora recusa a emissão de um escopo que não nomeie ao menos uma operação, em vez de deixar você descobrir pelo chamado do parceiro chave nunca aprova valor operações sujeitas a limite de alçada são recusadas para integração, sempre aprovar valor dentro de alçada é ato de agente público, preso a um cargo, e um programa não tem cargo se o parceiro disser que "precisa aprovar", o desenho está errado a integração registra , e uma pessoa aprova grupos de acesso — permissão em linguagem de negócio escolher operação por operação funciona, mas cansa e erra são dezenas de códigos (read registry, transmit fiscal, settle document…), e cada chave nova obriga a montar a lista de novo um grupo de acesso resolve isso — é um conjunto de operações com nome de negócio , criado uma vez e associado a quantas chaves precisar em vez de "esta chave tem manage financial document e settle document", você diz "esta chave tem faturamento " é o mesmo padrão que a nuvem usa (papel no google, política gerenciada na aws, conjunto de permissões no salesforce) a permissão vira reutilizável e ganha um nome que o gestor entende quem administra os grupos usa menu administração → grupos de acesso (/admin/access groups) o item só aparece para quem tem a permissão de gerenciar grupos de acesso o que já vem pronto o sistema já traz cinco presets (grupos prontos), que cobrem os casos mais comuns preset o que concede integration read only (all modules) leitura de todos os módulos (o "só consulta") registry read leitura de cadastros (parceiros, produtos, tabelas de preço) inventory read leitura de estoque fiscal issuance emitir e gerir documentos fiscais billing gerir e baixar documentos financeiros preset é ponto de partida — pode ser renomeado e ter as permissões ajustadas, mas não pode ser excluído (só desativado) os nomes chegam em inglês por serem semente do sistema; renomeie para o vocabulário do seu órgão à vontade criar um grupo próprio "novo grupo" dê um nome que o gestor entenda ("portal da transparência", "emissão fiscal") e uma descrição do que ele serve escolha as permissões ("permissões"), agrupadas por módulo — são as mesmas operações do escopo avulso, só que reunidas sob o nome um grupo sem nenhuma permissão não concede nada (a tela nem deixa salvar) salve o grupo passa a aparecer no seletor de grupos da emissão de chave o nome é único e não diferencia maiúscula de minúscula não há dois grupos "faturamento" a regra que surpreende editar um grupo mexe em todas as chaves que o usam um grupo é um único ponto de mudança quando você acrescenta uma permissão a um grupo, toda chave associada a ele passa a ter essa permissão na chamada seguinte — sem reemitir nada é a vantagem (ajusta um lugar, propaga para todas) e é a armadilha (ampliar um grupo compartilhado amplia todas as chaves de uma vez) daí a disciplina de grupos enxutos se só uma integração precisa de uma permissão a mais, dê a ela um grupo próprio, em vez de inchar um grupo que muitas chaves usam desativar um grupo remove as permissões dele das chaves que o referenciam — mesmo cuidado histórico do grupo mudança em grupo é mudança de permissão, então fica registrada na linha do grupo, "histórico" abre a trilha de auditoria quem criou, quem alterou o quê e quando, com o diff campo a campo em cada alteração — o mesmo padrão de histórico das demais telas de cadastro do erp chaves antigas (migradas) chaves que já existiam antes dos grupos continuam valendo com o escopo avulso que tinham para não perder rastreabilidade, cada uma dessas listas de escopo virou automaticamente um grupo próprio (com nome começando por "migrated"), que você pode renomear, reaproveitar em outras chaves, ou ignorar nada quebrou a chave continua exatamente com as permissões de antes editar as permissões de uma chave antes, mudar o que uma chave podia fazer exigia revogá la e emitir outra — e reconfigurar a integração do outro lado por uma mudança pequena agora não na grade, a ação editar de cada chave abre a tela de edição, onde você troca o nome e as permissões (marcando outros grupos de acesso, ou operações avulsas) e salva o segredo não muda — a chave que o parceiro já usa continua valendo; muda só o que ela pode fazer, valendo na chamada seguinte é o mesmo princípio dos provedores de nuvem a credencial autentica, as permissões são um ajuste à parte três detalhes que evitam susto chave revogada é só leitura você a abre para consultar o que ela concedia e o histórico, mas não há botão de salvar — revogar é definitivo editar um grupo muda todas as chaves que o usam se a chave é autorizada por um grupo compartilhado, alterar aquele grupo (na tela grupos de acesso ) repercute em todas as chaves associadas para mexer só nesta chave, dê a ela um grupo próprio ou use operações avulsas toda alteração fica no histórico a própria tela de edição mostra o histórico de alterações da chave quem mudou o quê e quando, com o diff campo a campo o segredo nunca aparece ali — a trilha guarda nome, prefixo e permissões, jamais a chave abrir o contrato da api (destravar no navegador) o contrato não fica aberto na internet ele responde a chave cadastrada , e só aí aparece um detalhe que confunde todo mundo na primeira vez — um navegador não envia cabeçalho quando você navega um programa carimba a chave em cada chamada; uma aba do navegador só pede a página, sem nada junto por isso um link direto para o console devolve "não autorizado" mesmo com a chave certa em mãos não existe onde colocá la o cartão "contrato da api" resolve isso com uma troca você cola a chave uma vez e o erp devolve, para aquele navegador, uma autorização curta que apenas nomeia a chave — nunca carrega a chave é essa autorização que abre o console nas navegações seguintes como fazer o cartão "contrato da api" é o primeiro da tela administração → chaves de integração se ele avisar "nenhuma chave ativa ainda" , não há o que destravar emita a primeira chave no painel de baixo e volte aqui escolha a "área de negócio" o contrato é publicado em uma seção por área — cadastros, compras, estoque, vendas e faturamento, financeiro, contabilidade, patrimônio e imóveis, custos e orçamento, frota, jurídico, folha de pagamento, gestão por indicadores, plataforma e gateway a escolha diz em que seção o console vai abrir ; ela não muda o que a chave pode fazer, que continua sendo só o escopo dela cole a chave em "chave de integração" o campo é do tipo senha — o que você colar não fica legível na tela é o segredo que apareceu uma única vez na emissão o prefixo listado na tabela de baixo não serve — ele é apenas o identificador visível da chave, e é o engano mais comum de quem tenta pela primeira vez se você acabou de emitir, o botão "usar esta chave para abrir o contrato" , no painel do segredo, preenche o campo sem passar pela área de transferência clique em "destravar o contrato" dando certo , aparece uma faixa verde com o nome da chave que abriu e em quanto tempo o console fecha de novo (uma hora, na configuração padrão), mais dois caminhos\ o seletor de área continua ativo depois de destravar troque a área e os dois caminhos passam a apontar para ela, sem colar a chave outra vez "abrir o console" — a página interativa, já posicionada na área escolhida; "abrir o documento (json)" — o mesmo contrato em arquivo, que é o que o desenvolvedor do parceiro joga no gerador de código dele o que fica valendo depois a abertura vale só naquele navegador e expira sozinha não é endereço para repassar por e mail quem receber o link sem ter destravado bate no mesmo "não autorizado" revogar a chave fecha o console na requisição seguinte cada navegação reconfere se a chave ainda está ativa — não há período de tolerância até o prazo vencer "usar outra chave" apenas devolve o formulário para destravar com outra chave; ele não fecha o que já está aberto o que fecha é o prazo ou a revogação se o desenvolvedor do parceiro não tem acesso ao portal, ele não usa esta tela — e não precisa o programa dele lê o mesmo contrato enviando a chave no cabeçalho x erp appkey, como faz em qualquer outra chamada esta tela existe para o navegador, que é justamente quem não consegue mandar o cabeçalho quando o destravamento é recusado a tela distingue os motivos porque a saída de cada um é diferente o que a faixa vermelha diz o que aconteceu o que fazer "esta chave não foi reconhecida" chave errada, incompleta ou já revogada espaço colado antes ou depois não é causa a tela remove confira que você colou o segredo da emissão, e não o prefixo da tabela; se o segredo se perdeu, emita outra chave e revogue esta "tentativas demais a partir deste endereço" proteção contra chute de chave cerca de dez tentativas por minuto vindas do mesmo endereço espere um minuto e tente de novo — não adianta reemitir a chave "abrir o contrato pelo navegador está desligado neste ambiente" esta instalação não tem configurado o segredo que assina a autorização é ajuste de quem administra a instalação, não da tela; enquanto isso só o caminho pelo cabeçalho funciona "não foi possível falar com o servidor" a requisição não chegou a sair rede, vpn ou servidor fora do ar se o destravamento der certo mas "abrir o console" cair em página não encontrada , o problema é outro o console não está publicado no mesmo endereço do portal nesta instalação também é assunto de quem administra o ambiente — reemitir chave não resolve se ninguém destravar não quebra nada dentro do erp quebra do outro lado, mais tarde sem o contrato aberto, o desenvolvedor do parceiro programa por descrição verbal ou por um documento antigo que alguém mandou por e mail, e a integração chega em produção errando nome de campo e operação que nem existe mais são os chamados de "está dando 400 e não sei por quê" que ninguém consegue responder sem o documento à mão — e o documento está aqui, a uma colagem de chave o portal do cidadão pedindo orçamento (requisito 22 4) esta é a primeira integração que o próprio cidadão dispara, ainda que ele nunca fale com o erp vale ler o desenho antes de habilitar, porque ele responde de antemão a maior parte das perguntas que aparecem depois quem é quem o interessado entra no portal do município , já identificado por lá (o gov br, tipicamente), e pede um orçamento quem conversa com o erp é o portal , não ele — com uma chave de aplicação, como qualquer outro sistema desta seção o erp não autentica o cidadão e não guarda senha dele do lado de cá, a solicitação chega como se um sistema parceiro a tivesse enviado, porque foi exatamente isso que aconteceu não existe, e não vai existir, uma tela do erp para o cidadão a operação submit quote request é de máquina nenhum cargo humano pode recebê la, nem por regra de autorização — o sistema recusa a tentativa se alguém pedir "o print da tela do portal do cliente", a resposta honesta é que a tela é do município; o que o erp mostra é o resultado dela, em vendas → solicitações de cotação , com o selo portal do cliente na coluna origem (veja 08 — vendas , passos 5 e 6) como habilitar crie um grupo de acesso com a operação receber pedido de orçamento pelo portal do cliente — é o nome dela na lista um grupo dedicado, e não um grupo existente com mais uma operação quando alguém perguntar "quem pode abrir solicitação em nome de cidadão?", a resposta tem que ser um nome, não uma varredura emita a chave para o portal do município ligada a esse grupo o segredo aparece uma única vez , na criação — o mesmo cuidado de sempre entregue a chave a quem mantém o portal do município ele precisa também do identificador do órgão (o tenant ), que acompanha a chave o contrato das duas operações está publicado na área vendas e faturamento da documentação da api, e vem pronto no sdk tipado — é o que evita o desenvolvedor do outro lado programar por descrição verbal e descobrir nome de campo errado em produção cada solicitação diz por qual chave entrou toda entrada por este canal fica registrada no histórico de alterações da própria solicitação, com a chave identificada pelo prefixo (appkey …) e a data é o que torna a chave dedicada mais que burocracia a pergunta "quem abriu esta solicitação em nome do cidadão?" passa a ter resposta por solicitação , não só por permissão uma ressalva para não mandar ninguém a um beco abrir esse histórico exige perfil de auditoria quem cuida da carteira comercial vê a solicitação, mas não o registro de origem — se ele clicar e receber uma negativa de permissão, o manual não está errado e a tela não está quebrada; falta o perfil peça a leitura a quem audita ⚠️ o cidadão precisa já ser cliente cadastrado este canal não cadastra ninguém se o requerente não existir no cadastro com o papel de cliente, a solicitação é recusada foi decisão do patrocinador, e é o que impede que um canal aberto vire porta de entrada de cadastro sem conferência o que o cidadão vê depois ele recebe um código de acompanhamento — uma sequência longa, sem significado, que não revela nada sobre o órgão nem sobre o pedido com ele, e apenas por meio do portal do município, consulta em que situação a solicitação está e as datas nunca valores nem o total, nem o preço de item nenhum a proposta continua indo pelo caminho de sempre, quando o vendedor enviar o orçamento isso é deliberado o código sozinho não pode virar uma janela para o preço que o órgão praticou — e como ele viaja por fora, é preciso assumir que pode vazar o que muda no dia a dia de quem vende nada no procedimento, e uma coisa no julgamento a solicitação que chega por este canal não passou por ninguém do setor ninguém conferiu se o pedido faz sentido, se o cliente é quem diz ser para aquele item, se o texto está completo vale ler com o mesmo cuidado que se teria ao telefone com um desconhecido o selo na coluna origem existe para isso quando alguém disser que não funciona o que relatam o que provavelmente é "o portal manda e dá 403" a chave não tem a operação no escopo não reemita — abra a chave em editar e marque o grupo que carrega receber pedido de orçamento pelo portal do cliente o segredo não muda e vale já na chamada seguinte; reemitir derrubaria o canal do cidadão até o município reconfigurar o segredo do outro lado "dá 403 e a operação está no grupo" o grupo pode estar inativo ; a chave só herda de grupo ativo "dá 400 dizendo que o cliente não existe" o requerente não está no cadastro, ou está sem o papel de cliente "dá 400 e não fala de cliente" o pedido só carrega cliente , validade (opcional) e uma observação de até 400 caracteres — texto maior é recusado quem limita o campo é o portal do município "o acompanhamento devolve 404" o identificador não corresponde a nada naquele órgão desconhecido, digitado errado e pertencente a outro órgão devolvem os três a mesma resposta vazia, de propósito — para ninguém descobrir por tentativa que um código existe não significa que a solicitação foi apagada confira o código guardado pelo portal antes de mandar o cidadão pedir de novo, senão entra uma segunda solicitação igual no funil de quem vende "consultamos o acompanhamento e não vem o valor" é o comportamento correto — o canal nunca devolve valor "funciona no servidor e falha no navegador" o navegador manda o cookie de sessão junto com a chave, e aí o erp trata a chamada como se fosse uma pessoa e recusa; a integração tem que chamar sem cookie quando o parceiro relatar erro o que ele relata o que provavelmente é "dá 401" chave errada, digitada com espaço, ou já revogada "dá 403 numa operação que existe" falta aquela operação no escopo da chave — reemita "dá 403 e você diz que está no escopo" o recurso pode ser fechado para integração; abra chamado "dá 429" ele está estourando o limite de chamadas; é ele que ajusta o ritmo "abri o endereço da documentação no navegador e deu 401" ele navegou direto, sem a troca descrita em abrir o contrato da api — o navegador não leva a chave junto; ou ele destrava, ou o programa dele baixa o documento com a chave no cabeçalho o catálogo de operações, na documentação para desenvolvedores, mostra o escopo exigido por operação — é a lista da qual você monta o escopo da chave, sem adivinhar o que esta seção não cobre personalizar telas sem programar (campos e telas novas, rótulos, ordem dos campos) seção administração docid\ z8ss7r6bvhs09rp1spxud contrato, exemplos de código e catálogo coleção documentação para desenvolvedores