Wyślij faks | MultiTEL

Przed wysłaniem

Użyj numeru nadawcy, który masz prawo prezentować, i wysyłaj do odbiorcy, który oczekuje Twojego faksu. To żądanie powoduje rzeczywistą transmisję, za którą może zostać naliczona opłata. Aby zapewnić możliwie przewidywalne wykrywanie stron, użyj przygotowanego dokumentu w formacie PDF lub TIFF. Odpowiedź informująca o dodaniu do kolejki potwierdza przyjęcie, a nie doręczenie.

Użyj aktywnego konta API MultiTEL. W przypadku konta z hasłem prześlij dane uwierzytelniające HTTP Basic, a w przypadku konta z tokenem — token Bearer. Uprawnienia konta i ograniczenia adresów IP nadal obowiązują. Nie używaj wewnętrznych danych uwierzytelniających procesu roboczego.

Prześlij dokument

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

Pola żądania
Pole	Wymagane	Znaczenie
`from_number`	Tak	Numer nadawcy, którego masz prawo używać. Zastosuj format międzynarodowy rozpoczynający się od + i numeru kierunkowego kraju.
`to_number`	Tak	Numer faksu odbiorcy w formacie międzynarodowym.
`fax_file`	Tak, dla żądań wieloczęściowych	Przesyłany dokument. Pozwól, aby curl ustawił Content-Type i separator części żądania wieloczęściowego.
`webhook_url`	Nie	Opcjonalny adres URL powiadomień zwrotnych przez HTTP lub HTTPS; zalecany jest HTTPS. Zawartość powiadomień zwrotnych i gwarancje ich doręczenia są nadal weryfikowane: odpytuj fax_status, aby korzystać z udokumentowanej procedury sprawdzania statusu.

Akceptowany jest również JSON z Content-Type: application/json, tymi samymi polami numerów i opcjonalnym webhook_url, a także polami file_name i file_b64. file_b64 zawiera bajty dokumentu zakodowane ściśle zgodnie z Base64, bez prefiksu data:. Prawidłowe pole fax_file w żądaniu wieloczęściowym ma pierwszeństwo. Ten interfejs API nie służy do pobierania plików z adresów URL.

Limity dokumentów i zgłoszeń

Aplikacja akceptuje maksymalnie 15,728,640 bajtów zdekodowanego dokumentu (15 MiB), z rozszerzeniami pdf, tif, tiff, jpg, jpeg, png, doc, docx lub txt. Dozwolone rozszerzenie nie gwarantuje, że usługa potrafi policzyć lub przekonwertować strony. Limity rozmiaru żądań narzucone przez infrastrukturę mogą być niższe, a Base64 zwiększa rozmiar żądania.

Obecnie aplikacja dopuszcza na jednym koncie jedno zadanie do tego samego odbiorcy znajdujące się w kolejce lub w trakcie wysyłania, najwyżej pięć zgłoszeń do tego odbiorcy w ciągu ostatniej godziny oraz najwyżej 50 zgłoszeń łącznie w ciągu ostatniej godziny. Odpowiedź dotycząca przekroczenia limitu częstotliwości używa kodu API 429. Odczekaj przed ponowną próbą; nie próbuj obchodzić limitów.

Zachowaj identyfikator zadania

Sprawdź zarówno wynik HTTP, jak i pole status.code w JSON. Błędy w JSON mogą być zwracane z HTTP 200. Pomyślna odpowiedź JSON zawiera status i response; w przykładach użyto fikcyjnych danych.

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

Odpytuj fax_status przy użyciu response.job_id. Jeśli odpowiedź na żądanie wysłania zostanie utracona, przed ponownym wysłaniem sprawdź skrzynkę nadawczą w portalu: powtórzone żądania mogą powodować osobne transmisje. Ta procedura obsługi nie udostępnia klientowi parametru idempotencji.

Błędy i sprawdzanie salda

Kody API obejmują 400 w przypadku brakujących pól, nieprawidłowego adresu URL powiadomień zwrotnych, odrzuconego dokumentu lub niepowodzenia wykrywania stron; 401 przy braku uwierzytelnienia; 402, gdy szacowany koszt faksu wraz z szacowanymi kosztami zadań w kolejce lub w trakcie wysyłania przekracza dostępne saldo konta; 429 przy przekroczeniu limitów częstotliwości; oraz 500 w przypadku błędu przygotowania do przetwarzania. Dokładną przyczynę odczytaj z status.msg.

Kolejka zapisuje szacowany koszt przed transmisją. Nie traktuj przyjęcia zgłoszenia, sprawdzenia salda ani tego oszacowania jako potwierdzenia pobrania opłaty. Ostateczne szczegóły rozliczeń i powiadomień zwrotnych nadal wymagają weryfikacji.