Aller au contenu principal

Suivre vos SMS

ZimSend vous permet de suivre en temps réel l'état de vos SMS et de consulter l'historique complet de vos envois.

Obtenir le statut d'un SMS​

Récupérez les informations détaillées sur un SMS spécifique.

Endpoint​

GET https://api.zimsend.com/v1/sms/status/:message_id

Paramètres d'URL​

ParamètreTypeDescription
message_idstringID du message retourné lors de l'envoi

Exemple de requête​

curl -X GET https://api.zimsend.com/v1/sms/status/msg_1234567890abcdef \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Réponse​

{
"success": true,
"message_id": "msg_1234567890abcdef",
"status": "delivered",
"to": "+33612345678",
"message": "Bonjour, votre commande est en cours de livraison",
"priority": "normal",
"created_at": "2025-01-15T10:30:00Z",
"queued_at": "2025-01-15T10:30:01Z",
"sent_at": "2025-01-15T10:30:05Z",
"delivered_at": "2025-01-15T10:30:08Z",
"metadata": {
"order_id": "order_12345",
"user_id": "user_789"
}
}

Statuts possibles​

Un SMS peut avoir les statuts suivants :

StatutDescription
queuedLe SMS est en file d'attente
sentLe SMS a été envoyé au réseau mobile
deliveredLe SMS a été délivré au destinataire
failedL'envoi du SMS a échoué
cancelledLe SMS a été annulé avant l'envoi

Cycle de vie d'un SMS​

queued → sent → delivered
↓ ↓
cancelled failed

Consulter l'historique des SMS​

Récupérez la liste de tous vos SMS envoyés avec des filtres avancés.

Endpoint​

GET https://api.zimsend.com/v1/sms/history

Paramètres de requête​

ParamètreTypeDescription
pagenumberNuméro de page (défaut: 1)
limitnumberNombre de résultats par page (défaut: 50, max: 100)
statusstringFiltrer par statut (queued, sent, delivered, failed)
tostringFiltrer par numéro de destinataire
from_datestringDate de début (format ISO 8601)
to_datestringDate de fin (format ISO 8601)
device_idstringFiltrer par device
searchstringRecherche dans le contenu des messages

Exemple de requête​

curl -X GET "https://api.zimsend.com/v1/sms/history?status=delivered&limit=20" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Réponse​

