{
    "module": "Passerelle SMS B2B (SMS)",
    "base_url": "https://notif.compareb2b.com/public/sms",
    "endpoints": [
        {
            "id": "send",
            "method": "POST",
            "path": "/send.php",
            "title": "Envoi unitaire de SMS sécurisé (LCR / QoS)",
            "summary": "Expédie un SMS sécurisé avec signature HMAC-SHA256, Smart Routing dynamique (LCR au moindre coût ou QoS haute qualité) et bascule automatique Circuit Breaker.",
            "headers": {
                "Content-Type": "application/json",
                "X-SMS-API-KEY": "sms_live_key_acme_2026_x89f2",
                "X-SMS-TIMESTAMP": "1774198200 (Timestamp UNIX actuel, tolérance ±300s)",
                "X-SMS-NONCE": "nonce_aleatoire_unique_16_caracteres",
                "X-SMS-SIGNATURE": "HMAC-SHA256(METHOD\\nPATH\\nTIMESTAMP\\nNONCE\\nSHA256(BODY), SECRET)"
            },
            "payload": {
                "to": {
                    "type": "string",
                    "required": true,
                    "description": "Numéro destinataire au format international E.164 (ex: \"+33612345678\")"
                },
                "from": {
                    "type": "string",
                    "required": false,
                    "description": "Expéditeur alphanumérique personnalisé (jusqu'à 11 caractères, ex: \"MON-ENTREPRISE\")"
                },
                "message": {
                    "type": "string",
                    "required": true,
                    "description": "Corps du texte SMS (encodage GSM-7 ou UCS-2 Unicode géré automatiquement)"
                },
                "routing_strategy": {
                    "type": "string",
                    "required": false,
                    "description": "\"lcr\" (moindre coût, par défaut), \"qos\" (qualité maximale) ou \"balanced\""
                },
                "provider_id": {
                    "type": "integer",
                    "required": false,
                    "description": "ID d'un opérateur spécifique pour forcer son utilisation prioritaire"
                }
            },
            "request_example": {
                "to": "+33612345678",
                "from": "ACME-NOTIF",
                "message": "Votre code d'authentification est : 492019. Valable 10 minutes.",
                "routing_strategy": "lcr"
            },
            "response_success": {
                "success": true,
                "message_uuid": "d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234",
                "status": "sent",
                "recipient": "+33612345678",
                "sender_id": "ACME-NOTIF",
                "segments": 1,
                "encoding": "GSM7",
                "character_count": 64,
                "routing_strategy": "lcr",
                "provider_used": "Twilio Direct API",
                "provider_message_id": "SM_twilio_9981240129",
                "cost_debited": 0.035,
                "currency": "EUR",
                "remaining_balance": 99.965,
                "attempts_count": 1
            },
            "response_error": {
                "success": false,
                "error": "Signature HMAC-SHA256 invalide ou timestamp expiré.",
                "code": 401
            }
        },
        {
            "id": "batch",
            "method": "POST",
            "path": "/batch.php",
            "title": "Envoi groupé de SMS (Bulk)",
            "summary": "Permet d'expédier en lot des SMS personnalisés avec gestion des quotas et débit régulé.",
            "headers": {
                "Content-Type": "application/json",
                "X-SMS-API-KEY": "sms_live_key_acme_2026_x89f2",
                "X-SMS-TIMESTAMP": "1774198200",
                "X-SMS-NONCE": "nonce_aleatoire_unique",
                "X-SMS-SIGNATURE": "HMAC-SHA256 signature"
            },
            "payload": {
                "messages": {
                    "type": "array of objects",
                    "required": true,
                    "description": "Tableau de SMS contenant chacun \"to\", \"message\" et éventuellement \"from\""
                },
                "routing_strategy": {
                    "type": "string",
                    "required": false,
                    "description": "\"lcr\" ou \"qos\""
                }
            },
            "request_example": {
                "messages": [
                    {
                        "to": "+33612345678",
                        "message": "Rappel : Votre rendez-vous de demain à 14h30 est confirmé."
                    },
                    {
                        "to": "+33698765432",
                        "message": "Rappel : Votre rendez-vous de demain à 15h00 est confirmé."
                    }
                ],
                "routing_strategy": "lcr"
            },
            "response_success": {
                "success": true,
                "batch_uuid": "batch_sms_44a19e8",
                "total": 2,
                "accepted": 2,
                "failed": 0,
                "total_cost": 0.07,
                "currency": "EUR",
                "results": [
                    {
                        "to": "+33612345678",
                        "uuid": "msg_1",
                        "status": "sent"
                    },
                    {
                        "to": "+33698765432",
                        "uuid": "msg_2",
                        "status": "sent"
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Solde insuffisant pour expédier ce lot de SMS.",
                "code": 402
            }
        },
        {
            "id": "status",
            "method": "GET",
            "path": "/status.php",
            "title": "Statut & historique de bascule d'un SMS",
            "summary": "Consulte le statut d'acheminement d'un SMS, son statut de remise DLR (DELIVRD, UNDELIV) et l'historique des tentatives de routage.",
            "headers": {
                "X-SMS-API-KEY": "sms_live_key_acme_2026_x89f2",
                "X-SMS-TIMESTAMP": "1774198200",
                "X-SMS-NONCE": "nonce_unique",
                "X-SMS-SIGNATURE": "HMAC-SHA256 signature"
            },
            "payload": {
                "uuid": {
                    "type": "string (query param)",
                    "required": true,
                    "description": "Identifiant UUID du SMS retourné lors de l'envoi"
                }
            },
            "request_example": {
                "query_params": "?uuid=d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234"
            },
            "response_success": {
                "success": true,
                "message_uuid": "d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234",
                "status": "delivered",
                "recipient": "+33612345678",
                "provider_used": "Twilio Direct API",
                "dlr_status": "DELIVRD",
                "dlr_received_at": "2026-09-22 01:18:24",
                "cascade_attempts": [
                    {
                        "attempt": 1,
                        "provider": "Twilio Direct API",
                        "success": true,
                        "latency_ms": 140
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "SMS UUID introuvable.",
                "code": 404
            }
        },
        {
            "id": "balance",
            "method": "GET",
            "path": "/balance.php",
            "title": "Solde de crédits & consommation des quotas",
            "summary": "Retourne le solde financier disponible en temps réel, la devise, les quotas mensuels alloués et le volume consommé.",
            "headers": {
                "X-SMS-API-KEY": "sms_live_key_acme_2026_x89f2",
                "X-SMS-TIMESTAMP": "1774198200",
                "X-SMS-NONCE": "nonce_unique",
                "X-SMS-SIGNATURE": "HMAC-SHA256 signature"
            },
            "payload": {
                "format": {
                    "type": "string (query param)",
                    "required": false,
                    "description": "Optionnel (\"json\")"
                }
            },
            "request_example": {
                "query_params": ""
            },
            "response_success": {
                "success": true,
                "tenant": "Acme Corporation",
                "credit_balance": 99.965,
                "currency": "EUR",
                "monthly_quota_sms": 10000,
                "monthly_consumed_sms": 124,
                "quota_remaining_sms": 9876,
                "rate_limit_per_second": 50
            },
            "response_error": {
                "success": false,
                "error": "Non authentifié.",
                "code": 401
            }
        },
        {
            "id": "webhook_dlr",
            "method": "POST",
            "path": "/webhook_dlr.php",
            "title": "Réception des accusés de remise (DLR)",
            "summary": "Endpoint récepteur des notifications de remise (Delivery Reports) envoyées par les opérateurs SMS (Twilio, Infobip, Vonage) pour mettre à jour l'état final de réception sur le terminal de l'utilisateur.",
            "headers": {
                "Content-Type": "application/x-www-form-urlencoded ou application/json"
            },
            "payload": {
                "MessageSid": {
                    "type": "string",
                    "required": true,
                    "description": "ID externe du message"
                },
                "MessageStatus": {
                    "type": "string",
                    "required": true,
                    "description": "\"delivered\", \"undelivered\", \"failed\""
                }
            },
            "request_example": {
                "MessageSid": "SM_twilio_9981240129",
                "MessageStatus": "delivered"
            },
            "response_success": {
                "success": true,
                "message": "DLR acquitté."
            },
            "response_error": {
                "success": false,
                "error": "Message introuvable pour ce DLR."
            }
        }
    ]
}