Een fax verzenden

Vóór het verzenden

Gebruik een afzendernummer dat u bevoegd bent te tonen en stuur de fax naar een ontvanger die uw fax verwacht. Dit verzoek leidt tot een daadwerkelijke verzending waarvoor kosten in rekening kunnen worden gebracht. Gebruik een voorbereid document in PDF- of TIFF-formaat voor de meest voorspelbare paginadetectie. Een antwoord dat de fax in de wachtrij staat, bevestigt de acceptatie, niet de aflevering.

Gebruik een ingeschakeld MultiTEL-account voor de API. Stuur bij een account met een wachtwoord de inloggegevens via HTTP Basic, of bij een account met een token een Bearer-token. Accountrechten en IP-beperkingen blijven van toepassing. Gebruik geen interne inloggegevens van het achtergrondproces.

Het document uploaden

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

Verzoekvelden
Veld	Verplicht	Betekenis
`from_number`	Ja	Uw afzendernummer waarvoor u bevoegd bent. Gebruik de internationale notatie, beginnend met + en de landcode.
`to_number`	Ja	Het faxnummer van de ontvanger in internationale notatie.
`fax_file`	Ja, bij een meerdelig verzoek	Het geüploade document. Laat curl de Content-Type en de scheiding tussen de onderdelen van het meerdelige verzoek instellen.
`webhook_url`	Nee	Optionele URL voor terugmeldingen via HTTP of HTTPS; HTTPS heeft de voorkeur. De inhoud van terugmeldingen en de aflevergaranties worden nog beoordeeld: vraag fax_status periodiek op om de status volgens de gedocumenteerde werkwijze te volgen.

JSON wordt ook geaccepteerd met Content-Type: application/json, dezelfde nummervelden en het optionele veld webhook_url, plus file_name en file_b64. file_b64 bevat de documentbytes, strikt gecodeerd volgens Base64, zonder het voorvoegsel data:. Een geldig fax_file in een meerdelig verzoek heeft voorrang. Dit is geen API om bestanden via een URL op te halen.

Limieten voor documenten en verzendverzoeken

De toepassing accepteert maximaal 15,728,640 gedecodeerde documentbytes (15 MiB), met de extensies pdf, tif, tiff, jpg, jpeg, png, doc, docx of txt. Een toegestane extensie garandeert niet dat de service de pagina's kan tellen of converteren. De infrastructuur kan lagere limieten voor verzoeken hanteren en Base64 vergroot het verzoek.

Per account staat de huidige toepassing één taak in de wachtrij of in verzending naar dezelfde bestemming toe, maximaal vijf verzendverzoeken naar die bestemming in het voorafgaande uur en maximaal 50 verzendverzoeken in totaal in het voorafgaande uur. Een antwoord bij overschrijding van de frequentielimiet gebruikt API-code 429. Wacht voordat u het opnieuw probeert; probeer de limieten niet te omzeilen.

Bewaar de taak-ID

Lees zowel het HTTP-resultaat als status.code in de JSON. Fouten in JSON kunnen worden teruggestuurd met HTTP 200. Een geslaagd JSON-antwoord bevat status en response; de voorbeelden gebruiken fictieve gegevens.

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

Vraag periodiek fax_status op met response.job_id. Als het antwoord op het verzendverzoek verloren gaat, controleer dan de uitgaande berichten in het portaal voordat u opnieuw verzendt: herhaalde verzoeken kunnen afzonderlijke verzendingen aanmaken. Deze verzoekafhandelaar biedt geen idempotentieparameter voor de client.

Fouten en saldocontroles

De API-codes omvatten 400 voor ontbrekende velden, een ongeldige URL voor terugmeldingen, een geweigerd document of mislukte paginadetectie; 401 voor ontbrekende authenticatie; 402 wanneer de geschatte faxkosten plus de geschatte kosten voor taken in de wachtrij of in verzending het beschikbare accountsaldo overschrijden; 429 voor frequentielimieten; en 500 voor een fout bij het voorbereiden van de verzending. Lees status.msg voor de specifieke reden.

De wachtrij legt vóór de verzending een kostenraming vast. Beschouw de acceptatie, de saldocontrole of deze raming niet als bevestiging dat er daadwerkelijk kosten zijn afgeschreven. De definitieve facturering en de details van terugmeldingen moeten nog worden geverifieerd.