{
"success": true,
"data": [
{
"message_id": "msg_1234567890abcdef",
"status": "delivered",
"to": "+33612345678",
"message": "Bonjour, votre commande est en cours de livraison",
"sent_at": "2025-01-15T10:30:05Z",
"delivered_at": "2025-01-15T10:30:08Z"
},
{
"message_id": "msg_abcdef1234567890",
"status": "delivered",
"to": "+33698765432",
"message": "Votre colis sera livré demain",
"sent_at": "2025-01-15T09:15:22Z",
"delivered_at": "2025-01-15T09:15:25Z"
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total_pages": 5,
"total_items": 94
}
}

Exemples de filtres​

Filtrer par période​

Récupérez les SMS envoyés durant une période spécifique :

curl -X GET "https://api.zimsend.com/v1/sms/history?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Filtrer par statut​

Récupérez uniquement les SMS échoués :

curl -X GET "https://api.zimsend.com/v1/sms/history?status=failed" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Filtrer par destinataire​

Récupérez tous les SMS envoyés à un numéro spécifique :

curl -X GET "https://api.zimsend.com/v1/sms/history?to=%2B33612345678" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Recherche dans le contenu​

Recherchez des SMS contenant un mot-clé :

curl -X GET "https://api.zimsend.com/v1/sms/history?search=commande" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Annuler un SMS programmé​

Si vous avez programmé un SMS pour un envoi futur, vous pouvez l'annuler avant son envoi.

Endpoint​

DELETE https://api.zimsend.com/v1/sms/:message_id

Exemple de requête​

curl -X DELETE https://api.zimsend.com/v1/sms/msg_1234567890abcdef \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Réponse​

{
"success": true,
"message": "SMS annulé avec succès",
"message_id": "msg_1234567890abcdef",
"status": "cancelled"
}

Note : Vous ne pouvez annuler que les SMS avec le statut queued. Les SMS déjà envoyés ne peuvent pas être annulés.

Obtenir les statistiques globales​

Obtenez un aperçu de vos statistiques d'envoi.

Endpoint​

GET https://api.zimsend.com/v1/sms/stats

Paramètres de requête​

ParamètreTypeDescription
from_datestringDate de début (format ISO 8601)
to_datestringDate de fin (format ISO 8601)
device_idstringFiltrer par device

Exemple de requête​

curl -X GET "https://api.zimsend.com/v1/sms/stats?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z" \
-H "X-API-Key: votre_cle_api" \
-H "X-Client-ID: votre_client_id"

Réponse​

{
"success": true,
"period": {
"from": "2025-01-01T00:00:00Z",
"to": "2025-01-31T23:59:59Z"
},
"stats": {
"total_sent": 1250,
"delivered": 1198,
"failed": 52,
"pending": 15,
"delivery_rate": 95.84,
"by_day": [
{
"date": "2025-01-01",
"sent": 45,
"delivered": 43,
"failed": 2
},
{
"date": "2025-01-02",
"sent": 52,
"delivered": 50,
"failed": 2
}
]
}
}

Exemples d'intégration​

Node.js / JavaScript​

const axios = require('axios');

class ZimSendTracking {
constructor(apiKey, clientId) {
this.apiKey = apiKey;
this.clientId = clientId;
this.baseURL = 'https://api.zimsend.com/v1';
}

async getStatus(messageId) {
try {
const response = await axios.get(
`${this.baseURL}/sms/status/${messageId}`,
{
headers: {
'X-API-Key': this.apiKey,
'X-Client-ID': this.clientId
}
}
);
return response.data;
} catch (error) {
throw error.response.data;
}
}

async getHistory(filters = {}) {
try {
const response = await axios.get(
`${this.baseURL}/sms/history`,
{
params: filters,
headers: {
'X-API-Key': this.apiKey,
'X-Client-ID': this.clientId
}
}
);
return response.data;
} catch (error) {
throw error.response.data;
}
}

async cancelMessage(messageId) {
try {
const response = await axios.delete(
`${this.baseURL}/sms/${messageId}`,
{
headers: {
'X-API-Key': this.apiKey,
'X-Client-ID': this.clientId
}
}
);
return response.data;
} catch (error) {
throw error.response.data;
}
}

async getStats(fromDate, toDate) {
try {
const response = await axios.get(
`${this.baseURL}/sms/stats`,
{
params: {
from_date: fromDate,
to_date: toDate
},
headers: {
'X-API-Key': this.apiKey,
'X-Client-ID': this.clientId
}
}
);
return response.data;
} catch (error) {
throw error.response.data;
}
}
}

// Utilisation
const tracking = new ZimSendTracking(
process.env.ZIMSEND_API_KEY,
process.env.ZIMSEND_CLIENT_ID
);

// Vérifier le statut d'un SMS
tracking.getStatus('msg_1234567890abcdef')
.then(status => {
console.log('Statut:', status.status);
console.log('Délivré à:', status.delivered_at);
})
.catch(error => console.error('Erreur:', error));

// Récupérer l'historique
tracking.getHistory({
status: 'delivered',
limit: 50,
page: 1
})
.then(history => {
console.log('SMS envoyés:', history.data.length);
console.log('Total:', history.pagination.total_items);
})
.catch(error => console.error('Erreur:', error));

// Annuler un SMS programmé
tracking.cancelMessage('msg_1234567890abcdef')
.then(result => console.log('SMS annulé:', result))
.catch(error => console.error('Erreur:', error));

// Obtenir les statistiques
tracking.getStats('2025-01-01T00:00:00Z', '2025-01-31T23:59:59Z')
.then(stats => {
console.log('Total envoyés:', stats.stats.total_sent);
console.log('Taux de délivrance:', stats.stats.delivery_rate + '%');
})
.catch(error => console.error('Erreur:', error));

Python​

import requests
from typing import Dict, Optional

class ZimSendTracking:
def __init__(self, api_key: str, client_id: str):
self.api_key = api_key
self.client_id = client_id
self.base_url = 'https://api.zimsend.com/v1'

def _get_headers(self) -> Dict[str, str]:
return {
'X-API-Key': self.api_key,
'X-Client-ID': self.client_id
}

def get_status(self, message_id: str) -> Dict:
"""Obtient le statut d'un SMS"""
url = f'{self.base_url}/sms/status/{message_id}'
response = requests.get(url, headers=self._get_headers())
return response.json()

def get_history(self, filters: Optional[Dict] = None) -> Dict:
"""Récupère l'historique des SMS"""
url = f'{self.base_url}/sms/history'
response = requests.get(url, params=filters, headers=self._get_headers())
return response.json()

def cancel_message(self, message_id: str) -> Dict:
"""Annule un SMS programmé"""
url = f'{self.base_url}/sms/{message_id}'
response = requests.delete(url, headers=self._get_headers())
return response.json()

def get_stats(self, from_date: str, to_date: str) -> Dict:
"""Obtient les statistiques d'envoi"""
url = f'{self.base_url}/sms/stats'
params = {
'from_date': from_date,
'to_date': to_date
}
response = requests.get(url, params=params, headers=self._get_headers())
return response.json()

# Utilisation
import os

tracking = ZimSendTracking(
os.getenv('ZIMSEND_API_KEY'),
os.getenv('ZIMSEND_CLIENT_ID')
)

# Vérifier le statut
status = tracking.get_status('msg_1234567890abcdef')
print(f"Statut: {status['status']}")
print(f"Délivré à: {status.get('delivered_at')}")

# Récupérer l'historique
history = tracking.get_history({
'status': 'delivered',
'limit': 50,
'page': 1
})
print(f"SMS envoyés: {len(history['data'])}")
print(f"Total: {history['pagination']['total_items']}")

# Obtenir les statistiques
stats = tracking.get_stats('2025-01-01T00:00:00Z', '2025-01-31T23:59:59Z')
print(f"Total envoyés: {stats['stats']['total_sent']}")
print(f"Taux de délivrance: {stats['stats']['delivery_rate']}%")

PHP​

<?php

class ZimSendTracking {
private $apiKey;
private $clientId;
private $baseURL = 'https://api.zimsend.com/v1';

public function __construct($apiKey, $clientId) {
$this->apiKey = $apiKey;
$this->clientId = $clientId;
}

private function getHeaders() {
return [
'X-API-Key: ' . $this->apiKey,
'X-Client-ID: ' . $this->clientId
];
}

public function getStatus($messageId) {
$url = $this->baseURL . '/sms/status/' . $messageId;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $this->getHeaders());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

return json_decode($response, true);
}

public function getHistory($filters = []) {
$url = $this->baseURL . '/sms/history';

if (!empty($filters)) {
$url .= '?' . http_build_query($filters);
}

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $this->getHeaders());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

return json_decode($response, true);
}

public function cancelMessage($messageId) {
$url = $this->baseURL . '/sms/' . $messageId;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, $this->getHeaders());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

return json_decode($response, true);
}

public function getStats($fromDate, $toDate) {
$url = $this->baseURL . '/sms/stats';
$url .= '?' . http_build_query([
'from_date' => $fromDate,
'to_date' => $toDate
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $this->getHeaders());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

return json_decode($response, true);
}
}

// Utilisation
$tracking = new ZimSendTracking(
getenv('ZIMSEND_API_KEY'),
getenv('ZIMSEND_CLIENT_ID')
);

// Vérifier le statut
$status = $tracking->getStatus('msg_1234567890abcdef');
echo "Statut: " . $status['status'] . "\n";

// Récupérer l'historique
$history = $tracking->getHistory([
'status' => 'delivered',
'limit' => 50
]);
echo "Total: " . $history['pagination']['total_items'] . "\n";

// Obtenir les statistiques
$stats = $tracking->getStats('2025-01-01T00:00:00Z', '2025-01-31T23:59:59Z');
echo "Total envoyés: " . $stats['stats']['total_sent'] . "\n";
?>

Prochaines étapes​