Embedded Files
Exemplo de integração em Oracle com a API SINTEGRA da ArquivoNFe, para consulta em lote de dados cadastrais por UF.
A API permite realizar consultas utilizando CNPJ, CPF ou Inscrição Estadual (IE), conforme a disponibilidade da consulta para cada UF.
🔄 Crie as tabelas - Scripts e códigos disponíveis no GITHUB
Execute o script tabelas.sql no schema Oracle que será utilizado para a integração.
O script cria:
Tabela VALIDA_CONTRIBUINTE: armazena as solicitações de consulta.
Tabela VALIDA_CONTRIBUINTE_RETORNO: armazena os dados retornados pela API.
Sequences para geração dos identificadores.
Constraints e índice para relacionamento entre as tabelas.
Registros de exemplo para teste.
🔄 Configure o package
Abra o arquivo PK_VALIDA_CONTRIBUINTE.pck e configure o token de acesso.
O package utiliza os recursos:
APEX_WEB_SERVICE: envio das requisições HTTP.
APEX_JSON: leitura e interpretação das respostas JSON.
DBMS_LOCK.SLEEP: intervalo entre tentativas de consulta.
O schema precisa possuir os privilégios necessários para utilização desses recursos e acesso HTTPS ao endpoint da API.
🔄 Execute a integração
O package disponibiliza duas procedures principais:
PB_ENVIA_SINTEGRA
Responsável por enviar as consultas pendentes à API, utilizando CNPJ, CPF ou IE e armazenando o request_id retornado.
PB_RETORNO_SINTEGRA
Responsável por consultar os resultados das solicitações enviadas anteriormente e armazenar os dados cadastrais retornados.
A separação em duas etapas permite organizar o envio das solicitações e o processamento dos respectivos retornos.
🔄 Execução dos processos
As procedures de integração podem ser executadas de diferentes formas, de acordo com a arquitetura do sistema que estiver utilizando a API.
Por exemplo:
por meio de um JOB do Oracle;
por um scheduler da aplicação;
diretamente por uma aplicação ou sistema ERP;
manualmente, durante testes ou processos específicos.
Não é necessário manter as procedures em execução continuamente.
O cliente pode definir a frequência e a forma de execução de acordo com sua necessidade.
Por exemplo, uma implementação pode executar periodicamente:
BEGIN
pk_valida_contribuinte.pb_envia_sintegra;
pk_valida_contribuinte.pb_retorno_sintegra;
END;
/
Outra implementação pode separar as duas etapas em processos diferentes, inclusive utilizando horários ou JOBs distintos.
🔄 Controle de transação
O controle da transação (COMMIT ou ROLLBACK) deve ser definido pelo usuário de acordo com a estrutura e a arquitetura de seu processo de integração.
🔄 Limite de tentativas
Durante o processo de consulta dos resultados, o exemplo possui um limite de 2.000 tentativas de chamada à API para o processamento dos registros.
Esse limite evita que um processo permaneça executando indefinidamente em situações nas quais determinados registros não estejam disponíveis para retorno.
Os registros que eventualmente não forem integrados dentro do processamento atual permanecem disponíveis para uma próxima execução, de acordo com as regras implementadas no processo do cliente.
Dessa forma, o processo pode ser executado novamente, permitindo que as solicitações pendentes sejam tratadas posteriormente.
O número de tentativas e os critérios de processamento podem ser adaptados pelo usuário conforme sua necessidade e arquitetura.
🔄 Consulte os resultados
Os registros de integração são armazenados nas tabelas:
SELECT *
FROM VALIDA_CONTRIBUINTE;
SELECT *
FROM VALIDA_CONTRIBUINTE_RETORNO;
A situação da solicitação é controlada pelo campo SIT: 1 - Pendente, 2 - Processado com erro e 3 - Processado
🔄 Fluxo de integração
O processo é dividido em duas etapas principais.
1. Envio das consultas
Os contribuintes são incluídos na tabela VALIDA_CONTRIBUINTE.
A procedure PB_ENVIA_SINTEGRA envia as solicitações para a API e recebe um request_id para cada consulta aceita.
2. Consulta dos resultados
A procedure PB_RETORNO_SINTEGRA utiliza o request_id para consultar posteriormente o resultado da solicitação.
Quando o resultado está disponível, os dados cadastrais são armazenados na tabela VALIDA_CONTRIBUINTE_RETORNO.
Fluxo resumido
VALIDA_CONTRIBUINTE
│
▼
PB_ENVIA_SINTEGRA
│
▼
API
│
▼
request_id
│
▼
PB_RETORNO_SINTEGRA
│
▼
VALIDA_CONTRIBUINTE_RETORNO
A arquitetura assíncrona permite separar o envio das solicitações da obtenção dos resultados.
Exemplos de execução
Inclusão dos registros para consulta na tabela valida contribuinte
Envia integração com o sintegra
Consulta e disponibilização dos dados da API na tabela valida_contribuinte_retorno
Google Sites
Report abuse