Quickstart: create an invoice in Kotlin

Key facts

• •Requirements: Kotlin 1.9+, JVM 17+ or Android API 26+
• •No official SDK: `OkHttp` or `Ktor Client`
• •Env var: `System.getenv("SCELL_API_KEY")` (JVM) or BuildConfig (Android)
• •HTTP: OkHttp 4.x (most popular)
• •Expected output: `Map<String, Any>` (Gson) or `JsonObject` (kotlinx)
• •Error codes: `response.isSuccessful` + parse error JSON

Code example

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import com.google.gson.Gson
import java.util.UUID

val JSON = "application/json".toMediaType()
val gson = Gson()
val http = OkHttpClient()
val API_KEY = System.getenv("SCELL_API_KEY")

fun call(path: String, body: Map<String, Any>): Map<String, Any> {
    val req = Request.Builder()
        .url("https://api.scell.io/api/v1$path")
        .header("X-API-Key", API_KEY)
        .header("Idempotency-Key", UUID.randomUUID().toString())
        .post(gson.toJson(body).toRequestBody(JSON)).build()
    http.newCall(req).execute().use { r ->
        val txt = r.body!!.string()
        if (!r.isSuccessful) error("${r.code}: $txt")
        return gson.fromJson(txt, Map::class.java) as Map<String, Any>
    }
}

fun main() {
    val seller = mapOf("siret" to "12345678901234", "name" to "Ma SAS", "vat_number" to "FR12345678901",
        "address" to mapOf("street" to "1 rue Test", "city" to "Paris", "postal_code" to "75001", "country" to "FR"))

    val b2b = call("/invoices", mapOf("format" to "factur-x", "profile" to "EN16931", "currency" to "EUR",
        "seller" to seller,
        "buyer" to mapOf("siret" to "98765432109876", "name" to "Client SARL",
            "address" to mapOf("street" to "2 avenue Demo", "city" to "Lyon", "postal_code" to "69001", "country" to "FR")),
        "lines" to listOf(mapOf("description" to "Prestation conseil", "quantity" to 1, "unit_price" to 1000.0, "vat_rate" to 20.0))))
    println("B2B: ${b2b["id"]} (${b2b["status"]})")

    val b2c = call("/invoices", mapOf("format" to "factur-x", "profile" to "EN16931", "currency" to "EUR",
        "seller" to seller,
        "buyer" to mapOf("buyer_is_individual" to true, "name" to "Jean Dupont", "email" to "jean@example.com",
            "address" to mapOf("street" to "3 bd Client", "city" to "Marseille", "postal_code" to "13001", "country" to "FR")),
        "lines" to listOf(mapOf("description" to "Abonnement", "quantity" to 1, "unit_price" to 49.90, "vat_rate" to 20.0))))
    println("B2C: ${b2c["id"]} (${b2c["status"]})")

    val sig = call("/signatures", mapOf("document_url" to "https://example.com/contrat.pdf",
        "signers" to listOf(mapOf("name" to "Jean Dupont", "email" to "jean@example.com", "phone" to "+33612345678")),
        "signature_options" to mapOf("signature_mode" to "drawn", "timezone" to "Europe/Paris")))
    println("Signature: ${sig["id"]} -> ${sig["signing_url"]}")
}

See also