API FAX

API fax gratuite pour vos envois de fax

L’API fax que nous avons développée vous permet d’accéder, via votre compte Express Mailing, à une plateforme gratuite vous donnant la possibilité de mettre en place des campagnes de type emailing par fax, des demandes de fax unitaires ou de fax dit transactionnels via l’API.
Nous vous décrivons ici les différentes possibilités à votre disposition grâce à notre API fax ainsi que les moyens de l’intégrer. Enfin, en cas de difficultés techniques relatives à l’utilisation ou à l’intégration de notre API fax, une équipe de développeurs se tient à votre disposition pour vous épauler et vous guider dans vos démarches.

Exemple de push fax par api

Nota : Les balises ou attributs suivants sont optionnels :

• login="demo" password="demo"
• start_date="01/01/2015 15:00:00"
• <fax_config tries="2">
• ref_target="uniq-id-for-report"

Consultez nos exemples de codes API Fax

Comment utiliser notre API fax ?

Notre API Transactionnelle s’articule principalement autour d’un fichier XML (très simple de compréhension) qu’il faut poster en HTTPS ou en HTTP sur nos serveurs. La réponse (elle aussi en XML) fournie un ensemble de références (des id numériques en général) permettant de connaître l’avancement de vos envois.

Le XML doit être posté à l’adresse suivante :

https://api.express-mailing.com/transac/api.ashx (port 443)

Plusieurs méthodes de POST sont possibles :

• POST direct du XML (méthode REST ; présentée dans nos exemples de POST SMS) ;
• POST d’un formulaire du type « application/x-www-form-urlencoded » qui doit contenir entre autre, un <input name="xml" type="text" /> contenant le XML ;
• POST du type « multipart/form-data » contenant un <input name="xml" type="file" />
  Ce dernier type de POST revient à placer un bouton  sur votre page et à sélectionner sur votre disque dur le fichier XML préalablement généré.

Authentification du POST

Lors de l’envoi de votre requête POST vers la page « api.ashx », vous devez systématiquement transmettre vos identifiants de compte fax Express-Mailing.

Pour ce faire, nous proposons 4 méthodes :

• L’authentification HTTP Basic grâce au header HTTP_AUTHORIZATION ;
• Le passage des paramètres login et password dans le « Query String » ;
• Le passage des paramètres login et password comme éléments du POST ;
• Ou l’ajout des attributs login et password dans la racine <request> du XML (solution présentée dans nos exemples de POST fax).

XML de requête

La racine <request> :

Le POST de requête permet de transmettre une ou plusieurs demandes successives à notre API. L’élément racine est <request> avec deux attributs optionnels qui sont login et password pour l’authentification. Chaque nœud enfant constituera une demande auprès de l’API.

L’envoi d’un push fax : <push>

La balise <push> s’ajoute comme nœud enfant de la racine <request>, et introduit une demande de routage fax. Le <push> permet de contrôler le type d’envoi (fax unitaire ou mailing fax) ainsi que la date d’envoi. À l’intérieur du <push> se trouvent divers paramètres optionnels de configuration ainsi que la liste des destinataires fax.

Structure d’un push fax :

Nota : L’attribut ref_target est optionnel mais est fortement recommandé pour identifier chaque envoi de manière unique dans les notifications.

Les attributs de la balise <push>

• media : « fax » permet l’envoi de fax transactionnels.
• type : peut prendre 2 valeurs :
  • « on_demand »On parlera alors d’un envoi fax transactionnel. Tous les envois transactionnels sont stockés dans un groupe qui restera actif pendant 1 semaine.Vous pouvez agréger plusieurs push fax dans un même groupe hebdomadaire en utilisant la même propriété « name ». Le rapport statistique de chaque groupe sera envoyé le dimanche à minuit.
  • « campaign »On parlera ici de campagne marketing. Une campagne peut contenir des milliers de destinataires, mais ne permet pas d’agréger/ajouter de nouveaux destinataires une fois le push créé. En revanche, le rapport statistique sera envoyé aussitôt le dernier « recipient/destinataire » traité (en général dans la journée même).
