Integrações¶
Em uma frase. Histórico do que os ERPs cadastraram no Dados Mestres por API — uma linha por chamada, com o resultado e as entidades gravadas. Tela de auditoria, sem cadastro.
Quem usa: analista fiscal, suporte · Frequência: ao conferir uma carga do ERP ou investigar uma empresa que não chegou · Pré-requisitos: um ERP com credencial de integração emitida pelo Hub
Para que serve¶
Além do cadastro pela tela e da importação por planilha, o ERP do cliente pode cadastrar empresa, inscrições estaduais de substituto tributário e certificado digital numa única chamada de API. Esta tela mostra cada uma dessas chamadas: de qual sistema veio, para qual CNPJ, se deu certo e o que foi gravado.
Ela responde a perguntas como "o ERP mandou a filial nova?", "por que o certificado não entrou?" e "esta empresa foi criada à mão ou pela integração?".
Como chegar¶
- No Hub, abra o app Dados Mestres.
- Selecione o tile Integrações.
A tela de listagem¶
Uma linha por chamada, não por tabela. Uma integração que criou a empresa, duas inscrições estaduais e o certificado aparece como uma linha; o que ela gravou fica no detalhe.
| Coluna | Conteúdo |
|---|---|
| Origem | Sistema que enviou (nome informado pelo ERP, ou o identificador da credencial) |
| Empresa | CNPJ da empresa enviada |
| Recurso | O que foi integrado — hoje, sempre Empresa |
| Data e hora | Quando a chamada chegou. A lista abre com as mais recentes primeiro |
| Status | Selo de situação e, quando houver, a mensagem do erro |
| Registros | Quantas entidades foram criadas e quantas atualizadas (empresa, inscrições estaduais, certificado) — duas inscrições criadas contam como uma entidade |
| Duração | Tempo de processamento da chamada |
Filtros: Origem, Status, Entidade e o período De / Até. A busca é pelo CNPJ da empresa. O botão de atualizar recarrega a lista; enquanto houver linha em Processando, a tela se atualiza sozinha.
Quando a integração gravou a empresa, o ícone de prédio na linha abre o cadastro dela direto na tela de Empresas.
Status¶
| Status | Significado | Quem age |
|---|---|---|
| Sucesso | Tudo gravado | — |
| Recusada | O conteúdo enviado tem problema (CNAE inexistente, senha do certificado errada, CNPJ do certificado diferente do da empresa…) | O ERP corrige e reenvia |
| Falhou | Erro interno do Dados Mestres | Suporte Invent investiga |
| Processando | Chamada em andamento. Uma linha parada nesse estado indica que o processamento foi interrompido | Suporte, se não se resolver |
Detalhe da integração¶
Clicar numa linha abre o detalhe: status, CNPJ, duração, Request ID e Idempotency-Key (identificadores que o suporte usa para rastrear a chamada) e a tabela Entidades alimentadas:
| Coluna | Conteúdo |
|---|---|
| Entidade | Empresa, Inscrição estadual (ST) ou Certificado digital |
| Tabela | Tabela do banco onde o dado foi gravado |
| Ação | Criado · Atualizado · Sem alteração · Ignorado · Recusado |
| Registros | Quantidade de registros daquela entidade |
| Registro gravado | Identificador do registro; na empresa, é um link para o cadastro |
Integração recusada ou com falha mostra "Nenhuma — a integração não chegou a gravar."
Regras de negócio¶
- RN-INT-001 — Tudo ou nada. Empresa, inscrições e certificado são gravados juntos. Se qualquer parte falha, nada é gravado — não existe integração "parcial".
- RN-INT-002 — O CNPJ identifica a empresa. Reenviar o mesmo CNPJ atualiza o cadastro existente; nunca cria empresa duplicada.
- RN-INT-003 — Reenvio não duplica. Uma chamada repetida com a mesma chave de idempotência devolve o resultado já registrado. Reusar a chave com conteúdo diferente é recusado.
- RN-INT-004 — Reenviar uma recusa devolve a mesma recusa. Uma integração que falhou por erro interno pode ser reenviada e é processada de novo.
- RN-INT-005 — A origem vem da credencial. O sistema de origem é o da credencial emitida pelo Hub, não um campo que o ERP preenche. O nome exibido é só rótulo.
- RN-INT-006 — Certificado exige permissão própria. A credencial precisa de escopo de certificado, além do de escrita, para enviar certificado digital.
- RN-INT-007 — O conteúdo enviado não é guardado. A trilha registra o resultado, as entidades e o código do erro, mas não o conteúdo da chamada, que traz o arquivo e a senha do certificado.
- RN-INT-008 — Somente leitura. Nada nesta tela edita, reprocessa ou apaga integração.
O que esta tela não faz¶
- Não reprocessa. Para corrigir uma recusa, o ERP reenvia a chamada.
- Não mostra o conteúdo enviado. Veja RN-INT-007.
- Não cadastra empresa. Cadastro manual é na tela de Empresas; carga por planilha, em Importações.
- Não emite a credencial do ERP. A credencial de integração é gerada no Hub.
Erros e mensagens¶
| Mensagem | Causa | O que fazer |
|---|---|---|
| Senha do certificado incorreta. | Senha do PFX não confere | ERP reenvia com a senha correta |
| Arquivo de certificado inválido ou ilegível. | O arquivo não é um PFX válido | Conferir o certificado A1 |
| CNPJ do certificado diferente do CNPJ da empresa. | Certificado de outra empresa | Enviar o certificado da própria empresa |
| Código CNAE não existe na tabela de referência. | CNAE inexistente | Corrigir o CNAE no ERP |
| Código IBGE do município não existe na referência. | Município inválido | Corrigir o código IBGE |
| UF informada não existe na tabela de referência. | UF inválida em inscrição estadual | Corrigir a UF |
| A credencial não tem escopo para este conteúdo. | Credencial sem permissão (ex.: certificado) | Ajustar os escopos da credencial no Hub |
| Idempotency-Key reusada com outro conteúdo. | Mesma chave, dados diferentes | ERP gera uma chave nova por envio distinto |
integration.processing_expired |
Um envio anterior com a mesma chave ficou interrompido por mais de 10 minutos e foi reaberto | Nenhuma: o reenvio já foi processado de novo |
company.duplicate_code · company.duplicate_part_code · company.duplicate_alternative_code (aparecem como código) |
Outra empresa da conta já usa esse código de referência, de participante ou alternativo | Corrigir o código no ERP ou na empresa que já o usa |
| Falha inesperada durante o processamento. | Erro interno | Acionar o suporte com o Request ID |
Relação com SPED / EFD¶
A integração alimenta os mesmos cadastros da tela de Empresas, e a relação com a EFD é a descrita no capítulo 1. Empresas. A origem (tela, planilha ou API) não muda o que vai para o arquivo.
| Registro | Relação |
|---|---|
| 0000 / 0005 | Identificação e dados complementares da empresa integrada |
| 0015 | Uma linha por inscrição estadual de substituto tributário enviada pelo ERP |
Atenção à inscrição de substituto. Cada 0015 obriga a apresentar os registros E200 e E300 daquela UF, mesmo sem movimento no período [Guia Prático EFD-ICMS/IPI 3.2.3, p. 32]. Uma inscrição incluída pelo ERP passa a exigir essa apuração na próxima EFD.
Perguntas frequentes¶
O ERP diz que enviou, mas não vejo a linha. Confira o período e os filtros. Sem nenhuma linha, a chamada não chegou ao Dados Mestres — verifique a credencial e o endereço configurados no ERP.
A integração foi recusada. Preciso corrigir algo aqui? Não. A recusa aponta problema no conteúdo enviado; a correção é no ERP, seguida de reenvio.
Editei na tela uma empresa que veio pela integração. O ERP sobrescreve? Sim, no próximo envio daquele CNPJ: a integração atualiza o cadastro existente.