uChecker API - руководство для разработчиков

curl -X POST https://api.uchecker.net/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your_password"
  }'

{
  "user": {
    "id": 1,
    "email": "you@example.com",
    "telegram_code": 123456
  },
  "api_key": "uk_xxxxxxxxxxxxx",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

{
  "email": "user@example.com"
}

curl -X POST https://api.uchecker.net/api/v1/validate/single \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

import requests
import os

API_KEY = os.environ["UCHECKER_API_KEY"]
BASE = "https://api.uchecker.net"

resp = requests.post(
    f"{BASE}/api/v1/validate/single",
    headers={"x-api-key": API_KEY},
    json={"email": "user@example.com"},
)
data = resp.json()
print(data["task_id"], data["credits_remaining"])

const API_KEY = process.env.UCHECKER_API_KEY;
const BASE = "https://api.uchecker.net";

const res = await fetch(`${BASE}/api/v1/validate/single`, {
  method: "POST",
  headers: {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com" }),
});
const data = await res.json();
console.log(data.task_id, data.credits_remaining);

{
  "success": true,
  "task_id": 123,
  "email": "user@example.com",
  "status": "queued",
  "credits_used": 1,
  "credits_remaining": 999,
  "estimated_completion": "2024-01-01T12:00:30.000Z"
}

curl -X POST https://api.uchecker.net/api/v1/validate/bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alice@company.com",
      "bob@example.org",
      "invalid-email",
      "carol@domain.net"
    ]
  }'

emails = ["alice@company.com", "bob@example.org", "carol@domain.net"]

resp = requests.post(
    f"{BASE}/api/v1/validate/bulk",
    headers={"x-api-key": API_KEY},
    json={"emails": emails},
)
data = resp.json()
print(f"Task {data['task_id']}: {data['valid_emails']} queued, "
      f"{data['invalid_emails']} skipped")

{
  "success": true,
  "task_id": 124,
  "status": "queued",
  "total_emails": 4,
  "valid_emails": 3,
  "invalid_emails": 1,
  "invalid_details": [
    { "email": "invalid-email", "reason": "Invalid email syntax" }
  ],
  "credits_used": 3,
  "credits_remaining": 996,
  "estimated_completion": "2024-01-01T12:01:35.000Z",
  "note": "1 invalid addresses were skipped"
}

curl https://api.uchecker.net/api/v1/tasks/124 \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "task_id": 124,
  "status": "processing",
  "total_emails": 3,
  "processed_emails": 1,
  "progress_percent": 33,
  "created_at": "2024-01-01T12:00:00.000Z",
  "finished_at": null
}

import time

def wait_for_task(task_id, timeout=300, interval=5):
    """Poll task until completed or failed."""
    elapsed = 0
    while elapsed < timeout:
        resp = requests.get(
            f"{BASE}/api/v1/tasks/{task_id}",
            headers={"x-api-key": API_KEY},
        )
        status = resp.json()["status"]
        progress = resp.json()["progress_percent"]
        print(f"Status: {status} ({progress}%)")

        if status == "completed":
            return True
        if status == "failed":
            raise Exception(f"Task {task_id} failed")

        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Task {task_id} timed out")

wait_for_task(124)

async function waitForTask(taskId, timeout = 300_000, interval = 5_000) {
  const start = Date.now();
  while (Date.now() - start < timeout) {
    const res = await fetch(`${BASE}/api/v1/tasks/${taskId}`, {
      headers: { "x-api-key": API_KEY },
    });
    const { status, progress_percent } = await res.json();
    console.log(`Status: ${status} (${progress_percent}%)`);

    if (status === "completed") return true;
    if (status === "failed") throw new Error(`Task ${taskId} failed`);

    await new Promise((r) => setTimeout(r, interval));
  }
  throw new Error(`Task ${taskId} timed out`);
}

await waitForTask(124);

curl "https://api.uchecker.net/api/v1/tasks/124/results?format=json" \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "format": "json",
  "data": [
    {
      "email": "alice@company.com",
      "validation_result": "good"
    },
    {
      "email": "bob@example.org",
      "validation_result": "bad",
      "result": "mailbox_not_found"
    },
    {
      "email": "carol@domain.net",
      "validation_result": "good"
    }
  ]
}

resp = requests.get(
    f"{BASE}/api/v1/tasks/124/results",
    headers={"x-api-key": API_KEY},
    params={"format": "json"},
)
results = resp.json()["data"]

good = [r["email"] for r in results if r["validation_result"] == "good"]
bad = [r["email"] for r in results if r["validation_result"] == "bad"]

print(f"Valid: {len(good)}, Invalid: {len(bad)}")

curl "https://api.uchecker.net/api/v1/tasks/124/download" \
  -H "x-api-key: YOUR_API_KEY" \
  -o results.zip

import zipfile, io

resp = requests.get(
    f"{BASE}/api/v1/tasks/124/download",
    headers={"x-api-key": API_KEY},
)

with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
    good = zf.read("good.txt").decode().splitlines()
    bad = zf.read("bad.txt").decode().splitlines()

print(f"Good: {len(good)}, Bad: {len(bad)}")

curl https://api.uchecker.net/api/v1/account/balance \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "account_id": 123456,
  "credits_remaining": 1000,
  "api_key": "uk_xxxxx..."
}

curl "https://api.uchecker.net/api/v1/tasks?page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "tasks": [
    {
      "task_id": 124,
      "fileName": "bulk_100_emails",
      "status": "completed",
      "created_at": "2024-01-01T12:00:00.000Z",
      "finished_at": "2024-01-01T12:01:35.000Z"
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 10
}

curl "https://api.uchecker.net/api/v1/billing/history?page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": 1,
      "amount": 1000,
      "status": "completed",
      "product_details": "5000 addresses (5k) via freekassa from web",
      "creation_date": "2024-01-01T12:00:00.000Z",
      "payment_id": "uuid-xxx"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}