Démarrage

Envoyez votre premier SMS canadien en moins de 5 minutes.

Démarrage rapide

Créer un compte gratuit — obtenez des clés API live et de test instantanément.
Enregistrez le consentement LCAP pour chaque numéro de téléphone que vous allez contacter.
Provisionnez optionnellement un numéro canadien à code long pour l'envoi.
Envoyez votre premier message via l'API REST.

Authentification

Toutes les requêtes API nécessitent un jeton Bearer dans l'en-tête Authorization. Utilisez test keys (mk_test_...) pour le développement — aucun vrai SMS n'est envoyé, aucuns frais. Utilisez live keys (mk_live_...) pour la production.

⚠️ Ne jamais exposer les clés API dans du code côté client ou dans des dépôts publics.

Numéros de téléphone

Recherchez les numéros canadiens disponibles, provisionnez-en un et utilisez-le comme champ from lors de l'envoi.

bash

curl https://api.honkio.ca/v1/phone-numbers/search?area_codes=416 \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# Provision a number
curl -X POST https://api.honkio.ca/v1/phone-numbers \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14165550100"}'

Consentement LCAP (requis avant l'envoi)

En vertu de la LCAP, vous devez enregistrer le consentement avant d'envoyer un message commercial à tout destinataire. L'API bloquera les envois vers des numéros de téléphone sans consentement valide (HTTP 451).

bash

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+16135550199",
    "consent_type": "express",
    "source_description": "Website opt-in form",
    "source_ip": "203.0.113.1"
  }'

Le consentement exprès n'expire jamais. Le consentement tacite expire après 2 ans conformément à la LCAP §10(9).

Envoi de SMS

Envoyez un message en utilisant un numéro provisionné. L'API valide le numéro de destination canadien, vérifie le consentement LCAP et vérifie la LNNTE avant la livraison.

bash

curl -X POST https://api.honkio.ca/v1/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14165550100",
    "to":   "+16135550199",
    "body": "Hello from HonkIO! 🇨🇦"
  }'

Vérification de numéro de téléphone (OTP)

Utilisez l'API Verify pour confirmer la propriété d'un numéro de téléphone avant d'envoyer des messages commerciaux. Votre utilisateur final reçoit un code à usage unique par SMS; soumettez-le au point de terminaison de vérification pour confirmer.

bash

# Start a verification (sends OTP SMS)
curl -X POST https://api.honkio.ca/v1/verify   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "from": "+14165550100",
    "to":   "+16135550199",
    "code_length": 6,
    "ttl_minutes": 10,
    "app_name": "Acme"
  }'
# Response: { "id": "clxxx...", "status": "pending", "code_length": 6, ... }

# Check the code submitted by your user
curl -X POST https://api.honkio.ca/v1/verify/clxxx.../check   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{ "code": "483721" }'
# Response 200: { "status": "verified", ... }
# Response 422: { "code": "VERIFICATION_INVALID_CODE", "attempts_remaining": 4 }

# Fetch status at any time
curl https://api.honkio.ca/v1/verify/clxxx...   -H "Authorization: Bearer mk_live_YOUR_KEY"

En mode test, le code est toujours composé de zéros pour la longueur choisie (p. ex. 000000 pour 6 chiffres). Aucun SMS n'est envoyé.

Webhooks

Enregistrez un point de terminaison webhook pour recevoir les accusés de réception et les messages entrants. Chaque charge utile est signée avec HMAC-SHA256 — vérifiez l'en-tête X-HonkIO-Signature.

json

{
  "id": "evt_01HXYZ...",
  "type": "message.delivered",
  "created": "2024-01-15T12:00:00Z",
  "account_id": "acc_01HXYZ...",
  "data": {
    "message_id": "msg_01HXYZ...",
    "to": "+16135550199",
    "status": "delivered"
  }
}
// Headers: X-HonkIO-Signature, X-HonkIO-Timestamp, X-HonkIO-Event

Codes d'erreur

HTTP	Code	Signification
401	UNAUTHORIZED	Clé API manquante ou invalide
402	INSUFFICIENT_BALANCE	Solde du compte insuffisant
404	VERIFICATION_NOT_FOUND	Identifiant de vérification introuvable ou non associé à ce compte
409	VERIFICATION_ALREADY_VERIFIED	Ce numéro a déjà été vérifié
410	VERIFICATION_EXPIRED	Le code de vérification a expiré
422	NON_CANADIAN_NUMBER	Numéro E.164 canadien invalide
422	VERIFICATION_INVALID_CODE	Code incorrect — attempts_remaining indique le nombre de tentatives restantes
422	ALLOW_LIST_BLOCKED	Le destinataire ne figure pas sur la liste AUTORISATION de cette clé API
422	DENY_LIST_BLOCKED	Le destinataire figure sur la liste BLOCAGE de cette clé API
429	RATE_LIMITED	Trop de requêtes — veuillez ralentir
429	VERIFICATION_MAX_ATTEMPTS	Trop de tentatives incorrectes — cette vérification est verrouillée
451	OPT_OUT_BLOCKED	Le destinataire a refusé le consentement — envoi bloqué par la loi
451	NO_CONSENT	Pas de consentement LCAP valide en dossier
451	CONSENT_EXPIRED	Consentement tacite expiré (limite LCAP de 2 ans)
451	DNCL_BLOCKED	Numéro sur la LNNTE du CRTC — aucune exemption applicable