Metadata-Version: 2.4
Name: integracaoequals
Version: 1.0.0
Summary: SDK Python para integração com a API de retornos da Equals
License: MIT
Keywords: equals,pagamentos,conciliacao,retorno,sdk,integracao
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.22.0; extra == "dev"

# SDK Equals Retorno DevX

SDK enxuto para o fluxo de retorno da Equals.

## Comece por aqui

- pacote novo: `retorno_sdk/`
- guia principal: `docs/README.md`
- exemplo de fluxo: `examples/fluxo_retorno.py`
- exemplo de parser ERP: `examples/erp_mapping.py`
- exemplo de webhook: `examples/receber_webhook_retorno.py`

## Nota

O material abaixo faz parte do esqueleto anterior do projeto.
Para a nova integração de retorno, priorize `retorno_sdk/` e os markdowns em `docs/`.

## Instalação

```bash
pip install -r requirements.txt
```

## Uso

```python
from src.equals_retorno import EqualsRetornoSDK

sdk = EqualsRetornoSDK("token", "secret")

# Listar configs
configs = sdk.get_configuracoes()

# Gerar remessa
resp = sdk.gerar_remessa(1, "01/01/2023", "31/01/2023")

# Obter dados
dados = sdk.get_todos_dados(resp["id"])
```

## Endpoints

- `get_configuracoes()` - Lista opções
- `gerar_remessa(id, dt_ini, dt_fim)` - Gera remessa
- `get_remessas(id, situacao)` - Lista remessas
- `get_dados_remessa(id, pagina)` - Dados paginados
- `deletar_remessa(id)` - Deleta remessa
- `validar_webhook(payload, signature)` - Valida webhook
- `get_todos_dados(id)` - Todos os dados

## Transformação

```python
from src.data_transformer import criar_transformador

transformador = criar_transformador({"NSR": "seq", "VLBRUTO": "valor"})
sdk.set_transformer(transformador)
```

## Receber dados via webhook

```bash
set EQUALS_API_TOKEN=seu_token
set EQUALS_WEBHOOK_SECRET=seu_segredo
python examples/receber_dados_webhook.py --port 8000
```

Quando a Equals enviar um `POST` para `/webhook`, o script vai:

- validar a assinatura do webhook
- identificar o `id` da remessa no payload
- baixar todos os registros com `get_todos_dados()`
- salvar o resultado em `dados_recebidos/remessa_<id>.json`

## Testes

```bash
python -m unittest tests/test_sdk.py
```

if validador.validar(payload_json, signature_header):
    # Processar webhook
    pass
```

## Documentação Completa

Consulte [docs/SDK-Documentation.md](docs/SDK-Documentation.md) para documentação detalhada incluindo:

- Descrição completa de cada endpoint
- Exemplos de uso
- Tratamento de erros
- Layout dos dados
- Tipos de movimento
- Tabelas de referência

## Desenvolvimento

### Executar Testes

```bash
python -m unittest tests/test_sdk.py
```

### Executar Exemplos

```bash
python examples/example_usage.py
```

## Suporte

- **API Equals**: https://integrao-equals.readme.io/reference/con_get_retornos_configuracoes
- **Issues**: Abra uma issue no repositório

## Licença

Este projeto é distribuído sob a licença MIT.
