Metadata-Version: 2.4
Name: integracaoequals
Version: 1.0.1
Summary: SDK Python para integração com a API de retornos da Equals
License-Expression: 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"

# integracaoequals

SDK Python para integração com a API de retornos da Equals.

## Instalação

```bash
pip install integracaoequals
```

## Início rápido

```python
from retorno_sdk import EqualsRetornoSDK

sdk = EqualsRetornoSDK(api_token="SEU_TOKEN")

remessa = sdk.gerar_remessa(id_config=1234, data_inicial="01/05/2026", data_final="31/05/2026")

for registro in sdk.iter_todos_dados(remessa["id"]):
    print(registro)
```

---

## Endpoints

### `get_configuracoes()`

Lista as configurações de remessa disponíveis para o token.

```python
configs = sdk.get_configuracoes()
# [{"id": 1234, "nome": "Vendas - Equals (API)"}, ...]
```

---

### `gerar_remessa(id_config, data_inicial, data_final)`

Solicita a geração de uma remessa para um período. Retorna o ID da remessa criada.

```python
remessa = sdk.gerar_remessa(
    id_config=1234,
    data_inicial="01/05/2026",
    data_final="31/05/2026",
)
# {"id": 7000000001110835}
```

Com filtros opcionais:

```python
remessa = sdk.gerar_remessa(
    id_config=1234,
    data_inicial="01/05/2026",
    data_final="31/05/2026",
    filtro_estabelecimentos=[101, 102],
    filtro_adquirentes=[1, 2],
)
```

---

### `get_remessas()`

Lista remessas existentes. Todos os parâmetros são opcionais.

```python
# Todas as remessas
remessas = sdk.get_remessas()

# Por ID
remessa = sdk.get_remessas(id_remessa=7000000001110835)

# Só as concluídas
concluidas = sdk.get_remessas(situacao="CONCLUIDO")

# Por período de geração
remessas = sdk.get_remessas(
    data_geracao_inicial="01/05/2026",
    data_geracao_final="31/05/2026",
)
```

Situações possíveis: `EM_PROCESSAMENTO`, `CONCLUIDO`, `ERRO`.

---

### `get_dados_remessa(id_remessa, pagina)`

Busca uma página específica de registros de uma remessa.

```python
pagina = sdk.get_dados_remessa(id_remessa=7000000001110835, pagina=1)
# {"id": ..., "pagina": 1, "registros": {"registro": [...]}}
```

---

### `iter_todos_dados(id_remessa)` ⭐

Itera por todos os registros de todas as páginas sem carregar tudo na memória.
Recomendado para remessas grandes.

```python
for registro in sdk.iter_todos_dados(id_remessa=7000000001110835):
    print(registro)
```

---

### `get_todos_dados(id_remessa)`

Retorna todos os registros em uma lista. Use para remessas pequenas.

```python
dados = sdk.get_todos_dados(id_remessa=7000000001110835)
# [{"NSR": 1, "VLBRUTO": 15000, ...}, ...]
```

---

### `processar_remessa(id_remessa, salvar_registro)`

Itera sobre todos os registros e chama uma função para cada um. Ideal para salvar direto no banco.

```python
sdk.processar_remessa(
    id_remessa=7000000001110835,
    salvar_registro=meu_banco.inserir,
)
```

---

### `deletar_remessa(id_remessa)`

Remove uma remessa.

```python
sdk.deletar_remessa(id_remessa=7000000001110835)
```

---

### `validar_webhook(payload, signature)`

Valida a assinatura de um webhook recebido da Equals.

```python
sdk = EqualsRetornoSDK(api_token="SEU_TOKEN", webhook_secret="SEU_WEBHOOK_SECRET")

valido = sdk.validar_webhook(payload=request.body, signature=request.headers["X-Hub-Signature-256"])

if valido:
    print("Webhook autentico")
```

---

## Transformação de dados

### `criar_transformador` — renomeia campos

```python
from retorno_sdk import criar_transformador

parser = criar_transformador({
    "NSR":         "numero_sequencial",
    "VLBRUTO":     "valor_bruto",
    "VLLIQUIDO":   "valor_liquido",
    "DTMOVIMENTO": "data_movimento",
})

for registro in sdk.iter_todos_dados(id_remessa, parser=parser):
    print(registro["valor_bruto"])  # campo renomeado
```

