novauth
TarifsDocumentationCommencer gratuitement
Référence

Référence API

Référence complète de tous les endpoints de vérification Novauth. Chaque canal partage le même modèle d'authentification et la même URL de base — seuls le chemin et la charge utile diffèrent.

BASE URLhttps://api.novauth.com/api/v1/connect-hub

Authentification

Chaque requête doit inclure deux en-têtes. Vous trouverez vos identifiants dans la section Développeur → Clés API du tableau de bord. Les identifiants sont mis en cache côté serveur pendant 5 minutes, les clés nouvellement créées sont donc actives en quelques secondes.

x-api-keyVotre clé API. À traiter comme un mot de passe — ne jamais exposer dans du code côté client.
x-account-idVotre identifiant de compte. Affiché dans le tableau de bord à côté de chaque clé API.
x-request-idID de corrélation optionnel. Transmettez n'importe quel UUID ; retourné dans les réponses d'erreur pour le traçage.

Stockez les identifiants dans des variables d'environnement (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Ne les codez jamais en dur dans les fichiers source.

Les clés préfixées par sk_test_ sont des clés bac à sable — elles ne touchent jamais les opérateurs réels et n'entraînent aucun frais. Utilisez-les pendant le développement, puis remplacez-les par votre clé BTEL_ lors de la mise en production. Mode bac à sable →

Liste blanche d'IP

Lors de la création d'une clé API, vous pouvez éventuellement associer une ou plusieurs adresses IP ou plages CIDR. Si une liste blanche d'IP est configurée, toute requête provenant d'une IP absente de la liste est rejetée avec 401 Unauthorized, même si la clé API elle-même est valide. Cela vous permet de verrouiller une clé sur l'IP de votre serveur afin qu'elle ne puisse pas être utilisée en cas de fuite.

Exemple de requête authentifiée
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"callee": "+14155552671"}'

Verify Call

Initie un appel de courte durée avec sonnerie puis raccroché. L'ID d'appelant encode l'OTP — votre SDK mobile lit le numéro entrant sans que l'utilisateur ait besoin de décrocher.

