Metadata-Version: 2.4
Name: nsj_integracao_api_client
Version: 2.2601.0.5
Summary: Client em Python desenvolvido para facilitar a extração de dados de bancos de dados de ERPs e a integração com as APIs de integração da Nasajon. Ele automatiza o fluxo de comunicação entre sistemas, oferecendo funcionalidades para consulta, transformação e envio de dados de maneira eficiente.
Home-page: https://github.com/Nasajon/nsj_integracao_api_client
Author: Nasajon Sistemas
Author-email: contact.dev@nasajon.com.br
Project-URL: Source, https://github.com/Nasajon/nsj_integracao_api_client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.4
Description-Content-Type: text/markdown
Requires-Dist: nsj-integracao-api-entidades==2.0.0a25.post70
Requires-Dist: colorama==0.4.6
Requires-Dist: tzdata==2025.1
Requires-Dist: sentry-sdk==1.7.1
Requires-Dist: psutil>=5.9.0

# Integracao api client

Cliente em Python desenvolvido para facilitar a extração de dados de bancos de dados de ERPs e a integração com as APIs de integração da Nasajon. Permite que se extraia dados do ERP e efetue integrações na base do bancos web para um tenant previamente configurado, para isso, utiliza-se do mesmo mecanismo de identificação da sincronia pelo Symmetrics, onde um token de tenant é utilizado para prover a comunicação.

---

## Visão geral

O Cliente possui um modo console onde disponibiliza suas principais operações sendo:

* [Instalação](#instalação)
* [Carga Inicial](#carga-inicial)
* [Integração](#intregação)
* [Recarga](#recarga)
* [Verificação de integridade](#verificação-de-integridade)

### Instalação

Possibilita através de uma **chave de ativação**, configurar a integração, escolhendo quais Grupos Empresariais serão integrados. A chave de ativação pode ser obtida no Diretório->Tenants, seguindo o mesmo fluxo da chave de ativação da sincronia. Caso já exista um sincronia instalada, usará a mesma chave no processo.


### Carga Inicial

Efetua a carga inicial de todos os dados das entidades registradas no cliente e dos grupos empresariais selecionados para as apis na web.

### Integração

Considerando as entidades com dados pendentes para envio, seleciona os dados dos grupos configurados e os envia para as APIs de integração da Nasajon.

### Recarga

Mesmo princípio da carga inicial, selecionando apenas as entidades que se deseje rcarregar.

### Verificação de integridade

Permite efetuar uma comparação entre os dados do ambiente na api e os dados locais. A saída permite identificar as diferenaças e corrigir atravéz do envio dos dados para a api de integração.

---
## Arquitetura

O diagrama abaixo apresenta a arquitetura do sistema de integração, destacando os principais componentes e suas interações:

1. **Usuário ERP**: Configura e acompanha o processo de integração.
2. **Ambiente ERP Nasajon**:
    - **Banco de Dados ERP**: Contém os dados operacionais do ERP.
    - **Integrador**: Aplicação local em Python que extrai dados do ERP e os envia para o ambiente web.
3. **Ambiente WEB Nasajon**:
    - **APIs de Integração Web**: Recebem os dados enviados pelo integrador.
    - **Banco de Dados Web**: Armazena os dados processados pelas APIs.
4. **Biblioteca de Entidades**: Modela os dados que serão extraídos e enviados, garantindo a integridade entre o integrador e as APIs.

As relações entre os componentes mostram como os dados fluem desde o ERP até o ambiente web, passando pelo integrador e utilizando a biblioteca de entidades para padronização.

```mermaid
%%{init: {'theme':'default'}}%%
C4Container

Person(usuario, "Usuário ERP", "Configura e executa a integração.")

System_Boundary(erp, "Ambiente ERP Nasajon") {
    ContainerDb(erp_db, "Banco de Dados ERP", "PostgreSQL", "Contém dados operacionais do ERP")
    Container(integrador, "Integrador", "Aplicação Local Python", "Extrai dados do ERP e envia para a Web")
}

System_Boundary(web, "Ambiente WEB Nasajon") {
    System_Ext(apis, "APIs de Integração Web", "Recebem os dados enviados pelo integrador")
    ContainerDb_Ext(db_web, "Banco de Dados Web", "Armazena os dados processados pelas APIs")
}

Container(entidades_lib, "Biblioteca de Entidades", "Python", "Modela os dados que serão extraídos e enviados")

Rel(usuario, integrador, "Configura e acompanha")
Rel(integrador, erp_db, "Lê dados para integrar")
Rel(integrador, entidades_lib, "Entidades modeladas para integração")
Rel(integrador, apis, "Envia entidades via HTTP")
Rel(apis, db_web, "Persiste dados recebidos")
Rel(apis, entidades_lib, "Entidades modeladas para integração")

```

### Componentes

**ERP Nasajon**
* Aplicação com banco de dados Postgres, onde residem os dados de um cliente.

**Bancos Web**
* Banco de dados Postgres multi-tenant que guarda os dados consumidos pelas aplicações web.

**Integrador**
* Captura os dados do ERP e envia para as APIs de integração, usando **bibliotecas de entidades**.

**APIs de Integração**
* Recebe os dados enviados pelo integrador e os armazena no banco de dados web. Poderão existir diversas apis, uma para cada Tribo, a exemplo [Integração Pessoas API](https://github.com/Nasajon/integracao-pessoas-api).

**Biblioteca de Entidades**
* Modela os dados que serão capturados e enviados para as APIs de integração. O Integrador e as apis usam a mesmma biblioteca de entidades ([nsj_integracao_api_entidades](https://github.com/Nasajon/nsj_integracao_api_entidades)) para garantir a integridade dos dados. Construída através da blioteca [nsj_rest_lib](https://github.com/Nasajon/nsj_rest_lib).


### Modelo de dados

| Módulo                          | Descrição                                   |
|---------------------------------|---------------------------------------------|
| `util.entidades_integracao`     | Gerencia as entidades que serão integradas. É alimentada pela trigger `TRG_registra_entidade_integracao` e função `util.registra_entidade_integracao()`. |
| `util.grupos_empresariais_integracao` | Gerencia os grupos empresariais para integração. |


## Executando localmente

Para executar localmente, Tenha disponível:

* Uma base local do ERP Nasajon;
* Copie o arquivo `env.dist` para `.env` e preencha os dados de conexão com o banco de dados local;
* Usar os comandos dispoíveis no Makefile para executar as operações.

> É possível usar tanto as Apis de QA/DEV, quanto subir uma instância de apis local. Para isso, na execução use o parâmetro `--env=local|dev|qa|prod`.

> Caso queira rodar as apis localmente, será preciso uma base de dados do bancosweb para testes e subir o projeto de apis localmente, tal como o [integracao-pessoas-api](https://github.com/Nasajon/integracao-pessoas-api).

## Distribuição

Existe uma versão do JobManager onde esta biblioteca foi distribuída como um Job, estando disponível tanto para agendamentos como execução pelo método [`run_job`](https://github.com/Nasajon/Jobmanager?#integracao_apis).


## Versionamento e publicação no PyPI

Esta seção explica como as bibliotecas se relacionam, em qual branch trabalhar em cada projeto, e como publicar novas versões no PyPI sem quebrar o build das APIs.

### Como as peças se encaixam

São três projetos, e a relação entre eles é a principal fonte de confusão:

| Projeto | Papel | Branch de trabalho | Versão no PyPI |
|---|---|---|---|
| [nsj_integracao_api_entidades](https://github.com/Nasajon/nsj_integracao_api_entidades) | Biblioteca de entidades (modelos dos dados) | **Branch única: `main`** | `2.0.0a25.postNN` (ex.: `2.0.0a25.post70`) |
| nsj_integracao_api_client (este projeto) | Integrador | **Sempre a branch da LD** (`v2.2501`, `v2.2502`, `v2.2601`, ...) | `2.<LD>.0.<N>` (ex.: `2.2601.0.3`) |
| [integracao-pessoas-api](https://github.com/Nasajon/integracao-pessoas-api) | API que recebe os dados | — | Não publica lib; consome as duas acima no `requirements.txt` |

```mermaid
graph TD
    A["integracao-pessoas-api<br/>(requirements.txt)"]
    C["nsj_integracao_api_client<br/>(branch da LD, ex.: v2.2601)"]
    E["nsj_integracao_api_entidades<br/>(branch única: main)"]
    A -->|"nsj_integracao_api_client==2.2601.0.3"| C
    A -->|"nsj_integracao_api_entidades==2.0.0a25.post70"| E
    C -->|"setup.cfg exige versão EXATA:<br/>nsj-integracao-api-entidades==2.0.0a25.post70"| E
```

O ponto central: **o client declara, no seu `setup.cfg`, uma versão EXATA da entidades** (`nsj-integracao-api-entidades==...`). Logo, a versão da entidades no `requirements.txt` de qualquer API precisa ser **exatamente a mesma** que o client publicado exige. Qualquer divergência quebra a instalação.

### O erro clássico no GitHub Actions

```
The conflict is caused by:
    The user requested nsj_integracao_api_entidades==2.0.0a25.post68
    nsj-integracao-api-client 2.2502.0.79 depends on nsj-integracao-api-entidades==2.0.0a25.post67
ERROR: ResolutionImpossible
```

Traduzindo: o `requirements.txt` da API pediu a entidades `post68`, mas o client `2.2502.0.79` foi publicado exigindo a `post67`. Como ambas as exigências são de versão exata, não existe combinação possível e o pip desiste.

**Correção:** alinhar o par de versões. Ou o `requirements.txt` volta para a entidades que o client exige, ou publica-se um novo client apontando para a entidades nova (ver passo a passo abaixo). Em caso de dúvida sobre qual entidades um client exige, consulte o `setup.cfg` na branch da LD, na tag/commit daquela versão.

### Em qual branch trabalhar

**`nsj_integracao_api_entidades` — branch única (`main`)**
Toda alteração entra na `main` e gera uma nova versão sequencial no `setup.cfg` (`2.0.0a25-70` → `2.0.0a25-71`).

> Nota sobre grafia: `2.0.0a25-71` (no `setup.cfg`) e `2.0.0a25.post71` (no pip/PyPI) são **a mesma versão** — o pip apenas normaliza o sufixo. Não estranhe a diferença.

**`nsj_integracao_api_client` — sempre a branch da LD**
Existe uma branch por LD do ERP (`v2.2501`, `v2.2502`, `v2.2601`, ...), e o número da versão publicada carrega a LD: `2.2601.0.3` é a release 3 da LD 2601. Alterações e correções devem ser feitas **na branch da LD correspondente**, e a publicação no PyPI também parte sempre dela — nunca da `main`.

> **Atenção — ambientes não são branches:** o client possui 4 ambientes embutidos no próprio pacote (`LOCAL`, `DEV`, `QA`, `PROD`), escolhidos em tempo de execução pelo parâmetro `--env`. O **mesmo** pacote publicado atende desenvolvimento, QA e produção. Ou seja: branch define a **LD**; ambiente é só **parâmetro de execução**.

### Passo a passo: publicando novas versões

Pré-requisito (uma única vez): `make install_to_pkg` e credenciais do PyPI configuradas.

**Caso 1 — alterei só a `nsj_integracao_api_entidades`:**

1. Na `main` da entidades, incremente a `version` no `setup.cfg` (ex.: `2.0.0a25-70` → `2.0.0a25-71`);
2. Publique: `make build_pkg && make upload_pkg`;
3. Como o client exige versão exata, **publique também um novo client** apontando para a nova entidades (Caso 2);
4. Atualize o `requirements.txt` das APIs com o **par** novo (entidades + client).

**Caso 2 — alterei só o client (ou preciso repontar a entidades):**

1. Checkout na **branch da LD** (ex.: `v2.2601`);
2. No `setup.cfg`: incremente a `version` (ex.: `2.2601.0.3` → `2.2601.0.4`) e, se for o caso, atualize o pin `nsj-integracao-api-entidades==...` em `install_requires`;
3. Publique: `make build_pkg && make upload_pkg` (ou `make publish_pkg`);
4. Atualize o `requirements.txt` das APIs.

**Caso 3 — alterei os dois:**

Publique **na ordem: entidades → client → APIs**. Se inverter, o client apontará para uma versão de entidades que ainda não existe no PyPI.

### Checklist antes de subir build de API que consome essas libs

- [ ] O `requirements.txt` declara `nsj_integracao_api_client==X` e `nsj_integracao_api_entidades==Y`;
- [ ] No `setup.cfg` do client versão `X` (na branch da LD), o pin de entidades é exatamente `Y`;
- [ ] Lembrando que `2.0.0a25-NN` e `2.0.0a25.postNN` são a mesma versão, só muda a grafia.


### FAQ

#### Adicionar/alterar entidades na integração?

Para adicionar ou alterar entidades na integração, siga o seguinte procedimento:

1. **Identifique a Entidade**
    Verifique qual entidade precisa ser adicionada ou alterada. Certifique-se de que ela está devidamente modelada na [biblioteca de entidades](https://github.com/Nasajon/nsj_integracao_api_entidades), seguindo a conveção do rest_lib.

1. **Atualize a Biblioteca de Entidades**
    Caso necessário, atualize a biblioteca de entidades ([nsj_integracao_api_entidades](https://github.com/Nasajon/nsj_integracao_api_entidades)) no [requirements.txt](requirements.txt) para incluir a nova versão da biblioteca — respeitando o alinhamento de versões descrito em [Versionamento e publicação no PyPI](#versionamento-e-publicação-no-pypi).
    Atualize a [lista de entidades no Integrador](./src/nsj_integracao_api_client/service/integrador.py#L45) respeitando ordem da dependência de chaves estrangeriras.


1. **Configure no Banco de Dados ERP**
    Adicione ou atualize os registros na tabela `util.entidades_integracao` para que a nova entidade seja reconhecida pelo integrador. Crie uma trigger para a função `util.registra_entidade_integracao()` apontando a entidade.

    ```sql
    CREATE TRIGGER "TRG_registra_entidade_integracao" AFTER INSERT OR UPDATE ON esquema.tabela FOR EACH ROW EXECUTE PROCEDURE util.registra_entidade_integracao();
    ```
1. **Teste Localmente**
    Execute o integrador localmente para verificar se a nova entidade está sendo capturada e enviada corretamente para as APIs. Use o comando apropriado no Makefile, como `make carga-inicial`.

1. **Valide na API de Integração**
    Certifique-se de que os dados enviados estão sendo processados corretamente pela API de integração. Verifique os logs e o banco de dados web para confirmar.

1. **Atualize a Documentação**
    Documente a nova entidade e quaisquer alterações realizadas para garantir que a equipe esteja ciente das mudanças.

1. **Distribua as Alterações**
    Caso esteja utilizando o JobManager, atualize o job correspondente para incluir a nova entidade ou as alterações realizadas.

> **Dica:** Sempre mantenha um ambiente de QA para validar as alterações antes de aplicá-las em produção.


# Notas

> No Linux, instale designer com:

```sh
sudo apt install qttools5-dev-tools
```

```sh
sudo apt install pyqt5-dev-tools
```

sudo apt install qt5-base-dev
sudo apt install qt5-tools-dev


https://gist.github.com/r00tdaemon/1dcd57542bdaf3c9d1b0dd526ccd44ff