---

### `transformar_campos` — processa o valor de um campo

```python
from retorno_sdk import transformar_campos

parser = transformar_campos({
    "VLBRUTO":     lambda v, _: round(v / 100, 2),   # centavos → reais
    "DTMOVIMENTO": lambda v, _: f"{str(v)[:4]}-{str(v)[4:6]}-{str(v)[6:]}",  # 20260501 → "2026-05-01"
})
```

O segundo argumento do lambda é o registro completo — útil para cálculos entre campos:

```python
parser = transformar_campos({
    "VLLIQUIDO": lambda v, reg: f"{round(v / reg['VLBRUTO'] * 100, 1)}%"  # % do bruto
})
```

---

### `compor_transformadores` — encadeia transformações

Primeiro renomeia, depois processa os valores com os nomes novos:

```python
from retorno_sdk import compor_transformadores, criar_transformador, transformar_campos

parser = compor_transformadores(
    # 1. Renomeia as chaves da API para o nome do seu sistema
    criar_transformador({
        "NSR":         "numero_sequencial",
        "VLBRUTO":     "valor_bruto",
        "VLLIQUIDO":   "valor_liquido",
        "DTMOVIMENTO": "data_movimento",
        "BANDEIRA":    "bandeira",
        "ADQUIRENTE":  "adquirente",
        "PARCELA":     "parcela_atual",
        "PARCELAS":    "total_parcelas",
    }),
    # 2. Transforma os valores já com os nomes novos
    transformar_campos({
        "valor_bruto":    lambda v, _: round(v / 100, 2),
        "valor_liquido":  lambda v, _: round(v / 100, 2),
        "data_movimento": lambda v, _: f"{str(v)[:4]}-{str(v)[4:6]}-{str(v)[6:]}",
        "parcela_atual":  lambda v, reg: f"{v}/{reg['total_parcelas']}",  # "2/7"
    }),
)

for registro in sdk.iter_todos_dados(id_remessa, parser=parser):
    print(registro)
```

---

## Cliente async

Para uso com FastAPI, Django async ou qualquer pipeline assíncrono:

```python
from retorno_sdk import EqualsRetornoSDKAsync

async def baixar():
    async with EqualsRetornoSDKAsync(api_token="SEU_TOKEN") as sdk:
        remessa = await sdk.gerar_remessa(1234, "01/05/2026", "31/05/2026")

        async for registro in sdk.iter_todos_dados(remessa["id"]):
            print(registro)
```

Todos os métodos do cliente síncrono têm equivalente async.

---

## CLI

Teste a integração sem escrever código:

```bash
# Verificar conexão e listar configurações
equals-sdk --token SEU_TOKEN testar

# Listar remessas concluídas
equals-sdk --token SEU_TOKEN remessas --situacao CONCLUIDO

# Gerar remessa
equals-sdk --token SEU_TOKEN gerar --config 1234 --inicio 01/05/2026 --fim 31/05/2026

# Baixar dados para arquivo
equals-sdk --token SEU_TOKEN baixar --id 7000000001110835 --output dados.json
```

O token também pode ser passado via variável de ambiente `EQUALS_API_TOKEN`.

---

## Tratamento de erros

```python
from retorno_sdk.exceptions import (
    AuthenticationError,   # Token inválido (401/403)
    RateLimitError,        # Limite de requisições (429) — o SDK reintenta automaticamente
    RemessaNotFoundError,  # Remessa não encontrada
    RemessaNotReadyError,  # Remessa ainda em processamento
    EqualsAPIError,        # Outros erros HTTP
)

try:
    dados = sdk.get_todos_dados(id_remessa)
except RemessaNotReadyError as e:
    print(f"Situação atual: {e.situacao}")  # EM_PROCESSAMENTO
except AuthenticationError:
    print("Verifique o token")
except EqualsAPIError as e:
    print(f"Erro HTTP {e.status_code}: {e}")
```

---

## Testes

```bash
python -m pytest tests/
```