Envoyer un Verify Call
POST/api/v1/connect-hub/call/flash
Corps de la requête
calleestringobligatoire
Téléphone du destinataire au format E.164 (par ex. +14155552671).
callerstring
ID d'appelant au format E.164. Par défaut, le numéro configuré du compte.
max_ring_timenumber
Durée de sonnerie en secondes avant le raccroché automatique. Par défaut, une valeur aléatoire entre les durées min/max de sonnerie du compte.
Réponse — 200 OK
uuidstring (ULID)
Identifiant unique de l'appel. À conserver — nécessaire pour la consultation du CDR et les rapports webhook.
callerstring
ID d'appelant réellement utilisé (peut différer de la requête si défini par défaut).
calleestring
Numéro du destinataire (echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "callee": "+14155552671",
    "caller": "+38761000001",
    "max_ring_time": 5
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671"
# }
Obtenir le relevé détaillé d'appel
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Réponse — 200 OK
hangup_causestring
Raison de raccroché SIP (par ex. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Durée totale de l'appel en secondes (sonnerie + connecté).
billsecnumber
Durée facturée en secondes (du décroché au raccroché).
pddnumber
Délai post-numérotation en secondes (temps jusqu'à la première sonnerie).
destination_countrystring
Nom du pays de destination résolu.
start_stampstring (ISO 8601)
Horodatage UTC du déclenchement de l'appel.
bash
curl https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671",
#   "hangup_cause": "NORMAL_CLEARING",
#   "duration": 6,
#   "billsec": 0,
#   "pdd": 2,
#   "start_stamp": "2024-06-01T10:30:00.000Z",
#   "destination_country": "United States",
#   "destination_country_code": "US"
# }
Lister les relevés d'appels
POST/api/v1/connect-hub/call/flash/cdr

Retourne une liste paginée de tous les appels de votre compte. Utilisez filter pour affiner les résultats par champ CDR (par ex. callee, hangup_cause).

Corps de la requête
pagenumber
Numéro de page (min : 1, défaut : 1).
rows_per_pagenumber
Enregistrements par page (1–100, défaut : 20).
sort_bystring
Champ de tri (par ex. start_stamp, callee).
sort_direction"ASC" | "DESC"
Ordre de tri.
filterobject
Filtres clé/valeur optionnels appliqués aux champs CDR.
Réponse — 200 OK
totalnumber
Total des enregistrements correspondant au filtre.
total_pagesnumber
Nombre total de pages.
has_next_pageboolean
Indique si une page suivante existe.
has_previous_pageboolean
Indique si une page précédente existe.
listCDR[]
Tableau des relevés détaillés d'appels pour la page en cours.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_by": "start_stamp",
    "sort_direction": "DESC"
  }'
Raccrocher un appel
DELETE/api/v1/connect-hub/call/flash/:uuid

Termine un appel actif avant sa fin naturelle. Retourne 204 No Content en cas de succès.

bash
# Terminate an active call before it naturally ends
curl -X DELETE https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Returns 204 No Content on success

SMS

Achemine un message texte via SMPP. Généralement utilisé pour envoyer un code OTP numérique que l'utilisateur saisit dans votre application.

Envoyer un SMS
POST/api/v1/connect-hub/sms
Corps de la requête
tostringobligatoire
Téléphone du destinataire au format E.164.
textstringobligatoire
Corps du message. Jusqu'à 4 096 caractères ; les messages plus longs sont divisés en parties concaténées.
fromstring
ID expéditeur (alphanumérique ou téléphone). Par défaut, l'expéditeur configuré du compte.
Réponse — 200 OK
messageIdstring (UUID)
Identifiant unique du message. À conserver — nécessaire pour la consultation du SDR et les rapports webhook.
fromstring
ID expéditeur utilisé.
tostring
Numéro du destinataire (echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes.",
    "from": "Novauth"
  }'

# Response:
# {
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "14155552671"
# }
Obtenir le statut du message
GET/api/v1/connect-hub/sms/:messageId/sdr

Récupère le statut de livraison d'un message envoyé. Le statut est mis à jour de manière asynchrone à mesure que les rapports de livraison (DLR) des opérateurs arrivent.

Réponse — valeurs de statut
deliveredLivraison confirmée sur le terminal.
sentTransmis à l'opérateur ; en attente du DLR.
failedÉchec de livraison (numéro invalide, bloqué).
undeliveredAccepté par l'opérateur mais livraison non confirmée.
bash
curl https://api.novauth.com/api/v1/connect-hub/sms/0a62face-6d15-11f0-962f-d89d6729654c/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "...",
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "+14155552671",
#   "status": "delivered",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
Lister les messages
POST/api/v1/connect-hub/sms/sdr

Retourne une liste paginée de tous les messages envoyés. Accepte le même corps de pagination que les autres endpoints de liste (page, rows_per_page, sort_by, filter).

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

OTP Telegram

Envoie un OTP numérique via le Gateway API officiel de Telegram. Prend en charge les vérifications de disponibilité, la validation du code côté serveur et la révocation avec remboursement automatique.

Envoyer un OTP Telegram
POST/api/v1/connect-hub/telegram
Corps de la requête
tostringobligatoire
Téléphone du destinataire au format E.164.
codestringobligatoire
Code OTP à livrer (4–8 chiffres).
ttlnumber
Validité du code en secondes (30–3600). Défaut : 300.
sender_usernamestring
Nom d'utilisateur du canal Telegram vérifié. Omettez pour utiliser le compte par défaut.
callback_urlstring
Substitution de webhook par requête. Le Telegram Gateway enverra des événements de statut directement en POST à cette URL.
Réponse — 200 OK
uuidstring (ULID)
ID de corrélation Novauth. À utiliser pour les rapports webhook.
request_idstring
ID de requête du Telegram Gateway. À utiliser pour les vérifications de statut et la révocation.
statusstring
Statut de livraison normalisé (sent, delivered, …).
request_costnumber
Coût de cette requête en EUR.
remaining_balancenumber
Solde du compte après le débit.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "code": "482910",
    "ttl": 300
  }'

# Response:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "request_id": "tg_req_abc123",
#   "to": "14155552671",
#   "status": "sent",
#   "request_cost": 0.05,
#   "remaining_balance": 49.95
# }
Vérifier la disponibilité
POST/api/v1/connect-hub/telegram/check-send-ability

Sonde si le numéro possède un compte Telegram avant l'envoi. Si is_refunded est true, l'utilisateur n'a pas de compte Telegram — le coût de la sonde est remboursé et vous devriez vous rabattre sur SMS ou Verify Call.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "phone_number": "14155552671",
#   "request_cost": 0.01,
#   "is_refunded": false,
#   "remaining_balance": 49.99,
#   "delivery_status": { "status": "sent", "updated_at": 1713350400 }
# }
Vérifier le statut de vérification
POST/api/v1/connect-hub/telegram/check-verification-status

Interroge le résultat de la saisie du code pour un request_id donné. Transmettez éventuellement le code saisi par l'utilisateur pour la validation côté serveur.

Valeurs de verification_status
code_validL'utilisateur a saisi le bon code.
code_invalidL'utilisateur a saisi un mauvais code.
code_max_attempts_exceededTrop de tentatives échouées.
expiredLe TTL du code a expiré avant la saisie.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_abc123",
    "code": "482910"
  }'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "verification_status": {
