Документация7 мин чтения

Примеры подключения: cURL, Node.js, Web и PHP

В статье приведён минимальный рабочий запрос для каждого из пяти распространённых окружений интеграции. Каждый пример отправляет GET-запрос к эндпоинту /validate и читает поле status из ответа. Формат запроса и ответа описан в статье «Справочник API».

cURL

Команда отправляет запрос с использованием ключа API, сохранённого в переменной окружения.

curl -H "X-API-Key: $CLEANCONTACT_KEY" \
  "https://api.cleancontact.ru/validate?email=someone@example.com"

Node.js (JavaScript)

В примере используется функция fetch, встроенная в Node.js версии 18 и выше. Дополнительный пакет не требуется. Ключ считывается из переменной окружения и не появляется в исходном коде.

const API_KEY = process.env.CLEANCONTACT_KEY

async function validateEmail(email) {
  const params = new URLSearchParams({ email })
  const response = await fetch(`https://api.cleancontact.ru/validate?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json()
}

validateEmail('someone@example.com')
  .then((data) => console.log(data.result.status))

Node.js (TypeScript)

Тот же запрос с явными типами для формы ответа. Поле status ограничено тремя значениями, которые возвращает эндпоинт.

const API_KEY = process.env.CLEANCONTACT_KEY as string

type ValidationStatus = 'Good' | 'Bad' | 'Unknown'

interface ValidationResult {
  value: string
  result: {
    status: ValidationStatus
    detail: string
  }
}

async function validateEmail(email: string): Promise<ValidationResult> {
  const params = new URLSearchParams({ email })
  const response = await fetch(`https://api.cleancontact.ru/validate?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json() as Promise<ValidationResult>
}

validateEmail('someone@example.com')
  .then((data) => console.log(data.result.status))

Web (JavaScript)

Запрос, отправляемый напрямую из браузера, требует ключ публичного типа, защищённый капчей, как описано в статье «Аутентификация и ключи API». Серверный ключ не должен появляться в коде браузера. Значение captchaToken в примере получено от виджета капчи до отправки запроса.

const params = new URLSearchParams({ email, captchaToken })

fetch(`https://api.cleancontact.ru/validate?${params}`, {
  headers: { 'X-API-Key': 'your-public-key' }
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data.result.status)
  })

PHP

В примере используется расширение cURL, входящее в стандартную установку PHP. Синтаксис PHP требует точку с запятой в конце каждой инструкции, поэтому в коде ниже она сохранена.

<?php

$apiKey = getenv('CLEANCONTACT_KEY');
$email = 'someone@example.com';
$url = 'https://api.cleancontact.ru/validate?' . http_build_query(['email' => $email]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['result']['status'];

Обработка ошибок в примерах опущена для краткости. Реальная интеграция должна проверять код состояния HTTP и обрабатывать ответы 400, 401 и 429, описанные в статье «Справочник API».