API Documentation REST API v2.0

Integra le nostre funzionalità di analisi domini nella tua applicazione

RESTful JSON HTTPS Rate Limited

Introduzione

L'API di Controllo Domini permette di accedere programmaticamente a tutte le funzionalità di analisi domini disponibili sul nostro sito. Puoi verificare DNS, WHOIS, blacklist e servizi cloud direttamente dalla tua applicazione.

Base URL

https://api.controllodomini.it/v2

Caratteristiche principali

  • ✓ Risposte JSON strutturate
  • ✓ Autenticazione tramite API Key
  • ✓ Rate limiting flessibile
  • ✓ Supporto CORS
  • ✓ Endpoint RESTful
  • ✓ HTTPS obbligatorio

Quick Start

cURL 
curl -X GET "https://api.controllodomini.it/v2/dns/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Autenticazione

Tutte le richieste API richiedono autenticazione tramite API Key. Puoi ottenere la tua API Key registrandoti gratuitamente.

Ottenere una API Key

  1. Registrati su controllodomini.it/register
  2. Verifica il tuo indirizzo email
  3. Accedi alla dashboard e genera una nuova API Key
  4. Copia la chiave (verrà mostrata una sola volta)

Utilizzo della API Key

Includi la tua API Key nell'header Authorization di ogni richiesta:

HTTP Header 
Authorization: Bearer YOUR_API_KEY

⚠️ Sicurezza API Key

  • Non condividere mai la tua API Key pubblicamente
  • Non includere la API Key nel codice client-side
  • Usa variabili d'ambiente per memorizzare le chiavi
  • Rigenera la chiave se compromessa

Rate Limits

I rate limits proteggono l'API da un uso eccessivo e garantiscono un servizio equo per tutti gli utenti.

Limiti per piano

Piano Richieste/minuto Richieste/giorno Burst limit
Free 10 1,000 20
Basic 60 10,000 100
Pro 300 50,000 500
Enterprise Custom Custom Custom

Headers di Rate Limit

Ogni risposta include headers che indicano lo stato del rate limit:

Response Headers 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
X-RateLimit-Reset-After: 3600

Endpoints Disponibili

Lista completa degli endpoint API disponibili:

DNS Lookup

GET /dns/{domain}

Recupera tutti i record DNS di un dominio

WHOIS Lookup

GET /whois/{domain}

Ottieni informazioni WHOIS del dominio

Blacklist Check

GET /blacklist/{domain_or_ip}

Verifica presenza in blacklist

Cloud Detection

GET /cloud/{domain}

Identifica servizi cloud utilizzati

Full Analysis

GET /analyze/{domain}

Analisi completa del dominio

Bulk Analysis

POST /bulk/analyze

Analizza multipli domini

DNS Lookup

Recupera tutti i record DNS per un dominio specifico.

Request

GET /dns/{domain}

Parametri

Nome Tipo Richiesto Descrizione
domain string Sì Il dominio da analizzare
types string No Tipi di record da recuperare (comma-separated)

Esempio Request

cURL 
curl -X GET "https://api.controllodomini.it/v2/dns/example.com?types=A,MX,TXT" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

200 OK 
{
  "success": true,
  "domain": "example.com",
  "timestamp": "2024-01-20T10:30:00Z",
  "records": {
    "A": [
      {
        "ip": "93.184.216.34",
        "ttl": 3600,
        "type": "A"
      }
    ],
    "MX": [
      {
        "priority": 10,
        "target": "mail.example.com",
        "ttl": 3600,
        "type": "MX"
      }
    ],
    "TXT": [
      {
        "txt": "v=spf1 include:_spf.example.com ~all",
        "ttl": 3600,
        "type": "TXT"
      }
    ]
  },
  "response_time_ms": 145
}

WHOIS Lookup

Ottieni informazioni complete sulla registrazione del dominio.

Request

GET /whois/{domain}

Esempio Response

200 OK 
{
  "success": true,
  "domain": "example.com",
  "status": "active",
  "registrar": "Example Registrar Inc.",
  "creation_date": "1995-08-14T00:00:00Z",
  "expiry_date": "2025-08-13T00:00:00Z",
  "updated_date": "2024-01-15T00:00:00Z",
  "nameservers": [
    "ns1.example.com",
    "ns2.example.com"
  ],
  "registrant": {
    "name": "REDACTED FOR PRIVACY",
    "organization": "Example Organization",
    "country": "US"
  },
  "domain_status": [
    "clientTransferProhibited",
    "clientUpdateProhibited"
  ]
}

Blacklist Check

Verifica se un dominio o IP è presente in blacklist di spam.

Request

GET /blacklist/{domain_or_ip}

Esempio Response