• name : permet de nommer un envoi ou un ensemble d’envoi (on parlera alors de groupe). Ce nom permet de retrouver facilement vos envois dans notre logiciel fax ou Manager WebFax et d’effectuer des opérations non possibles via l’API (annulation d’un envoi, mise en pause, renvoi d’un rapport, effectuer des relances, etc.).
  Il peut s’agir d’une clé unique dans votre système (une référence de mailing), mais tout simplement du nom d’un client ou d’une étape commerciale (colis livré, livraison retardée, rappel comptable, etc.).Pour les envois fax « on_demand », le paramètre « name » permet de grouper hebdomadairement tous les envois portant le même nom. Le dimanche à minuit, les rapports statistiques de tous les groupes sont envoyés par email puis le ou les push correspondants seront archivés. La semaine suivante si vous continuez d’utiliser le même nom, un nouveau groupe portant ce nom sera alors créé.Attention, un envoi créé en toute fin de mois pourra se retrouver dans les archives statistiques du mois suivant, de même il pourra n’apparaître que sur votre facture du mois suivant.
• start_date : Optionnel ; Si vous omettez ce paramètre, les envois seront placés immédiatement dans notre pool d’envoi fax et seront traités au plus vite (au plus vite signifiant « dans la limite des capacités de notre plateforme fax et de son taux d’utilisation à un instant T »).
  Si elle est fournie, la date doit être au format GMT +01:00 (Fuseau Bruxelles, Copenhague, Madrid, Paris) sous la forme suivante « dd/mm/yyyy hh:nn:ss » (14 chiffres avec les zéros initiaux).
• fax_config : Optionnel ; Permet de définir certains attributs spécifiques au média fax.
  Actuellement le média fax ne dispose que d’une seule configuration particulière :

  
  

  • tries : Optionnel ; Indique le nombre de tentatives à effectuer lorsque le télécopieur ne décroche pas lors de la première tentative ou s’il sonne occupé.Par défaut le nombre de tentatives est 2 (valeurs supportées 1 à 3).
• message : permet de transmettre à l’API le document fax à diffuser sous forme d’une chaîne encodée en BASE64, l’attribut « type » indiquera l’extension du fichier (valeurs supportées « doc », « pdf » ou « tiff »).
  Les documents fax de type « doc » et « pdf » seront convertis par notre plateforme en Noir & Blanc … attention donc aux erreurs typographiques qui pourraient apparaître (fonds gris qui deviennent noirs, polices et petits caractères qui deviennent illisibles, mauvais positionnement des objets, etc.). Veuillez privilégier l’utilisation d’un template fax validé préalablement par notre service commercial.Pour envoyer plusieurs documents dans un push fax, vous devez englober la balise dans une sur-balise comme ceci :

Gestion multi-documents dans une balise <push media="fax">:

• recipients : permet de fournir la liste des fax destinataires du push.Chaque destinataire est ajouté par un élément <add target<. Si la cible est un numéro, celui-ci devra être fourni au format (+33 [espace] numéro).
  Plus généralement le format est [+Indicatif pays] [un espace] [suivi du numéro du destinataire sans le zéro initial].
  Exceptionnellement l’API acceptera le format fax 10 chiffres (01xxxxxxxx) pour des envois vers la France Métropolitaine uniquement.
  L’attribut optionnel ref_target permet de fournir pour chaque destinataire fax une référence unique et personnelle qui sera re-communiquée lors de la récupération des notifications.

Retour du push

Une fois votre push fax déposé en HTTP ou HTTPS sur nos serveurs, l’API vous fournira en retour un XML de confirmation très simple :

Le status= »ok » est l’accusé de réception que devra analyser votre propre système. Si le statut est différent de « ok », nous vous invitons à faire une pause dans votre script de 10 secondes puis de renouveler l’envoi du push sur nos serveurs.

