Envoyer un fax | MultiTEL

Avant l’envoi

Utilisez un numéro d’expéditeur que vous êtes autorisé à présenter et adressez votre fax à un destinataire qui l’attend. Cette requête crée une transmission réelle, susceptible d’être facturée. Utilisez un document PDF ou TIFF préparé à l’avance pour une détection des pages aussi prévisible que possible. Une réponse indiquant la mise en file d’attente confirme l’acceptation de la demande, et non la remise du fax.

Utilisez un compte API MultiTEL activé. Transmettez les identifiants d’authentification HTTP Basic pour un compte à mot de passe, ou un jeton Bearer pour un compte à jeton. Les autorisations du compte et les restrictions d’adresses IP restent applicables. N’utilisez pas les identifiants internes des processus de travail.

Téléverser le document

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

Champs de la requête
Champ	Obligatoire	Signification
`from_number`	Oui	Le numéro d’expéditeur que vous êtes autorisé à utiliser. Utilisez le format international commençant par + suivi de l’indicatif du pays.
`to_number`	Oui	Le numéro de fax du destinataire, au format international.
`fax_file`	Oui pour les requêtes en plusieurs parties	Le document téléversé. Laissez curl définir l’en-tête Content-Type et le délimiteur de la requête en plusieurs parties.
`webhook_url`	Non	Adresse de rappel facultative en HTTP ou HTTPS ; privilégiez HTTPS. Le contenu des notifications de rappel et leurs garanties de remise sont encore à l’étude : interrogez périodiquement fax_status pour suivre la procédure documentée de consultation de l’état.

Le format JSON est également accepté avec Content-Type: application/json, les mêmes champs de numéros et le champ facultatif webhook_url, ainsi que file_name et file_b64. file_b64 contient les octets du document encodés strictement en Base64, sans préfixe data:. Un champ fax_file valide fourni dans une requête en plusieurs parties est prioritaire. Cette API ne récupère pas de fichiers à partir de leur adresse.

Limites des documents et des soumissions

L’application accepte au maximum 15,728,640 octets de document après décodage (15 MiB), avec les extensions pdf, tif, tiff, jpg, jpeg, png, doc, docx ou txt. Une extension autorisée ne garantit pas que le service puisse compter ou convertir les pages. Les limites de taille des requêtes imposées par l’infrastructure peuvent être inférieures, et l’encodage Base64 augmente la taille de la requête.

Pour chaque compte, l’application actuelle autorise une seule tâche en attente ou en cours d’envoi vers une même destination, au maximum cinq soumissions vers cette destination au cours de l’heure précédente et au maximum 50 soumissions au total au cours de l’heure précédente. Une réponse de limitation de fréquence utilise le code API 429. Patientez avant de réessayer ; ne tentez pas de contourner les limites.

Conserver l’identifiant de la tâche

Consultez à la fois le résultat HTTP et, dans le contenu JSON, le champ status.code. Des échecs signalés dans le contenu JSON peuvent être accompagnés d’un code HTTP 200. Une réponse JSON réussie contient status et response ; les exemples utilisent des données fictives.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

Interrogez périodiquement fax_status à l’aide de response.job_id. Si la réponse à la demande d’envoi est perdue, consultez la boîte d’envoi du portail avant de renvoyer le fax : des requêtes répétées peuvent créer des transmissions distinctes. Ce gestionnaire n’expose aucun paramètre d’idempotence côté client.

Erreurs et vérifications du solde

Les codes API comprennent 400 en cas de champs manquants, d’adresse de rappel invalide, de document rejeté ou d’échec de détection des pages ; 401 en l’absence d’authentification ; 402 lorsque le coût estimé du fax, ajouté aux estimations des tâches en attente ou en cours d’envoi, dépasse le solde disponible du compte ; 429 pour les limites de fréquence ; et 500 en cas d’échec de préparation du document avant traitement. Consultez status.msg pour connaître la raison précise.

La file d’attente enregistre un coût estimé avant la transmission. Ne considérez ni l’acceptation, ni la vérification du solde, ni cette estimation comme la confirmation qu’une facturation a été effectuée. La facturation finale et les détails des notifications de rappel restent à vérifier.