Documentation API

Premiers Pas

L'API FineSpeak est organisée autour de REST. Notre API possède des URL orientées ressources prévisibles, accepte des corps de requête encodés JSON, renvoie des réponses encodées JSON et utilise des codes de réponse HTTP et une authentification standard.

URL de Base

https://api.finespeak.net/v1

SDK Libraries

PHP

composer require finespeak/sdk

Node.js

npm install finespeak

Python

pip install finespeak

Authentification

L'API FineSpeak utilise des clés API pour authentifier les requêtes. Vous pouvez consulter et gérer vos clés API dans le tableau de bord.

Authentification par Clé API

Incluez votre clé API dans l'en-tête Authorization :

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Gardez vos clés API sécurisées! Ne partagez pas vos clés API secrètes dans des zones accessibles publiquement comme GitHub, le code côté client, etc.

Numéros de Téléphone

Lister les Numéros Disponibles

Recherchez des numéros de téléphone disponibles à l'achat.

GET /numbers/available

curl https://api.finespeak.net/v1/numbers/available?country=US&area_code=415 \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Acheter un Numéro

Achetez un numéro de téléphone pour votre compte.

POST /numbers/purchase

curl -X POST https://api.finespeak.net/v1/numbers/purchase \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Ligne d'Assistance"
  }'
                    

Lister Vos Numéros

Récupérez une liste des numéros de téléphone appartenant à votre compte.

GET /numbers

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Appels

Passer un Appel

Initiez un appel sortant.

POST /calls

curl -X POST https://api.finespeak.net/v1/calls \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "callback_url": "https://votredomaine.com/call-status"
  }'
                    

Récupérer les Détails de l'Appel

Obtenez des informations sur un appel spécifique.

GET /calls/{call_id}

curl https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Terminer un Appel

Mettez fin à un appel actif.

DELETE /calls/{call_id}

curl -X DELETE https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Messagerie

Envoyer un SMS

Envoyez un message SMS.

POST /messages

curl -X POST https://api.finespeak.net/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "body": "Hello from FineSpeak!"
  }'
                    

Lister les Messages

Récupérez l'historique des messages.

GET /messages

curl https://api.finespeak.net/v1/messages?limit=50 \
  -H "Authorization: Bearer VOTRE_CLE_API"
                    

Webhooks

FineSpeak utilise des webhooks pour notifier votre application lorsque des événements se produisent dans votre compte. Les webhooks sont particulièrement utiles pour les événements asynchrones comme les appels et messages entrants.

Événements Webhook

call.initiated - Un appel a été initié
call.answered - Un appel a été répondu
call.completed - Un appel s'est terminé
message.received - Un message SMS a été reçu
message.delivered - Un message SMS a été livré

Exemple de Charge Utile Webhook

{
  "event": "message.received",
  "timestamp": "2025-12-04T10:30:00Z",
  "data": {
    "message_id": "SM123456789",
    "from": "+14155555678",
    "to": "+14155551234",
    "body": "Hello!",
    "status": "received"
  }
}
                    

Codes d'Erreur

FineSpeak utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec d'une requête API.

Code	Description
`200`	OK - La requête a réussi
`201`	Créé - Ressource créée avec succès
`400`	Mauvaise Requête - Paramètres de requête invalides
`401`	Non Autorisé - Clé API invalide
`403`	Interdit - Autorisations insuffisantes
`404`	Non Trouvé - La ressource n'existe pas
`429`	Trop de Requêtes - Limite de débit dépassée
`500`	Erreur Interne du Serveur - Quelque chose s'est mal passé de notre côté

Format de Réponse d'Erreur

{
  "error": {
    "code": "invalid_request",
    "message": "The 'to' parameter is required",
    "param": "to"
  }
}
                    

Navigation Rapide