Documentation développeur

Introduction

SoftAfrik Push est une plateforme SaaS de notifications push destinée au marché africain. Elle prend en charge :

• Android via Firebase Cloud Messaging (FCM) HTTP v1
• iOS via Apple Push Notification Service (APNS)
• Web Push via FCM

Toutes les requêtes API (sauf les URLs de tracking publiques) nécessitent une clé API passée dans le header X-API-Key.

Authentification

Toutes les requêtes API doivent inclure l'en-tête suivant :

Content-Type: application/json
X-API-Key: sk_live_votre_cle_api_ici

Obtenir une clé API

1. Créez un compte sur SoftAfrik Push
2. Connectez-vous au dashboard client ou admin
3. Générez ou copiez votre clé API (64 caractères hexadécimaux)

Sécurité

• La clé est liée à un api_client_id unique
• Le client doit avoir le statut active
• Un client soft-deleted est rejeté

Base URL

https://push.softafrik.com/api/v1

En développement local (Docker) :

http://localhost:8080/api/v1

Formats & Erreurs

Réponse succès (HTTP 200)

{
  "success": true,
  "message": "Push created successfully",
  "data": { ... }
}

Réponse erreur

{
  "success": false,
  "error": "title and message are required",
  "details": { ... }
}

Codes HTTP courants

Quota & Santé API

{
  "success": true,
  "message": "OK",
  "data": {
    "plan": { "code": "pro", "name": "Pro" },
    "limits": {
      "devices": 50000,
      "pushes_per_month": 500000,
      "api_requests_per_minute": 1000
    },
    "current_month": {
      "devices_count": 12,
      "pushes_sent": 340,
      "api_requests": 1200
    },
    "totals": {
      "active_devices": 45,
      "total_pushes": 1280
    }
  }
}

{ "success": true, "message": "OK", "timestamp": "2026-05-02T13:17:50+00:00" }

Devices

{
  "push_token": "dGhpcyBpcyBhIGZha2UgdG9rZW4...",
  "platform": "web",
  "external_user_id": "customer_12345",
  "email": "client@example.com",
  "phone": "+22897417951",
  "country": "TG",
  "language": "fr",
  "device_model": "Chrome Desktop",
  "os_version": "Windows 11",
  "app_version": "1.0.0"
}

{
  "success": true,
  "message": "Device registered",
  "data": { "device_id": 123, "platform": "web", "token_status": "valid" }
}

{
  "success": true,
  "message": "OK",
  "data": {
    "devices": [
      {
        "id": 123,
        "platform": "web",
        "push_token": "dGhpcyBpcyBhIGZha2UgdG9rZW4...",
        "token_status": "valid",
        "external_user_id": "customer_12345",
        "last_active_at": "2026-04-25 14:30:00",
        "created_at": "2026-04-20 10:00:00"
      }
    ],
    "pagination": {
      "total": 45,
      "per_page": 20,
      "current_page": 1,
      "last_page": 3
    }
  }
}

{
  "device_model": "Chrome 124",
  "language": "fr",
  "country": "TG",
  "token_status": "valid"
}

{
  "success": true,
  "message": "Device revoked",
  "data": { "device_id": 123 }
}

Push / Notifications

{
  "title": "Nouvelle promo !",
  "message": "Profitez de -30% sur tous les articles",
  "target_type": "all",
  "image_url": "https://cdn.example.com/banner.jpg",
  "action_url": "https://example.com/promos/summer",
  "custom_data": { "promo_id": 42, "expires": "2026-05-01" }
}

{
  "title": "Commande confirmée",
  "message": "Votre commande #123 a été confirmée.",
  "target_type": "external_user_id",
  "target_value": "customer_12345",
  "action_url": "https://example.com/orders/123",
  "custom_data": { "order_reference": "ORD-123", "type": "order_status" }
}

{
  "title": "Message privé",
  "message": "Un vendeur vous a répondu.",
  "target_type": "device_ids",
  "target_value": [123, 124],
  "action_url": "https://example.com/messages/42"
}

{
  "success": true,
  "message": "Push created successfully",
  "data": {
    "push_id": 128,
    "recipients": 342,
    "status": "queued"
  }
}

{
  "success": true,
  "message": "OK",
  "data": {
    "push_id": 128,
    "title": "Nouvelle promo !",
    "status": "sent",
    "total_recipients": 342,
    "sent_at": "2026-04-25 20:00:00",
    "delivery": {
      "delivered": 320,
      "opened": 89,
      "failed": 22,
      "pending": 0
    }
  }
}

Campagnes

{
  "name": "Campagne Ramadan 2026",
  "title": "Promo Ramadan",
  "message": "Des offres exceptionnelles pendant le mois béni",
  "platform": "android",
  "country": "CI",
  "scheduled_at": "2026-03-01 20:00:00"
}

{
  "success": true,
  "message": "Campaign created",
  "data": {
    "campaign_id": 45,
    "push_id": 129,
    "recipients": 120,
    "status": "active"
  }
}

Tracking

1. Tracking authentifié (backend)