L’analyse en temps réel de vos envois fax se fait ensuite via des notifications (ci-dessous).

Récupération des notifications

La balise <notifications> permet de récupérer les statistiques d’avancement de vos fax. Cette balise comme celle du <push> s’ajoute comme nœud enfant de la racine <request>.

Vous pouvez ajouter une balise <notifications> sans faire de <push> et vice versa, mais vous pouvez également utiliser une balise <notifications> et un <push> dans le même POST.

Les notifications sont fournies dans l’ordre de traitement par nos serveurs. L’ordre peut donc être très différent de celui des contacts fournis dans la balise <recipients>. Chaque notification possède un identificateur séquentiel pour la différencier des autres.

Nota : Les attributs suivants sont optionnels :

• <login="demo" password="demo">
• <seek="id-notification">
• < max="100">

Les attributs de la balise <notifications>

• media : « fax » pour récupérer les notifications de vos push fax.
• seek : optionnel ; S’il n’est pas fourni, le seek fera automatiquement référence à la première notification « non lue ». Sur le principe d’une Pile FIFO, tout élément lu ne réapparaîtra pas dans les lectures suivantes.Toutefois, si votre système de reporting venait à perdre un bloc de notification, seek vous permet de repositionner le pointeur à n’importe quel endroit dans la pile, et ainsi retrouver d’anciennes valeurs. Ce repositionnement permet par exemple de gérer 2 compteurs : un compteur temps réel et un autre compteur de vérification le soir à minuit.Le seek est l’id d’une notification ou « 0 » pour reprendre au tout début (attention les notifications ne sont conservées que 15 jours donc la valeur 0 signifie : reprendre l’analyse maximum 15 jours en arrière).Une fois le curseur repositionné, vous pouvez à nouveau omettre le seek lors des lectures suivantes afin de récupérer bloc par bloc les notifications.
• max : optionnel ; Nombre de notifications à récupérer à chaque appel.

• target : numéro de sms/fax/voice ou adresse email du destinataire.
• ref_target : est en rapport avec le « ref_target » unique passé dans chaque balise <add target>.
  
  ASTUCE : si votre <push> contient des « ref_target » uniques, vous pourrez alors facilement mettre à jour l’état de chacun de vos envois dans votre propre base de données !
• ref_group : est en rapport avec la propriété « name » du push.
• status : (4 valeurs possibles) : PROGRESS, SUCCESS, CANCEL et ERROR
  • SUCCESS correspond à une notification finale indiquant un envoi abouti/délivré
  • ERROR correspond à une notification finale indiquant un échec de l’envoi
  • CANCEL correspond à une notification finale indiquant un envoi non facturé (liste noire, liste anti-publicité, target mal formaté, etc.)
  • PROGRESS est une information temporaire sur l’avancée d’un envoiPar exemple : page 1 sur 5 d’un fax envoyée, page 2 sur 5 d’un fax envoyée, sms déposé chez l’opérateur mobile, numéro occupé, etc.Un envoi peu générer plusieurs notifications PROGRESS, mais donnera systématiquement lieu à une notification SUCCESS ou ERROR à la fin du traitement.

Gestion de votre propre liste rouge fax

La balise <personnal_redlist> permet d’ajouter ou de retirer des numéros de télécopie de votre liste rouge. La liste rouge permet de mémoriser tous les destinataires à qui notre plateforme fax n’enverra plus de communication même si (par erreur) vous ajoutiez ces destinataires dans un push marketing.

Cette balise comme celle du <push> s’ajoute comme nœud enfant de la racine <request>. Vous pouvez ajouter une balise <personnal_redlist> sans faire de <push> et vice versa. Toutefois, si les deux balises sont présentes lors du même appel à l’API, la balise <personnal_redlist> sera traitée avant le <push>.

Les attributs de la balise <personnal_redlist>