Puxh
API des expéditeurs

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.

URL de base fournie par Puxh
https://<your-puxh-api-url>
En-tête sur chaque requête
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ètreTypeDescription
torequisstringPuxh ID du destinataire.
templaterequisstringModèle approuvé pour cet expéditeur : une version (order_shipped.v2) ou le nom seul (order_shipped) pour la dernière version approuvée.
variablesfacultatifobjectValeurs des variables déclarées par le modèle, une entrée par variable.
variables.<nom>facultatifstringValeur d’une variable, en texte, 200 caractères au plus.
expiresInfacultatifintegerPour un modèle otp seulement : durée de validité du code en secondes, de 30 à 3600 (300 par défaut).
lockedfacultatifbooleanMessage 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.
oneViewfacultatifbooleanVue 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êtestring1 à 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ètreTypeDescription
torequisstringPuxh ID du destinataire qui vient de vous répondre, ou de tout destinataire qui vous a accepté avec le badge vert.
textrequisstringTexte du message, 1 à 1000 caractères.
buttonsfacultatifarrayFacultatif : 1 à 3 boutons url, code ou reply, dont un seul reply.
buttons[].idrequisstringIdentifiant du bouton, renvoyé à votre webhook avec chaque réponse.
buttons[].typerequisstringurl ouvre un lien, code copie un code, reply ouvre une réponse envoyée à votre webhook.
buttons[].labelrequisstringLibellé du bouton, 24 caractères au plus, distinct des autres boutons.
buttons[].urlfacultatifstringPour un bouton url : lien https://, 2048 caractères au plus.
buttons[].codefacultatifstringPour un bouton code : texte copié, 1 à 100 caractères.
Idempotency-Keyfacultatif · en-têtestring1 à 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ètreTypeDescription
messageIdrequis · cheminstringIdentifiant 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ètreTypeDescription
torequisstringPuxh 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ètreTypeDescription
namerequisstringNom du modèle : minuscules, chiffres et _, 2 à 48 caractères.
definitionrequisobjectContenu du modèle soumis à la revue.
definition.typerequisstringotp, utility ou info. Un modèle otp n’a que type et language : Puxh fixe son texte.
definition.languagefacultatifstringLangue du modèle : fr, en, es, pt, de, it, nl, ar, zh, ja, ko, hi, ru, tr, sw, pl ; fr par défaut.
definition.textfacultatifstringTexte du message, sauf pour un modèle otp. Une variable s’écrit {orderId} et doit être déclarée.
definition.variablesfacultatifobjectVariables citées dans le texte ou les boutons, une entrée par nom.
definition.variables.<nom>.typerequisstringtext ou number.
definition.variables.<nom>.maxLengthrequisintegerLongueur maximale de la valeur, de 1 à 200 caractères.
definition.notificationModerequisstringsecure, plain ou encrypted. Un modèle otp est toujours en secure.
definition.publicTextfacultatifstringTexte 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.buttonsfacultatifarray1 à 3 boutons, pour un modèle utility ou info. Un modèle otp n’en porte jamais.
definition.buttons[].idrequisstringIdentifiant du bouton, renvoyé à votre webhook avec chaque réponse.
definition.buttons[].typerequisstringurl ouvre un lien, code copie un code, reply ouvre une réponse envoyée à votre webhook.
definition.buttons[].labelrequisstringLibellé du bouton, 24 caractères au plus, distinct des autres boutons.
definition.buttons[].urlfacultatifstringPour un bouton url : lien https://, 2048 caractères au plus ; le chemin peut citer des variables.
definition.buttons[].codefacultatifstringPour 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ètreTypeDescription
templaterequis · cheminstringRé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 facultatif
  • GET /v1/senders — liste les expéditeurs de votre compte
  • GET /v1/senders/{senderId} — lit un expéditeur, son badge et l’état de sa vérification
  • PUT /v1/senders/{senderId}/website — renseigne le site web, figé pendant une revue ou sous un badge
  • POST /v1/senders/{senderId}/verification/email — envoie le code au mail pro du client
  • POST /v1/senders/{senderId}/verification/email/confirm — confirme le code et met le dossier en revue
  • POST /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 fois
  • DELETE /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.

En-tête sur chaque requête
Authorization: Bearer pxa_••••••••
Créer un expéditeur
{
  "name": "Boutique Awa",
  "website": "https://boutique-awa.ci"
}
Expéditeur
{
  "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
}
Vérification par mail pro
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 invalide
  • 401 unauthorized — clé absente, inconnue, révoquée ou IP refusée
  • 402 insufficient_balance — solde épuisé : rechargez depuis l’espace expéditeurs
  • 403 balance_frozen — solde gelé par une suspension ou un remboursement
  • 403 sender_suspended — expéditeur de la clé suspendu
  • 404 sender_not_found — expéditeur de la clé introuvable
  • 404 message_not_found — message inconnu ou envoyé par un autre expéditeur
  • 404 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ête
  • 409 template_in_review — une version de ce modèle est déjà en revue
  • 409 template_name_deleted — nom d’un modèle supprimé : choisissez-en un autre
  • 400 template_link_not_allowed — lien hors des domaines vérifiés de l’expéditeur
  • 403 free_form_not_allowed — aucun message libre possible pour ce destinataire
  • 403 protection_not_allowed — message protégé (locked, oneView) réservé aux badges bleu et vert
  • 422 free_form_refused — message refusé par le contrôle : corrigez-le et renvoyez
  • 503 free_form_review_unavailable — contrôle indisponible : réessayez
  • 429 quota_exceeded — limite de débit ou quota métier atteint
  • 500 / 503 internal — erreur de Puxh ou envois momentanément coupés : réessayez plus tard
4xx / 5xx
{
  "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.

En-têtes reçus
X-Puxh-Delivery: whd_01JABCDEF
X-Puxh-Timestamp: 1793117100
X-Puxh-Signature: v1=<hex-hmac-sha256>
Corps reçu : réponse d’un utilisateur
{
  "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"
}
Corps reçu : décision de revue
{
  "event": "template.reviewed",
  "template": "order_shipped.v1",
  "status": "rejected",
  "reason": "Le texte contient une promotion.",
  "at": "2026-10-29T09:30:00.000Z"
}
Corps reçu : suivi d’un envoi
{
  "event": "message.failed",
  "messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
  "reason": "refused",
  "at": "2026-10-27T16:10:00.000Z"
}
Vérification côté serveur
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