> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin

> KotlinアプリケーションにDodo Paymentsを統合するためのモダンなコルーチンとヌル安全性

Kotlin SDKは、Kotlinで書かれたアプリケーションからDodo Payments REST APIへの便利なアクセスを提供します。ヌル可能な値、Sequence、suspend関数、その他のKotlin特有の機能を備えており、使いやすさを考慮しています。

## インストール

### Gradle (Kotlin DSL)

依存関係を`build.gradle.kts`に追加してください:

```kotlin build.gradle.kts theme={null}
implementation("com.dodopayments.api:dodo-payments-kotlin:1.97.1")
```

### Maven

依存関係を`pom.xml`に追加してください:

```xml pom.xml theme={null}
<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-kotlin</artifactId>
  <version>1.97.1</version>
</dependency>
```

<Tip>
  最新の Dodo Payments 機能にアクセスするには常に最新の SDK バージョンを使用してください。最新バージョンは[Maven Central](https://central.sonatype.com/artifact/com.dodopayments.api/dodo-payments-kotlin)で確認してください。
</Tip>

<Info>
  この SDK は Java 8 以降が必要で、JVM と Android プラットフォームの両方と互換性があります。
</Info>

## クイックスタート

クライアントを初期化し、チェックアウトセッションを作成します:

```kotlin theme={null}
import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionCreateParams
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.ProductItemReq

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.baseUrl)
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

val params: CheckoutSessionRequest = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("product_id")
        .quantity(1)
        .build())
    .build()
    
val checkoutSessionResponse: CheckoutSessionResponse = client.checkoutSessions().create(params)
println(checkoutSessionResponse.sessionId())
```

<Warning>
  API キーは環境変数や暗号化された設定を使用して安全に保管してください。決してバージョン管理にコミットしないでください。
</Warning>

## コア機能

<CardGroup cols={2}>
  <Card title="Coroutines" icon="bolt">
    非同期処理のための Kotlin コルーチンを完全サポート
  </Card>

  <Card title="Null Safety" icon="shield-check">
    Kotlin のヌルセーフ機能を活用して堅牢なエラーハンドリングを実現
  </Card>

  <Card title="Extension Functions" icon="code">
    機能拡張のための慣用的な Kotlin 拡張
  </Card>

  <Card title="Data Classes" icon="layer-group">
    コピーおよび分解構文をサポートする型安全なデータクラス
  </Card>
</CardGroup>

## 設定

### 環境変数から

環境変数またはシステムプロパティから初期化します:

```kotlin theme={null}
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()
```

### 手動設定

すべてのオプションで手動で設定します:

```kotlin theme={null}
import java.time.Duration

val client = DodoPaymentsOkHttpClient.builder()
    .bearerToken("your_api_key_here")
    .baseUrl("https://live.dodopayments.com")
    .maxRetries(3)
    .timeout(Duration.ofSeconds(30))
    .build()
```

### テストモード

テスト/サンドボックス環境用に設定します:

```kotlin theme={null}
val testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build()
```

### タイムアウトとリトライ

グローバルまたはリクエストごとに設定します:

```kotlin theme={null}
import com.dodopayments.api.core.RequestOptions

// Global configuration
val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(45))
    .maxRetries(3)
    .build()

// Per-request timeout override
val product = client.products().retrieve(
    "prod_123",
    RequestOptions.builder()
        .timeout(Duration.ofSeconds(10))
        .build()
)
```

## 一般的な操作

### チェックアウトセッションの作成

チェックアウトセッションを生成します:

```kotlin theme={null}
val params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("prod_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build()

val session = client.checkoutSessions().create(params)
println("Checkout URL: ${session.checkoutUrl()}")
```

### 商品の作成

詳細な設定で商品を作成します:

```kotlin theme={null}
import com.dodopayments.api.models.products.Product
import com.dodopayments.api.models.products.ProductCreateParams
import com.dodopayments.api.models.misc.Currency
import com.dodopayments.api.models.misc.TaxCategory

val createParams = ProductCreateParams.builder()
    .name("Premium Subscription")
    .description("Monthly subscription with all features")
    .price(
        ProductCreateParams.RecurringPrice.builder()
            .currency(Currency.USD)
            .preTaxAmount(2999) // $29.99 in cents
            .paymentFrequencyInterval(ProductCreateParams.RecurringPrice.TimeInterval.MONTH)
            .paymentFrequencyCount(1)
            .build()
    )
    .taxCategory(TaxCategory.DIGITAL_PRODUCTS)
    .build()

val product: Product = client.products().create(createParams)
println("Created product ID: ${product.productId()}")
```

### ライセンスキーの有効化

顧客のためにライセンスキーを有効化します:

```kotlin theme={null}
import com.dodopayments.api.models.licenses.LicenseActivateParams
import com.dodopayments.api.models.licenses.LicenseActivateResponse

val activateParams = LicenseActivateParams.builder()
    .licenseKey("XXXX-XXXX-XXXX-XXXX")
    .instanceName("user-laptop-01")
    .build()

try {
    val activationResult: LicenseActivateResponse = client.licenses()
        .activate(activateParams)

    println("License activated successfully")
    println("Instance ID: ${activationResult.instanceId()}")
    println("Expires at: ${activationResult.expiresAt()}")
} catch (e: UnprocessableEntityException) {
    println("License activation failed: ${e.message}")
}
```

### サブスクリプションの処理

定期サブスクリプションを作成し管理します：

```kotlin theme={null}
import com.dodopayments.api.models.payments.AttachExistingCustomer
import com.dodopayments.api.models.payments.BillingAddress
import com.dodopayments.api.models.payments.CountryCode
import com.dodopayments.api.models.subscriptions.SubscriptionChargeParams
import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams

// Create a subscription
val subscriptionParams = SubscriptionCreateParams.builder()
    .billing(BillingAddress.builder()
        .city("San Francisco")
        .country(CountryCode.US)
        .state("CA")
        .street("1 Market St")
        .zipcode("94105")
        .build())
    .customer(AttachExistingCustomer.builder()
        .customerId("cus_123")
        .build())
    .productId("pdt_456")
    .quantity(1)
    .build()

val subscription = client.subscriptions().create(subscriptionParams)
println("Subscription ID: ${subscription.subscriptionId()}")

// Charge an on-demand subscription
// productPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
val chargeParams = SubscriptionChargeParams.builder()
    .subscriptionId(subscription.subscriptionId())
    .productPrice(2500)
    .build()

val chargeResponse = client.subscriptions().charge(chargeParams)
println("Payment ID: ${chargeResponse.paymentId()}")
```

<Info>
  `billing` は、最低でも2文字のISO `country` コードが必要です。既存の顧客を添付するには`AttachExistingCustomer` を使用し、新しい顧客を作成するには`NewCustomer` を使用してください。`productPrice` は最小の通貨単位で表されます。
</Info>

## 使用量ベースの請求

### 使用イベントの記録

メーターの使用を追跡します：

```kotlin theme={null}
import com.dodopayments.api.models.usageevents.EventInput
import com.dodopayments.api.models.usageevents.UsageEventIngestParams

val usageParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .customerId("cust_456")
        .eventId("event_123")
        .eventName("api_call")
        .build())
    .build()

client.usageEvents().ingest(usageParams)
println("Usage event recorded")
```

## 非同期操作

### 非同期クライアント

コルーチンベースの操作に非同期クライアントを使用します：

```kotlin theme={null}
import com.dodopayments.api.client.DodoPaymentsClientAsync
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClientAsync
import kotlinx.coroutines.runBlocking

val asyncClient: DodoPaymentsClientAsync = DodoPaymentsOkHttpClientAsync.fromEnv()

runBlocking {
    val customer = asyncClient.customers().retrieve("cust_123")
    println("Customer email: ${customer.email()}")
}
```

## エラーハンドリング

Kotlinの例外処理でエラーを処理します：

```kotlin theme={null}
import com.dodopayments.api.errors.*

try {
    val payment = client.payments().create(params)
    println("Success: ${payment.id()}")
} catch (e: AuthenticationException) {
    println("Authentication failed: ${e.message}")
} catch (e: InvalidRequestException) {
    println("Invalid request: ${e.message}")
    e.parameter?.let { println("Parameter: $it") }
} catch (e: RateLimitException) {
    println("Rate limit exceeded, retry after: ${e.retryAfter}")
} catch (e: DodoPaymentsServiceException) {
    println("API error: ${e.statusCode()} - ${e.message}")
}
```

### 機能的エラーハンドリング

機能的なエラーハンドリングには `Result` を使用します：

```kotlin theme={null}
fun safeCreatePayment(client: DodoPaymentsClient): Result<Payment> = runCatching {
    client.payments().create(params)
}

// Usage
safeCreatePayment(client)
    .onSuccess { payment -> println("Created: ${payment.id()}") }
    .onFailure { error -> println("Error: ${error.message}") }
```

<Tip>
  Kotlinの `runCatching` を使用して、Resultタイプでより機能的なエラーハンドリングを行います。
</Tip>

## Android統合

Androidアプリケーションと一緒に使用します：

```kotlin theme={null}
import android.app.Application
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.dodopayments.api.client.DodoPaymentsClient
import kotlinx.coroutines.launch

class PaymentViewModel(application: Application) : ViewModel() {
    private val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(BuildConfig.DODO_API_KEY)
        .build()
    
    fun createCheckout(productId: String) {
        viewModelScope.launch {
            try {
                val session = client.async().checkoutSessions().create(params)
                // Open checkout URL in browser or WebView
                openUrl(session.checkoutUrl())
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}
```

## 応答の検証

応答の検証を有効にします：

```kotlin theme={null}
import com.dodopayments.api.core.RequestOptions

// Per-request validation
val product = client.products().retrieve(
    "prod_123",
    RequestOptions.builder()
        .responseValidation(true)
        .build()
)

// Or validate explicitly
val validatedProduct = product.validate()
```

## 高度な機能

### プロキシ設定

プロキシ設定を構成します：

```kotlin theme={null}
import java.net.InetSocketAddress
import java.net.Proxy

val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .proxy(
        Proxy(
            Proxy.Type.HTTP,
            InetSocketAddress("proxy.example.com", 8080)
        )
    )
    .build()
```

### 一時設定

クライアント構成を一時的に変更します：

```kotlin theme={null}
val customClient = client.withOptions {
    it.baseUrl("https://example.com")
    it.maxRetries(5)
}
```

## Ktor統合

Ktorサーバーアプリケーションと統合します：

```kotlin theme={null}
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.configureRouting() {
    val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(environment.config.property("dodo.apiKey").getString())
        .build()
    
    routing {
        post("/create-checkout") {
            try {
                val request = call.receive<CheckoutRequest>()
                val session = client.checkoutSessions().create(params)
                call.respond(mapOf("checkout_url" to session.checkoutUrl()))
            } catch (e: DodoPaymentsServiceException) {
                call.respond(HttpStatusCode.BadRequest, mapOf("error" to e.message))
            }
        }
    }
}
```

## リソース

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-kotlin">
    ソースコードを表示し、貢献する
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    完全なAPIドキュメント
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    サポートを受け、開発者とつながる
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-kotlin/issues">
    バグの報告や機能のリクエスト
  </Card>
</CardGroup>

## サポート

Kotlin SDKのサポートが必要ですか？

* **Discord**: リアルタイムサポートのために[コミュニティサーバー](https://discord.gg/bYqAp4ayYh)に参加
* **Email**: [support@dodopayments.com](mailto:support@dodopayments.com)にご連絡ください
* **GitHub**: [リポジトリ](https://github.com/dodopayments/dodopayments-kotlin)で問題をオープンする

## 貢献

貢献を歓迎します！[貢献ガイドライン](https://github.com/dodopayments/dodopayments-kotlin/blob/main/CONTRIBUTING.md)をチェックして始めましょう。