200 OK 
{
  "success": true,
  "target": "example.com",
  "ips_checked": ["93.184.216.34"],
  "reputation": {
    "score": 98,
    "status": "Excellent",
    "color": "success"
  },
  "blacklists": {
    "checked": 45,
    "listed": 1,
    "issues": [
      {
        "ip": "93.184.216.34",
        "blacklist": "Example RBL",
        "dnsbl": "rbl.example.org",
        "status": "listed",
        "reason": "Spam reports"
      }
    ]
  },
  "checked_at": "2024-01-20T10:30:00Z"
}

Cloud Detection

Identifica quali servizi cloud e CDN utilizza un dominio.

Request

GET /cloud/{domain}

Esempio Response

200 OK 
{
  "success": true,
  "domain": "example.com",
  "detected": [
    {
      "name": "Cloudflare",
      "type": "CDN/Security",
      "confidence": 100,
      "evidence": [
        "NS records point to cloudflare.com",
        "Cloudflare IP ranges detected"
      ]
    },
    {
      "name": "Google Workspace",
      "type": "Email Service",
      "confidence": 100,
      "evidence": [
        "MX records point to google.com",
        "SPF includes _spf.google.com"
      ]
    }
  ],
  "email_services": [
    {
      "provider": "Google Workspace",
      "mx_record": "aspmx.l.google.com",
      "priority": 1
    }
  ],
  "cdn_services": [
    {
      "name": "Cloudflare",
      "details": {
        "ray_id_support": true,
        "anycast": true
      }
    }
  ]
}

Gestione Errori

L'API utilizza codici di stato HTTP standard e restituisce errori in formato JSON.

Formato Errore

Error Response 
{
  "success": false,
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "The provided domain is not valid",
    "details": "Domain contains invalid characters"
  },
  "timestamp": "2024-01-20T10:30:00Z"
}

Codici di Errore Comuni

HTTP Status Error Code Descrizione
400 INVALID_DOMAIN Dominio non valido o malformato
401 UNAUTHORIZED API Key mancante o non valida
403 FORBIDDEN Accesso negato alla risorsa
404 NOT_FOUND Endpoint o risorsa non trovata
429 RATE_LIMITED Troppo richieste, rate limit superato
500 INTERNAL_ERROR Errore interno del server
503 SERVICE_UNAVAILABLE Servizio temporaneamente non disponibile

Esempi di Codice

PHP con cURL

PHP 
<?php
$domain = "example.com";
$apiKey = "YOUR_API_KEY";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.controllodomini.it/v2/dns/{$domain}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Accept: application/json"
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: HTTP {$httpCode}\n";
    echo $response;
}
?>

Python con requests

Python 
import requests

domain = "example.com"
api_key = "YOUR_API_KEY"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Accept": "application/json"
}

response = requests.get(
    f"https://api.controllodomini.it/v2/dns/{domain}",
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: HTTP {response.status_code}")
    print(response.text)

JavaScript con Fetch API

JavaScript 
const domain = 'example.com';
const apiKey = 'YOUR_API_KEY';

fetch(`https://api.controllodomini.it/v2/dns/${domain}`, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Accept': 'application/json'
    }
})
.then(response => {
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
})
.then(data => {
    console.log(data);
})
.catch(error => {
    console.error('Error:', error);
});

Ruby con Net::HTTP

Ruby 
require 'net/http'
require 'json'

domain = 'example.com'
api_key = 'YOUR_API_KEY'

uri = URI("https://api.controllodomini.it/v2/dns/#{domain}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"
request['Accept'] = 'application/json'

response = http.request(request)

if response.code == '200'
  data = JSON.parse(response.body)
  puts data
else
  puts "Error: HTTP #{response.code}"
  puts response.body
end

SDK & Librerie

Librerie ufficiali e community-maintained per vari linguaggi di programmazione.

PHP SDK

Libreria PHP ufficiale con supporto Composer

composer require gtechgroup/controllodomini-php Documentazione →

Python SDK

Package Python con supporto async

pip install controllodomini Documentazione →

Node.js SDK

Client JavaScript/TypeScript per Node.js

npm install @gtechgroup/controllodomini Documentazione →

Ruby Gem

Gem Ruby (Coming Soon)

gem install controllodomini In sviluppo

Changelog API

v2.0.0

20 Gennaio 2024
  • 🚀 Nuova versione major dell'API
  • ✨ Aggiunto endpoint /bulk/analyze per analisi multiple
  • ⚡ Miglioramento performance del 40%
  • 🔧 Standardizzazione delle risposte JSON
  • 📝 Documentazione completamente riscritta

v1.5.0

15 Dicembre 2023
  • ✨ Aggiunto supporto per record CAA
  • 🐛 Fix timeout su domini con molti record
  • 📊 Nuovi campi nella risposta cloud detection

v1.4.0

1 Novembre 2023
  • ✨ Supporto IPv6 completo
  • 🔒 Miglioramenti sicurezza autenticazione
  • 📈 Aumento rate limits per piani Pro

Hai bisogno di aiuto?

Il nostro team di supporto è qui per aiutarti con l'integrazione delle API.

Supporto Email

api@controllodomini.it

GitHub Issues

Segnala problemi

Discord Community

Chat in tempo reale