{ "device_id": 123 }

{ "success": true, "message": "Event tracked" }

2. URLs publiques signées (Service Worker)

GET /api/v1/track/open?t=eyJ...&s=abc123

GET /api/v1/track/click?t=eyJ...&s=abc123&redirect=https%3A%2F%2Fexample.com

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  const data = event.notification.data;
  fetch(data.tracking_url_click);
  event.waitUntil(clients.openWindow(data.action_url));
});

Webhooks

SoftAfrik Push peut notifier votre backend à chaque événement important. Configurez votre URL webhook dans le dashboard.

Payload push.delivered

{
  "event": "push.delivered",
  "push_id": 128,
  "device_id": 123,
  "platform": "web",
  "status": "delivered",
  "timestamp": "2026-04-25T20:01:15+00:00"
}

Rate Limits & Quotas

Les limites dépendent de votre plan :

En cas de dépassement, l'API renvoie HTTP 429 avec un message explicite.

Exemples cURL complets

1. Tester l'API (quota)

curl -s -X GET \
  -H "X-API-Key: sk_live_votre_cle_api" \
  "https://push.softafrik.com/api/v1/quota" | jq .

2. Enregistrer un device

curl -s -X POST \
  -H "X-API-Key: sk_live_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "push_token": "dGhpcyBpcyBhIGZha2UgdG9rZW4...",
    "platform": "web",
    "external_user_id": "customer_12345",
    "email": "client@example.com",
    "phone": "+22897417951",
    "country": "TG",
    "language": "fr"
  }' \
  "https://push.softafrik.com/api/v1/devices" | jq .

3. Envoyer un push (tous)

curl -s -X POST \
  -H "X-API-Key: sk_live_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nouvelle promo !",
    "message": "Profitez de -30% sur tous les articles",
    "target_type": "all",
    "image_url": "https://cdn.example.com/banner.jpg",
    "action_url": "https://example.com/promos/summer",
    "custom_data": { "promo_id": 42 }
  }' \
  "https://push.softafrik.com/api/v1/push/send" | jq .

4. Statut d'un push

curl -s -X GET \
  -H "X-API-Key: sk_live_votre_cle_api" \
  "https://push.softafrik.com/api/v1/push/128/status" | jq .

5. Créer une campagne planifiée

curl -s -X POST \
  -H "X-API-Key: sk_live_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campagne Ramadan 2026",
    "title": "Promo Ramadan",
    "message": "Des offres exceptionnelles",
    "platform": "android",
    "country": "CI",
    "scheduled_at": "2026-03-01 20:00:00"
  }' \
  "https://push.softafrik.com/api/v1/campaigns" | jq .

6. Révoquer un device

curl -s -X DELETE \
  -H "X-API-Key: sk_live_votre_cle_api" \
  "https://push.softafrik.com/api/v1/devices/123" | jq .

Exemple d'intégration PHP

<?php
class SoftAfrikPushClient {
    private string $apiKey;
    private string $baseUrl = 'https://push.softafrik.com/api/v1';

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

    private function request(string $method, string $endpoint, array $data = null): array {
        $ch = curl_init($this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-API-Key: ' . $this->apiKey
        ]);
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        if ($method === 'POST') curl_setopt($ch, CURLOPT_POST, true);
        if ($method === 'PUT') curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
        if ($method === 'DELETE') curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
        $response = curl_exec($ch);
        curl_close($ch);
        return json_decode($response, true) ?? [];
    }

    public function registerDevice(array $device): array {
        return $this->request('POST', '/devices', $device);
    }

    public function sendPush(array $push): array {
        return $this->request('POST', '/push/send', $push);
    }

    public function getQuota(): array {
        return $this->request('GET', '/quota');
    }
}

// Utilisation
$client = new SoftAfrikPushClient('sk_live_votre_cle_api');
$client->registerDevice([
    'push_token' => 'token_ici',
    'platform' => 'web',
    'external_user_id' => 'user_123'
]);
$client->sendPush([
    'title' => 'Bienvenue !',
    'message' => 'Merci de nous avoir rejoint.',
    'target_type' => 'all'
]);
?>

Service Worker (Web Push)

Exemple de firebase-messaging-sw.js pour recevoir les notifications Web Push :

importScripts('https://www.gstatic.com/firebasejs/10.0.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.0.0/firebase-messaging-compat.js');

firebase.initializeApp({
  apiKey: "YOUR_FIREBASE_API_KEY",
  projectId: "your-project-id",
  messagingSenderId: "123456789"
});

const messaging = firebase.messaging();

messaging.onBackgroundMessage(function(payload) {
  const notificationTitle = payload.notification.title;
  const notificationOptions = {
    body: payload.notification.body,
    icon: '/icon.png',
    data: payload.data
  };
  self.registration.showNotification(notificationTitle, notificationOptions);
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  const data = event.notification.data;
  if (data && data.tracking_url_click) {
    fetch(data.tracking_url_click);
  }
  event.waitUntil(clients.openWindow(data.action_url || '/'));
});