konduto-rs

SDK não oficial em Rust para a API da Konduto - Plataforma de análise de prevenção a fraude.

Características

Cliente HTTP assíncrono completo para a API da Konduto
Autenticação integrada (Basic Auth)
Tipos fortemente tipados para todas as estruturas de dados
Suporte a todos os endpoints principais:
- Envio e consulta de pedidos
- Atualização de status de pedidos
- Gerenciamento de Blocklist, Allowlist e Reviewlist
Métricas automáticas (feature statsd):
StatsD/DogStatsD nativo
Rastreamento de latência, taxa de requisições, erros

Instalação

Adicione ao seu Cargo.toml:

[dependencies]
konduto-rs = "0.1"
tokio = { version = "1", features = ["full"] }

# Para habilitar métricas automáticas (opcional)
# konduto-rs = { version = "0.1", features = ["statsd"] }

Configuração

Obtenha sua chave de API no painel da Konduto e configure como variável de ambiente:

export KONDUTO_API_KEY="sua_chave_api_aqui"

Exemplos de Uso

Enviando um Pedido para Análise

use konduto::{KondutoClient, Order, Customer, Payment, PaymentType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Criar cliente
    let client = KondutoClient::new("sua_api_key".to_string());
    
    // Criar dados do cliente
    let customer = Customer::builder()
        .id("CUSTOMER123")
        .name("João Silva")
        .email("joao@example.com")
        .phone1("+55 11 98765-4321")
        .tax_id("12345678900")
        .build();
    
    // Criar pedido
    let order = Order::builder()
        .id("ORDER123")
        .total_amount(100.0)
        .customer(customer)
        .analyze(true)
        .build();
    
    // Enviar para análise
    let response = client.send_order(&order).await?;
    
    println!("Recomendação: {:?}", response.recommendation);
    println!("Score: {:.2}", response.score);
    
    Ok(())
}

Consultando um Pedido

use konduto::KondutoClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    let order = client.get_order("ORDER123").await?;
    println!("Status: {:?}", order.status);
    println!("Recomendação: {:?}", order.recommendation);
    
    Ok(())
}

Atualizando Status de um Pedido

use konduto::{KondutoClient, OrderStatus};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    let response = client
        .update_order_status("ORDER123", OrderStatus::Approved)
        .await?;
    
    println!("Status atualizado para: {:?}", response.status);
    
    Ok(())
}

Gerenciando Listas (Blocklist/Allowlist)

use konduto::{KondutoClient, ListType, ListEntryType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KondutoClient::new("sua_api_key".to_string());
    
    // Bloquear email
    client.block_email("fraud@example.com", Some("Fraude confirmada")).await?;
    
    // Permitir email de cliente confiável
    client.allow_email("vip@example.com", Some("Cliente VIP")).await?;
    
    // Bloquear CPF
    client.block_cpf("12345678900", Some("Cliente fraudador")).await?;
    
    // Bloquear IP
    client.block_ip("192.168.1.100", Some("IP suspeito")).await?;
    
    // Consultar item em lista
    let entry = client.get_from_list(
        ListType::Blocklist,
        ListEntryType::Email,
        "fraud@example.com"
    ).await?;
    
    println!("Encontrado na lista: {}", entry.list);
    
    // Remover da lista
    client.remove_from_list(
        ListType::Blocklist,
        ListEntryType::Email,
        "fraud@example.com"
    ).await?;
    
    Ok(())
}

Exemplos Completos

Confira os exemplos completos no diretório examples/:

# Enviar um pedido
cargo run --example send_order

# Gerenciar listas
cargo run --example blocklist

# Métricas automáticas (requer feature statsd)
cargo run --example automatic_metrics --features statsd

Observabilidade e Métricas

A SDK possui suporte nativo para métricas automáticas via StatsD/DogStatsD:

Métricas Disponíveis

Quando a feature statsd está habilitada, a SDK envia automaticamente:

konduto.requests.hits - Taxa de requisições
konduto.requests.latency - Latência (média, P95, P99)
konduto.requests.status - Distribuição de status HTTP
konduto.requests.errors - Taxa de erros

Todas com tags: method, endpoint, status, latency_bucket, sdk:konduto-rs

Testes

Execute os testes:

# Usando just (recomendado)
just test

# Ou usando cargo diretamente
cargo test

🛠️ Ferramentas de Desenvolvimento

Este projeto usa just como task runner para facilitar o desenvolvimento.

Instalação do Just

# macOS
brew install just

# Linux/Windows
cargo install just

Comandos Úteis

# Ver todos os comandos disponíveis
just

Documentação da API

Para mais detalhes sobre a API da Konduto, consulte:

Documentação oficial da API Konduto

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

Fazer fork do projeto
Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
Push para a branch (git push origin feature/MinhaFeature)
Abrir um Pull Request

⚠️ Aviso

Esta é uma SDK não oficial para a API da Konduto. Para SDKs oficiais, consulte:

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.

Links Úteis

Suporte

Para questões relacionadas à API da Konduto, entre em contato com o suporte oficial da Konduto.

Para questões sobre esta SDK, abra uma issue no GitHub.

Feito com ❤️ em Rust

konduto-rs 0.2.2