Envoyez des messages attendus, avec un contrat clair.
API HTTP en JSON : chaque expéditeur s’authentifie par clé, les champs inconnus sont refusés et les codes d’erreur sont stables.
Rien n’est envoyé depuis cette page : copiez la requête et exécutez-la depuis votre serveur, avec votre clé dans la variable PUXH_API_KEY.
Authentification
Créez une clé dans l’espace expéditeurs et envoyez-la comme jeton Bearer. Une clé appartient à un seul expéditeur et peut être limitée à des adresses IP.
La clé n’est affichée qu’une fois : gardez-la côté serveur et révoquez-la si elle fuit.
https://<your-puxh-api-url>Authorization: Bearer pxh_••••••••POST/v1/messages
Envoyer un message
Le destinataire est désigné par son Puxh ID, le modèle doit être approuvé et les variables le remplissent. Une clé d’idempotence protège les nouvelles tentatives pendant 24 heures.
Le texte public n’est pas confidentiel
Le champ publicText peut s’afficher dans une notification lue par Google ou Apple. Il peut citer les variables du texte du modèle : leurs valeurs y apparaissent alors en clair, n’y mettez ni code ni donnée personnelle. Le reste du message est chiffré.
| Paramètre | Type | Description |
|---|---|---|
torequis | string | Puxh ID du destinataire. |
templaterequis | string | Modèle approuvé pour cet expéditeur : une version (order_shipped.v2) ou le nom seul (order_shipped) pour la dernière version approuvée. |
variablesfacultatif | object | Valeurs des variables déclarées par le modèle, une entrée par variable. |
variables.<nom>facultatif | string | Valeur d’une variable, en texte, 200 caractères au plus. |
expiresInfacultatif | integer | Pour un modèle otp seulement : durée de validité du code en secondes, de 30 à 3600 (300 par défaut). |
lockedfacultatif | boolean | Message protégé : le destinataire l’affiche par Face ID, empreinte, code du téléphone ou code PIN Puxh, et il se recache à la fermeture. Notification « Vous avez reçu un message protégé », sans contenu. Badge bleu ou vert ; refusé pour un modèle otp. |
oneViewfacultatif | boolean | Vue unique : comme locked, mais le message est supprimé après sa première lecture. Badge bleu ou vert ; refusé pour un modèle otp. |
Idempotency-Keyfacultatif · en-tête | string | 1 à 255 caractères ; la même clé renvoie la première réponse pendant 24 h. |
POST/v1/messages/free-form
Envoyer un message libre
Après une réponse d’un destinataire par un bouton reply, vous pouvez lui envoyer un seul message libre dans les 24 heures, sans modèle : un texte et jusqu’à trois boutons. Avec le badge vert, vous pouvez en envoyer à tout destinataire qui vous a accepté.
| Paramètre | Type | Description |
|---|---|---|
torequis | string | Puxh ID du destinataire qui vient de vous répondre, ou de tout destinataire qui vous a accepté avec le badge vert. |
textrequis | string | Texte du message, 1 à 1000 caractères. |
buttonsfacultatif | array | Facultatif : 1 à 3 boutons url, code ou reply, dont un seul reply. |
buttons[].idrequis | string | Identifiant du bouton, renvoyé à votre webhook avec chaque réponse. |
buttons[].typerequis | string | url ouvre un lien, code copie un code, reply ouvre une réponse envoyée à votre webhook. |
buttons[].labelrequis | string | Libellé du bouton, 24 caractères au plus, distinct des autres boutons. |
buttons[].urlfacultatif | string | Pour un bouton url : lien https://, 2048 caractères au plus. |
buttons[].codefacultatif | string | Pour un bouton code : texte copié, 1 à 100 caractères. |
Idempotency-Keyfacultatif · en-tête | string | 1 à 255 caractères ; la même clé renvoie la première réponse pendant 24 h. |
GET/v1/messages/{messageId}
Suivre un message
Renvoie le statut d’un envoi, sans son contenu.
| Paramètre | Type | Description |
|---|---|---|
messageIdrequis · chemin | string | Identifiant renvoyé par l’envoi. |
POST/v1/approval-requests
Demander une autorisation sans message
Crée une demande d’autorisation avec un code court, sans texte libre.
| Paramètre | Type | Description |
|---|---|---|
torequis | string | Puxh ID de la personne à qui demander l’autorisation. |
POST/v1/templates
Soumettre un modèle
Le modèle passe en revue et ne sert à l’envoi qu’une fois approuvé (référence order_shipped.v1). La décision arrive avec template.reviewed.
| Paramètre | Type | Description |
|---|---|---|
namerequis | string | Nom du modèle : minuscules, chiffres et _, 2 à 48 caractères. |
definitionrequis | object | Contenu du modèle soumis à la revue. |
definition.typerequis | string | otp, utility ou info. Un modèle otp n’a que type et language : Puxh fixe son texte. |
definition.languagefacultatif | string | Langue du modèle : fr, en, es, pt, de, it, nl, ar, zh, ja, ko, hi, ru, tr, sw, pl ; fr par défaut. |
definition.textfacultatif | string | Texte du message, sauf pour un modèle otp. Une variable s’écrit {orderId} et doit être déclarée. |
definition.variablesfacultatif | object | Variables citées dans le texte ou les boutons, une entrée par nom. |
definition.variables.<nom>.typerequis | string | text ou number. |
definition.variables.<nom>.maxLengthrequis | integer | Longueur maximale de la valeur, de 1 à 200 caractères. |
definition.notificationModerequis | string | secure, plain ou encrypted. Un modèle otp est toujours en secure. |
definition.publicTextfacultatif | string | Texte de la notification, obligatoire en mode plain, sans donnée personnelle. Il ne cite que des variables déclarées du modèle, remplies à l’envoi. |
definition.buttonsfacultatif | array | 1 à 3 boutons, pour un modèle utility ou info. Un modèle otp n’en porte jamais. |
definition.buttons[].idrequis | string | Identifiant du bouton, renvoyé à votre webhook avec chaque réponse. |
definition.buttons[].typerequis | string | url ouvre un lien, code copie un code, reply ouvre une réponse envoyée à votre webhook. |
definition.buttons[].labelrequis | string | Libellé du bouton, 24 caractères au plus, distinct des autres boutons. |
definition.buttons[].urlfacultatif | string | Pour un bouton url : lien https://, 2048 caractères au plus ; le chemin peut citer des variables. |
definition.buttons[].codefacultatif | string | Pour un bouton code : texte copié, 1 à 100 caractères. |
GET/v1/templates/{template}
Lire un modèle
Renvoie une version d’un modèle avec son état de revue et, en cas de refus, le motif.
| Paramètre | Type | Description |
|---|---|---|
templaterequis · chemin | string | Référence de la version, comme dans l’envoi : le nom, puis .v et le numéro (order_shipped.v1). |
GET/v1/balance
Lire le solde
Renvoie le solde du compte : credits, debt et frozen. Les recharges se font dans l’espace expéditeurs.
Aucun paramètre : la clé d’API suffit.
API de compte
Avec une clé de compte (pxa_…), créez les expéditeurs de vos clients, faites-les vérifier et créez leurs clés d’envoi. Une clé de compte n’envoie aucun message.
POST /v1/senders— crée un expéditeur au badge d’alerte, avec son site web facultatifGET /v1/senders— liste les expéditeurs de votre compteGET /v1/senders/{senderId}— lit un expéditeur, son badge et l’état de sa vérificationPUT /v1/senders/{senderId}/website— renseigne le site web, figé pendant une revue ou sous un badgePOST /v1/senders/{senderId}/verification/email— envoie le code au mail pro du clientPOST /v1/senders/{senderId}/verification/email/confirm— confirme le code et met le dossier en revuePOST /v1/senders/{senderId}/verification/documents— dépose le type de personne, son nom et les documents (pièce d’identité ou d’entreprise) ; le TXT du domaine est contrôléPOST /v1/senders/{senderId}/api-keys— crée une clé d’envoi pxh_, affichée une seule foisDELETE /v1/senders/{senderId}/api-keys/{keyId}— révoque une clé de cet expéditeur
Le badge bleu ou vert exige le site web de l’expéditeur : code envoyé au mail pro de votre client pour le bleu ; pour le vert, pièce d’identité ou document d’entreprise, et enregistrement TXT « puxh-verification= » suivi de l’identifiant de l’expéditeur, à la racine du domaine du site.
Les règles de l’espace expéditeurs s’appliquent et vos expéditeurs partagent votre solde.
Authorization: Bearer pxa_••••••••{
"name": "Boutique Awa",
"website": "https://boutique-awa.ci"
}{
"senderId": "snd_8kq2",
"pushId": "BOUAWA3F",
"name": "Boutique Awa",
"website": "https://boutique-awa.ci",
"badge": "alert",
"status": "active",
"verification": "pro_email",
"verificationStatus": "in_review",
"rejectionReason": null
}POST /v1/senders/snd_8kq2/verification/email
{ "email": "awa@boutique-awa.ci" }
→ 200 { "challengeId": "…", "expiresAt": …, "retryAt": … }
POST /v1/senders/snd_8kq2/verification/email/confirm
{ "challengeId": "…", "code": "012345" }
→ 200 { "status": "in_review", "domain": "boutique-awa.ci" }Erreurs stables
Une erreur porte un code, un message et, pour la validation, la liste errors, chaque message précédé de son champ (template: …). Branchez votre logique sur code.
400 invalid_request— corps ou paramètre invalide401 unauthorized— clé absente, inconnue, révoquée ou IP refusée402 insufficient_balance— solde épuisé : rechargez depuis l’espace expéditeurs403 balance_frozen— solde gelé par une suspension ou un remboursement403 sender_suspended— expéditeur de la clé suspendu404 sender_not_found— expéditeur de la clé introuvable404 message_not_found— message inconnu ou envoyé par un autre expéditeur404 template_not_found— version de modèle inconnue de l’expéditeur de la clé409 idempotency_key_reused— même clé réutilisée pour une autre requête409 template_in_review— une version de ce modèle est déjà en revue409 template_name_deleted— nom d’un modèle supprimé : choisissez-en un autre400 template_link_not_allowed— lien hors des domaines vérifiés de l’expéditeur403 free_form_not_allowed— aucun message libre possible pour ce destinataire403 protection_not_allowed— message protégé (locked, oneView) réservé aux badges bleu et vert422 free_form_refused— message refusé par le contrôle : corrigez-le et renvoyez503 free_form_review_unavailable— contrôle indisponible : réessayez429 quota_exceeded— limite de débit ou quota métier atteint500 / 503 internal— erreur de Puxh ou envois momentanément coupés : réessayez plus tard
{
"code": "invalid_request",
"message": "template is unknown or not approved for this sender",
"errors": [
"template: unknown or not approved for this sender"
]
}Vérifier les webhooks
Puxh envoie à votre URL HTTPS les réponses de vos destinataires, le suivi de vos envois et les décisions de revue. Vérifiez la signature HMAC-SHA256 (horodatage, un point, puis le corps brut).
Un bouton reply envoie message.reply avec messageId, l’identifiant du bouton (button) et le texte saisi (text).
Une réponse ouvre un message libre pendant 24 heures (voir « Envoyer un message libre »).
La décision sur un modèle arrive avec template.reviewed, et le motif en cas de refus.
Après queued, vous recevez message.sent quand le message est déposé, puis message.delivered quand un premier appareil l’a récupéré, ou message.failed avec reason (expired, refused ou withdrawn).
Événements : message.reply, message.sent, message.delivered, message.failed, template.reviewed et puxh.test (bouton « Tester »).
Avec une clé publique ECDH P-256, le corps est chiffré (epk, iv, ct) : déchiffrez-le sur votre serveur après avoir vérifié la signature.
Répondez en 2xx en moins de 10 secondes, sinon Puxh retente jusqu’à 6 heures. Dédupliquez avec X-Puxh-Delivery.
X-Puxh-Delivery: whd_01JABCDEF
X-Puxh-Timestamp: 1793117100
X-Puxh-Signature: v1=<hex-hmac-sha256>{
"event": "message.reply",
"messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
"button": "question",
"text": "Puis-je changer l’adresse de livraison ?",
"at": "2026-10-27T16:05:00.000Z"
}{
"event": "template.reviewed",
"template": "order_shipped.v1",
"status": "rejected",
"reason": "Le texte contient une promotion.",
"at": "2026-10-29T09:30:00.000Z"
}{
"event": "message.failed",
"messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
"reason": "refused",
"at": "2026-10-27T16:10:00.000Z"
}expected = HMAC_SHA256(secret, timestamp + "." + rawBody)
accept only if signature == "v1=" + hex(expected)
reject if abs(now - timestamp) > 300 seconds
ignore an already processed X-Puxh-Delivery
Puxh