Documentation de l'API HAMBOOK

Intégrez vos logiciels radioamateurs avec le carnet de trafic hambook.site

Authentification et Sécurité

Pour travailler avec l'API, vous avez besoin d'une clé API personnelle (API Key). Toutes les requêtes API doivent être exécutées dans le contexte d'un utilisateur spécifique.

Comment obtenir votre clé API :
  1. Connectez-vous à votre Espace personnel sur le portail hambook.site.
  2. Allez dans l'onglet 'Paramètres' et trouvez la section 'Clés API'.
  3. Indiquez le nom de votre application et cliquez sur 'Générer la clé'.
Format de la requête HTTP

La transmission des données QSO se fait via une requête POST standard. La clé d'autorisation doit être transmise dans l'en-tête HTTP ou comme paramètre GET.

Method POST (Form-Data или JSON)
Endpoint URL https://hambook.site/api/v1/qso/
Auth Header X-Hambook-Key: [your_api_key]
Alternative GET Auth https://hambook.site/api/v1/qso/?key=[your_api_key]

Paramètres de requête acceptés

Les données doivent être soumises au format application/x-www-form-urlencoded (requête POST classique).

Parameter Type Required Description / Example
call string YES Indicatif du correspondant (sera automatiquement converti en majuscules).
Example: W1AW, R3TJL/3
my_call string No Votre indicatif (station). Si vide, l'indicatif principal de l'utilisateur sera utilisé automatiquement.
Example: UB3TLU
band string No Bande de fréquence au format ADIF (sera automatiquement convertie en majuscules).
Example: 20m, 40m, 2m (или вычисляется автоматически по freq)
mode string No Type de modulation (mode) au format ADIF.
Example: CW, SSB, FT8
submode string No Sous-mode de modulation (pour FT4, PSK31, etc.).
Example: FT4, USB, LSB
freq float No Fréquence exacte du QSO en MHz.
Example: 14.074 (MHz)
qso_date string No Date du QSO au format AAAAMMJJ. Si vide, la date actuelle sera utilisée.
Example: 20260623 (YYYYMMDD)
time_on string No Heure de début du QSO au format HHMM (en UTC). Si vide, l'heure actuelle sera utilisée.
Example: 1753 или 175300 (HHMM / HHMMSS, UTC)
rst_sent string No Rapport RST envoyé.
Example: 599, -12 (Default: 59)
rst_rcvd string No Rapport RST reçu.
Example: 59, -08 (Default: 59)
gridsquare string No Localisateur d'antenne (Grid) du correspondant.
Example: FN31, LO26ah (автоматически рассчитывает координаты для карты!)
my_gridsquare string No Votre localisateur d'antenne (Grid) pendant le QSO.
Example: LO26mg
qth string No Ville/localisation du correspondant.
Example: Nizhny Novgorod
name string No Nom du correspondant.
Example: John
comment string No Commentaire personnalisé pour le QSO.
Example: QRP 5W, dipole

Formats des réponses du serveur (JSON)

L'API hambook.site renvoie toujours une réponse au format JSON avec un statut HTTP 200, même en cas d'erreurs.

Enregistré avec succès 
{
  "status": "success",
  "id": 1430955,
  "confirmed": true
}
confirmed: true означает мгновенное встречное подтверждение (CFM)!
Doublon détecté (ignoré) 
{
  "status": "success",
  "message": "Duplicate ignored",
  "id": 1430954
}
Erreur d'authentification 
{
  "status": "error",
  "message": "Invalid API Key"
}

Exemples d'intégration de code

<?php
$ch = curl_init('https://hambook.site/api/v1/qso/');
$data = [
    'call'       => 'W1AW',
    'band'       => '20m',
    'freq'       => 14.074,
    'mode'       => 'FT8',
    'rst_sent'   => '-10',
    'rst_rcvd'   => '-05',
    'gridsquare' => 'FN31pr',
    'comment'    => 'Logged via Hambook API v5'
];

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Hambook-Key: YOUR_API_KEY_HERE'
]);

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

$result = json_decode($response, true);
print_r($result);
?>
import requests

url = 'https://hambook.site/api/v1/qso/'
headers = {
    'X-Hambook-Key': 'YOUR_API_KEY_HERE'
}
data = {
    'call': 'W1AW',
    'band': '20m',
    'freq': 14.074,
    'mode': 'FT8',
    'rst_sent': '-10',
    'rst_rcvd': '-05',
    'gridsquare': 'FN31pr',
    'comment': 'Logged via Python API'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
curl -X POST https://hambook.site/api/v1/qso/ \
  -H "Content-Type: application/json" \
  -H "X-Hambook-Key: YOUR_API_KEY_HERE" \
  -d '{
    "call": "W1AW",
    "band": "20m",
    "freq": 14.074,
    "mode": "FT8",
    "rst_sent": "-10",
    "rst_rcvd": "-05",
    "gridsquare": "FN31pr"
  }'