# Tugas dan kesalahan

Periksa tugas, unduh buku kerjanya, dan tangani kegagalan permintaan.

Dokumentasi resmi: https://img2excel.net/id/docs/api/jobs

`GET /api/v1/jobs/{job_id}`

Endpoint sinkron langsung mengembalikan hasil selesai. Gunakan endpoint tugas untuk proses asinkron, memeriksa pengulangan idempoten yang tertunda, atau memperbarui URL selama hasil masih disimpan. Kegagalan sinkron mengembalikan `422` beserta tugas; pemeriksaan tugas yang ada tetap mengembalikan `200`. Selalu periksa `status`.

Periksa status konversi saat ini. Gambar ke Excel dan Tulisan tangan ke Excel memakai endpoint yang sama.

## Permintaan

| Parameter | Lokasi | Wajib | Keterangan |
| --- | --- | --- | --- |
| `job_id` | Jalur | Ya | `id` yang diterima saat tugas dibuat. |
| `Authorization` | Header | Ya | `Bearer $IMG2EXCEL_API_KEY`. Kunci harus milik akun yang membuat tugas. |

```bash
curl --fail-with-body https://img2excel.net/api/v1/jobs/job_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY"
```

Permintaan valid mengembalikan **200 OK**, meskipun konversi gagal. Periksa JSON `status`: keberhasilan HTTP bukan berarti buku kerja sudah siap.

## Status tugas

| Status | Arti | Langkah berikutnya |
| --- | --- | --- |
| `queued` | Unggahan diterima dan menunggu eksekusi. | Periksa lagi setelah 2–3 detik. |
| `processing` | Konversi sedang berjalan. | Periksa lagi setelah 2–3 detik. |
| `succeeded` | Buku kerja siap. | Unduh file melalui `result.download_url`, lalu hentikan polling. |
| `failed` | Konversi gagal. | Baca `error.code` dan `error.message`, lalu hentikan polling. |
| `expired` | Masa penyimpanan hasil berakhir. | Hentikan polling. Buat tugas dengan kunci idempotensi baru jika diperlukan. |

## Respons

### Konversi berhasil

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-09-07T12:00:00.000Z",
  "completed_at": "2026-09-07T12:00:18.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}

```

URL di atas hanya contoh. Gunakan URL yang dikembalikan oleh tugas Anda.

| Kolom | Tipe | Keterangan |
| --- | --- | --- |
| `id` | String | ID tugas. |
| `type` | String | `image-to-excel` atau `handwriting-to-excel`. |
| `status` | String | Salah satu dari lima status di atas. |
| `credits_reserved` | Bilangan bulat | Kredit yang diperlukan untuk konversi. |
| `credits_used` | Bilangan bulat | Kredit yang digunakan oleh konversi. |
| `created_at` | String | Waktu UTC dalam format ISO 8601. |
| `completed_at` | String atau null | Waktu selesai; sebelumnya `null`. |
| `result` | Objek | Tersedia jika tugas berhasil dan hasil dapat diakses. |
| `error` | Objek | Tersedia saat konversi gagal; berisi `code` dan `message`. |

### Kolom hasil

| Kolom | Tipe | Keterangan |
| --- | --- | --- |
| `filename` | String | Nama file buku kerja yang disarankan. |
| `content_type` | String | Tipe MIME XLSX. |
| `size_bytes` | Bilangan bulat atau null | Ukuran file dalam byte; `null` jika tidak tersedia. |
| `download_url` | String | URL unduhan bertanda tangan yang bersifat sementara. |
| `download_url_expires_in` | Bilangan bulat | Masa berlaku URL dalam detik: `900` (15 menit). |

Hasil tersedia selama 24 jam setelah selesai. Jika URL kedaluwarsa dalam periode tersebut, ambil kembali tugas untuk memperoleh URL baru. Jangan mencatat atau membagikan URL bertanda tangan secara publik.

### Konversi gagal

Kegagalan dilaporkan dalam respons tugas, misalnya:

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "failed",
  "credits_reserved": 1,
  "credits_used": 0,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:18.000Z",
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "The conversion could not be completed."
  }
}
```

Konversi yang gagal tidak menggunakan kredit. Periksa pesan sebelum mengulang. Konversi baru membutuhkan kunci idempotensi baru; kunci lama mengembalikan tugas gagal yang sama.