#     "status": "code_valid",
#     "updated_at": 1713350400
#   }
# }
Révoquer une vérification
POST/api/v1/connect-hub/telegram/revoke-verification

Annule une requête OTP active avant que l'utilisateur ne la complète. Si le message n'a pas encore été lu, is_refunded sera true et le débit est retourné à votre solde.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_abc123"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "is_refunded": true,
#   "remaining_balance": 50.0
# }
Obtenir le relevé de livraison
GET/api/v1/connect-hub/telegram/:uuid/tdr

Récupère le relevé de livraison Telegram complet pour un uuid donné (l'ID de corrélation Novauth retourné par l'endpoint d'envoi). Inclut le statut de livraison, le statut de vérification, le coût et le pays.

bash
curl https://api.novauth.com/api/v1/connect-hub/telegram/01KNV9CWW9ZEYVDFBJ1N7M1DVR/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response includes full TDR:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "delivery_status": "delivered",
#   "verification_status": "code_valid",
#   "request_cost": 0.05,
#   "country": "United States",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Lister les relevés de livraison
POST/api/v1/connect-hub/telegram/tdr

Retourne une liste paginée de tous les relevés de livraison Telegram. Filtrez par <code>verification_status</code>, <code>delivery_status</code> ou tout autre champ TDR.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

WhatsApp

Envoie un message OTP via l'API WhatsApp Business. L'utilisateur lit le code dans la conversation WhatsApp et le saisit dans votre application.

Envoyer un OTP WhatsApp
POST/api/v1/connect-hub/whatsapp/otp
Corps de la requête
tostringobligatoire
Téléphone du destinataire au format E.164.
textstringobligatoire
Corps du message. Incluez le code OTP et l'indication d'expiration.
Réponse — 200 OK
uuidstring (ULID)
Identifiant unique du message. À conserver — nécessaire pour les rapports webhook.
tostring
Numéro du destinataire (echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/otp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes."
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671"
# }

Après l'envoi, signalez le résultat de vérification de l'utilisateur via POST /whatsapp/webhook. Consultez la référence Webhooks pour plus de détails.

Obtenir le relevé de livraison
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Récupère le relevé de livraison WhatsApp (WDR) pour un uuid donné retourné par l'endpoint d'envoi.

bash
curl https://api.novauth.com/api/v1/connect-hub/whatsapp/01KAK9KATW01A437PSXS5EVDCR/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Lister les relevés de livraison
POST/api/v1/connect-hub/whatsapp/wdr

Retourne une liste paginée de tous les relevés de livraison WhatsApp. Prend en charge le même corps <code>page</code>, <code>rows_per_page</code>, <code>filter</code> que tous les autres endpoints de liste.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Codes d'erreur

Toutes les réponses d'erreur suivent la même enveloppe JSON. Le champ error contient une chaîne lisible par machine ; transmettez votre x-request-id au support lors du signalement de problèmes.

StatutCodeDescription
400BAD_REQUESTCorps de requête invalide — champ obligatoire manquant, mauvais format ou numéro de téléphone invalide.
401UNAUTHORIZEDEn-têtes x-api-key / x-account-id manquants ou invalides.
402PAYMENT_REQUIREDSolde de compte insuffisant. Rechargez votre compte pour continuer.
403FORBIDDENLa clé API existe mais ne dispose pas des permissions pour cette opération.
404NOT_FOUNDL'UUID ou la ressource demandé(e) n'existe pas.
409CONFLICTRequête dupliquée ou état conflictuel (par ex. révocation d'une requête déjà expirée).
480TEMPORARY_UNAVAILABLEPasserelle temporairement inaccessible. Réessayez avec un recul exponentiel.
486BUSY_HERE(Verify Call) Le destinataire est occupé ou l'appel a été rejeté par le réseau.
500INTERNAL_SERVER_ERRORErreur serveur inattendue. Contactez le support avec votre x-request-id.
503SERVICE_UNAVAILABLEPasserelle déconnectée ou service en maintenance. Consultez la page de statut.
603DECLINE(Verify Call) Le destinataire a explicitement refusé l'appel.

Pour une liste complète des codes d'erreur incluant les étapes de remédiation suggérées, consultez le guide de gestion des erreurs.