integracaoequals 1.0.1

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

integracaoequals

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

Instalação

pip install integracaoequals

Início rápido

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.

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.

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

Com filtros opcionais:

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.

# 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.

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.

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.

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.

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

---

deletar_remessa(id_remessa)

Remove uma remessa.

sdk.deletar_remessa(id_remessa=7000000001110835)

---

validar_webhook(payload, signature)

Valida a assinatura de um webhook recebido da Equals.

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

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

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:

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:

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:

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:

# 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

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

python -m pytest tests/