## Polling dan unduh

Instal `requests` dengan `pip install requests`, atur `IMG2EXCEL_API_KEY`, dan ganti `job_id` dengan ID tugas Anda. Contoh ini melakukan maksimal 60 pemeriksaan. Kesalahan HTTP atau jaringan menghentikan skrip; tangani kegagalan sementara di produksi sesuai petunjuk berikut.

```python
import os
import time
import requests

job_id = "job_0123456789abcdef0123456789abcdef"
headers = {"Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}"}

for _ in range(60):
    response = requests.get(
        f"https://img2excel.net/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()

    if job["status"] == "succeeded":
        xlsx = requests.get(job["result"]["download_url"], timeout=60)
        xlsx.raise_for_status()
        with open(job["result"]["filename"], "wb") as output:
            output.write(xlsx.content)
        break
    if job["status"] in ("failed", "expired"):
        raise RuntimeError(job.get("error", {"code": job["status"]}))

    time.sleep(2)
else:
    raise TimeoutError("IMG2Excel conversion did not finish in time")

```

## Kesalahan permintaan

Permintaan HTTP yang ditolak mengembalikan status selain 2xx dan objek kesalahan:

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "A valid API key is required."
  }
}
```

| Status HTTP | Kode | Penyebab | Penanganan |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | Isi tidak dapat dibaca sebagai formulir multipart. | Gunakan fitur unggah multipart pada klien HTTP. |
| 400 | `INVALID_FILE` | `file` tidak ada atau bukan file. | Lampirkan gambar pada kolom `file`. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Kunci lebih dari 200 karakter. | Pendekkan nilai header. |
| 401 | `INVALID_API_KEY` | Kunci tidak ada, tidak valid, kedaluwarsa, dicabut, atau tanpa izin konversi. | Periksa Bearer dan kunci di [pengaturan API](https://img2excel.net/id/settings/api). |
| 403 | `API_ACCESS_REQUIRED` | Akun tidak memiliki akses API. | Beli paket Business atau Professional. |
| 404 | `JOB_NOT_FOUND` | Tugas tidak ada atau milik akun lain. | Periksa ID dan gunakan kunci akun pembuat tugas. |
| 409 | `JOB_CONFLICT` | Konflik mencegah pembuatan tugas. | Ulangi dengan kunci idempotensi awal. |
| 413 | `FILE_TOO_LARGE` | File melebihi 4 MB. | Perkecil gambar sebelum mengunggah. |
| 429 | `RATE_LIMITED` | Terlalu banyak tugas baru dalam satu menit terakhir. | Tunggu sesuai `Retry-After`, lalu ulangi dengan kunci yang sama. |
| 429 | `CONCURRENCY_LIMITED` | Terlalu banyak tugas mengantre atau diproses. | Tunggu tugas berjalan selesai sebelum mengirim lagi. |

Kredit tidak cukup atau kegagalan pengenalan dapat terjadi **setelah** tugas diterima. Pemeriksaan mengembalikan `status: "failed"`, `error.code`, dan `error.message`, tanpa selalu menolak unggahan awal. Periksa saldo jika pesan menyebut kredit tidak cukup.

## Batas dan pengulangan

| Batas | Nilai |
| --- | --- |
| Tugas baru per akun | 30 per menit, gabungan kedua endpoint konversi |
| Tugas mengantre atau diproses bersamaan | Business: 3; Professional: 10 |
| Ukuran file | Maksimal 4 MB |
| Masa berlaku URL unduhan | 15 menit |
| Penyimpanan hasil | 24 jam setelah konversi berhasil |

Untuk `429`, ikuti `Retry-After` jika ada. Untuk kegagalan sementara `5xx` atau jaringan, tambah jeda secara bertahap dengan penundaan acak. Gunakan kunci awal untuk mengulang unggahan dan ID yang sama untuk memeriksa status. Tetapkan batas waktu keseluruhan polling di aplikasi.

Jangan otomatis mengulang permintaan tidak valid atau kesalahan autentikasi. Perbaiki permintaan terlebih dahulu. Jika masalah berlanjut, hubungi [dukungan](mailto:support@img2excel.net) dengan ID tugas dan kode kesalahan, tanpa kunci API atau URL unduhan.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Dokumentasi API lengkap: https://img2excel.net/id/docs/api/text/llms-full.txt