Webdienst-API
Mit der Webdienst-API von GFI FaxMaker können Sie Ihre eigenen Anwendungen entwickeln, die sich mit GFI FaxMaker verbinden und Faxe versenden und empfangen können.
HINWEIS
Dieses Thema gilt für Benutzer, die mit Visual Studio, XML Web Services und SOAP-Technologien vertraut sind.
Anforderungen und wichtige Hinweise
- Verwenden Sie zur Erstellung der API eine Entwicklungsumgebung, die XML Web Services und SOAP unterstützt.
- Die Webdienst-API von GFI FaxMaker nutzt für die HTTPHypertext Transfer Protocol-Kommunikation zwischen der Anwendung und GFI FaxMaker Port 8555. Dieser Port kann automatisch über den Konfigurationsassistenten von GFI FaxMaker geöffnet werden. Weitere Informationen finden Sie unter Webdienst-API-Port.
- Greifen Sie über XML-Webservices und den HTTP-Port 8555 auf den GFI FaxMaker-Webdienst zu, indem Sie die folgende URLBei der „Uniform Resource Locator“ (URL) handelt es sich um die Adresse einer Seite im World Wide Web. verwenden:
http://<GFI FaxMaker-Server>:8555/faxmaker/wsapi
Ersetzen Sie<GFI FaxMaker-Server>durch den Namen oder die IP-Adresse des GFI FaxMaker-Servers. Beispiel:http://myfaxserver.mydomain.local:8555/faxmaker/wsapi. - Alternativ können Sie eine sichere HTTPS-Verbindung nutzen. Weitere Informationen finden Sie unter Verwenden der Webdienst-API über eine sichere HTTPS-Verbindung.
- Registrieren Sie im Knoten Lizenzierte Benutzer die Benutzer, welche die Webdienst-API verwenden werden. Verwenden Sie die Anmeldeinformationen dieser Benutzer in API-Anrufen. Weitere Informationen finden Sie unter Webdienst-API-Benutzer.
- Empfangene Faxe, die an Benutzer geschickt werden, die für die Webdienst-API registriert sind, werden in der Webdienst-API-Warteschlange gespeichert und nicht per E-Mail an den Benutzer weitergeleitet. Konfigurieren Sie RoutingDie von GFI FaxMaker verwendeten Methoden, um zu bestimmen, wie Faxe an interne Empfänger weitergeleitet werden sollen.-Regeln, um Faxe umzuleiten, die von der Webdienst-API an die registrierten Benutzer übertragen werden sollen. Weitere Informationen finden Sie unter Faxrouting.
- GFI FaxMaker speichert empfangene Faxe für 30 Tage in der Warteschlange der Webdienst-API. Abgelaufene Faxe können nicht von der Webdienst-API abgerufen werden. Weitere Informationen finden Sie unter Verwalten der Webdienst-API-Warteschlange.
Erste Schritte
Erstellen Sie in Visual Studio eine C#-Windows- oder Konsolenanwendung, und fügen Sie in Solution Explorer einen Web- oder Dienstverweis hinzu (abhängig von der Visual Studio-Version).
Wenn Sie zur Eingabe der Dienst-URL aufgefordert werden, geben Sie den GFI FaxMaker-Webdienst-URL-WSDL-Link ein. Dieser setzt sich zusammen aus der GFI FaxMaker-Webdienst-URL, wie oben im Abschnitt „Anforderungen“ definiert, und dem Zusatz ?singleWsdl. Beispiel: http://meinfaxserver.meinedomaene.com:8555/faxmaker/wsapi?singleWsdl
Wenn Sie zur Eingabe des Namespace- oder eine Webverweisnamens aufgefordert werden, geben Sie FMWSAPI ein.
Öffnen Sie nach dem Erstellen der Anwendung die Datei app.config. Suchen Sie nach der Adresse http://127.0.0.1:8555/faxmaker/wsapi, und ersetzen Sie sie durch den Wert Ihrer GFI FaxMaker-Webdienst-URL. Beispiel: http://meinfaxserver.meinedomaene.com:8555/faxmaker/wsapi
Speichern Sie die Änderungen, und verwenden Sie im Weiteren die folgenden Namespace-Klassen als typische C#-Klassen.
API-Funktionen
SendFax
Verwenden Sie diese Funktion zum Senden eines Faxes. Diese Funktion gibt ein Array aus FaxJobIDs zurück. Für jeden Empfänger wird eine FaxJobID erstellt. Diese ID gibt die Möglichkeit, den Status des gesendeten Faxes an den jeweiligen Empfänger zu überwachen.
FMResult SendFax
(
FMUser user,
UserDetails senderdetails,
List<UserDetails> recipients,
MessageDetails messagedetails,
out FaxJobID[] faxjobids
);
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
|
|
senderdetails |
Die Details des Benutzers |
|
recipients[] |
Die Liste der Faxempfänger |
|
messagedetails |
Das zu sendende Fax |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
|
|
Faxjobids |
Ein Array aus |
CheckForUnreadFaxes
Verwenden Sie diese Funktion, um eine Liste der Faxe in der Warteschlange zu erhalten. Diese Warteschlange enthält all diese Faxe, die zuvor nicht heruntergeladen wurden.
Jedes Element in dieser Liste enthält nur die Details dieses Faxes und nicht das tatsächliche Faxbild. Verwenden Sie zum Herunterladen des Faxes den Befehl GetNextFax().
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
|
|
receivedfaxes |
Ein Array aus |
GetSendingFaxStatusUpdates
Verwenden Sie diese Funktion, um den Status eines Faxes abzufragen, das zuvor mithilfe der SendFax-API übermittelt wurde.
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
|
| Die jedem Empfänger eines ausgehenden Faxes zugewiesene eindeutige Kennung |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
|
|
Gibt den Faxstatus zurück. |
GetNextFax
Verwenden Sie diesen Befehl, um das älteste Fax aus der Warteschlange abzurufen. Diese Warteschlange enthält all diese Faxe, die zuvor nicht heruntergeladen wurden.
Beim Abrufen des ältesten Faxes wird es nicht automatisch aus der Warteschlange gelöscht. Verwenden Sie DeleteFax(), um das älteste Fax zu löschen und so das nächste Fax abrufen zu können. Wenn das älteste Fax nicht gelöscht wird, erhalten Sie das gleiche Fax erneut.
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
|
|
faxdetails |
ReceivedFaxDetails enthält die Details des Faxes. |
|
fax |
Das Faxbild |
GetNextFaxByCriteria
Verwenden Sie diesen Befehl, um das älteste Fax gemäß den angegebenen Kriterien aus der Warteschlange zu löschen. Diese Warteschlange enthält all diese Faxe, die zuvor nicht heruntergeladen wurden.
Beim Abrufen des ältesten Faxes wird es nicht automatisch aus der Warteschlange gelöscht. Verwenden Sie DeleteFax(), um das älteste Fax zu löschen und so das nächste Fax abrufen zu können. Wenn das älteste Fax nicht gelöscht wird, erhalten Sie das gleiche Fax erneut.
FMResult GetNextFaxByCriteria
(
FMUser user,
SearchCriteria criteria,
stringcriteriavalue,
out ReceivedFaxDetails faxdetails,
out FileData fax
);
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
|
|
Criteria |
DTMFDualton-Mehrfrequenzwahlverfahren- oder Remote-ID |
|
Criteriavalue |
Der Wert des Kriteriums |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
|
|
faxdetails |
ReceivedFaxDetails enthält die Details des Faxes. |
|
Fax |
FileData enthält die tatsächlichen Faxbilddaten. |
DeleteFax
Verwenden Sie diese Funktion, um ein bestimmtes Fax zu löschen.
Parameter:
| Parameter | Beschreibung |
|---|---|
|
Die Anmeldeinformationen des Webdienst-API-Benutzers |
|
|
FaxID |
Die ID des zu löschenden Faxes. Dieser Wert kann aus der Ausgabe von |
Rückgabewerte:
| Parameter | Beschreibung |
|---|---|
|
Gibt das Ergebnis der Funktion zurück. |
Klassen
UserDetails
Diese Klasse enthält die Details eines Empfängers/Absenders.
Alle Felder sind optional. Eine Ausnahme bildet die Eigenschaft Faxnumber, wenn sie als Empfänger verwendet wird.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
Firstname |
Zeichenfolge | Der Vorname |
|
Lastname |
Zeichenfolge | Der Nachname |
|
Company |
Zeichenfolge | Der Unternehmensname |
|
Department |
Zeichenfolge | Der Abteilungsname |
|
Faxnummer |
Zeichenfolge | Die Faxnummer |
|
|
Zeichenfolge | Die E-Mail-Adresse |
MessageDetails
Ein Objekt dieser Klasse enthält die Details für ein neues Fax.
Alle Felder sind optional mit Ausnahme von BillingCode, wenn die Kostenstelle aktiviert ist.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
Subject |
Zeichenfolge | Der Faxbetreff |
|
Schedule |
DateTime | Das Datum und die Uhrzeit, an dem/zu der das Fax gesendet werden soll. |
|
Priority |
FaxPriority |
Legt die Faxpriorität fest. |
|
BillingCode |
Zeichenfolge |
Gibt die Kostenstelle an. Nur erforderlich, wenn Kostenstelle aktiviert ist. |
|
Resolution |
FaxResolution | Die zu verwendende Auflösung. |
|
Coverpage |
Zeichenfolge | Standardmäßig wird ein Fax mit dem in GFI FaxMaker konfigurierten Standard-DeckblattEine Seite mit Informationen, die an das Fax angehängt und als erste Seite gesendet wird. Diese Seite ist benutzerdefinierbar und kann das Unternehmenslogo und die Unternehmensfarben sowie Absender- und Empfängerinformationen, Faxdetails u.v.m. enthalten. geschickt. Mit diesem Parameter können Sie ein Fax mit einem bestimmten Deckblatt schicken. |
|
FrontCoverNote |
Zeichenfolge | Standardmäßig wird das Fax mit der in GFI FaxMaker konfigurierten Standard-Deckblattadressierung geschickt. Mit diesem Parameter können Sie ein Fax mit einer bestimmten Deckblattadressierung schicken. |
|
FaxLine |
Ganzzahl | Verwenden Sie diesen Parameter, wenn das Fax an eine bestimmte FaxleitungEine reale Telefonleitung oder softwarebasierte (FoIP-)Leitung, die an ein Faxgerät (Modem oder ISDN-/Faxkarte) angeschlossen ist. geschickt werden soll. Geben Sie die Faxleitungsnummer an, die in der GFI FaxMaker-Konfiguration festgelegt ist. |
|
Demandline |
Bool‘sch | Bei der Angabe einer bestimmten Faxleitung (Attribut FaxLine) wird das Fax an eine andere Leitung geschickt, wenn die Leitung besetzt ist. Wenn das Fax nur über eine bestimmte Leitung gesendet werden soll, setzen Sie den Attributwert auf true. |
|
header |
Zeichenfolge | Geben Sie eine personalisierte Kopfzeile an, die oben auf der Faxseite zur Faxkopfzeile hinzugefügt wird. |
|
UniqueID |
Zeichenfolge | Gibt eine Kennung an, die zur Markierung der Nachricht verwendet wird. Die Eindeutigkeit dieser Kennung legt die Person fest, die die Nachricht erstellt. |
| Zeichenfolge |
Gibt eine einzelne Zeile des TextAPI-Befehls an. Eine Liste der TextAPI-Befehle finden Sie unter TextAPI-Befehle. |
|
|
MessageBodyFile. |
FileData | Eine Instanz von FileData, die eine Textdatei enthält, die wiederum den Nachrichtentext des Faxes enthält. |
|
Attachments |
List<FileData> | Array aus Anhängen |
FMUser
Ein Webdienst-API-Benutzer
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
|
Zeichenfolge |
Die E-Mail-Adresse des Benutzers, wie sie unter Lizenzierte Benutzer konfiguriert ist. Der Benutzer muss ein registrierter Webdienst-API-Benutzer sein. |
|
Password |
Zeichenfolge |
In Active Directory ist dies das konfigurierte Benutzerkennwort. In SMTPSimple Mail Transport Protocol-Umgebungen ist das Kennwort eine automatisch erstellte GUID aus dem Knoten Lizenzierte Benutzer für registrierte Webdienst-API-Benutzer. |
FaxJobID
GFI FaxMaker weist jedem Empfänger eines ausgehenden Faxes eine einzigartige Kennung zu. Verwenden Sie diese Kennung, um den Status eines Faxes zu überwachen.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
Recipient |
Zeichenfolge | Die Faxnummer des Empfängers |
|
ID |
Zeichenfolge | Die von GFI FaxMaker zugewiesene, einzigartige Kennung |
ReceivedFaxDetails
Ein Objekt dieser Klasse wird empfangen, wenn GetNextFax() aufgerufen wird.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
FaxUID |
Zeichenfolge | Die eindeutige Faxkennung. Verwenden Sie diese Kennung, um ein Fax zu löschen. |
|
WhenReceived |
DateTime | Das Datum und die Uhrzeit, an dem/zu der das Fax empfangen wurde. |
|
NosPages |
Zeichenfolge | Die Anzahl der empfangen Seiten |
|
Resolution |
FaxResolution | Die Auflösung des empfangenen Faxes |
|
RemoteID |
Zeichenfolge | Der Name des Faxgerätes des Empfängers |
| Zeichenfolge | Die DTMF/DID-Durchwahlnummer der empfangenden Leitung |
FileData
Ein Objekt dieser Klasse enthält die tatsächlichen Daten einer Datei.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
Filename |
Zeichenfolge |
Die Name der Datei; oftmals zur Bestimmung des Dateiformats verwendet. |
|
Data |
Byte[] |
Die Dateidaten in einem Bytearray |
FaxSendingStatus
Ein Objekt dieser Klasse wird empfangen, wenn GetSendingFaxStatusUpdates() aufgerufen wird.
| Datenelemente | Typ | Beschreibung |
|---|---|---|
|
FaxUID |
Zeichenfolge | Eindeutige Faxkennung |
|
RemoteID |
Zeichenfolge | Der Name des Faxgerätes des Empfängers |
|
CurrentTransmissionPage |
Ganzzahl | Die Seite, die momentan übermittelt wird. Nach dem Versand eines Faxes gibt dies die Gesamtanzahl der übermittelten Seiten zurück. |
| TotalPages | Ganzzahl | Die Gesamtanzahl der Seiten, aus denen das Fax besteht |
| Status | SendingStatus | Der aktuelle Faxstatus |
Enums
FaxPriority
| Wert | Beschreibung |
|---|---|
|
None |
Keine Priorität festgelegt. |
|
Low |
Niedrige Priorität |
|
Normal |
Normale Priorität |
|
High |
Hohe Priorität |
|
VeryHigh |
Sehr hohe Priorität |
FaxResolution
| Wert | Beschreibung |
|---|---|
|
NonSet |
Keine Auflösung für benutzerdefiniertes Fax festgelegt. |
|
High |
Hohe Auflösung |
|
Normal |
Normale Auflösung |
SearchCriteria
| Wert | Beschreibung |
|---|---|
|
RemoteID |
Suchen Sie Faxe nach Anrufer-ID oder Name des Faxgerätes. |
|
DTMF |
Suchen Sie Faxe nach der Durchwahlnummer der empfangenden Leitung. |
SendingStatus
| Wert | Beschreibung |
|---|---|
|
Preparing |
Verarbeiten und Umwandeln des Inhalts in ein Fax |
|
ConvertingAttachment |
Umwandeln des Anhangs in das Faxformat |
|
Pending |
Das Fax befindet sich in der Warteschlange. |
|
Sending |
Fax wird übertragen. |
|
Sent |
Fax wurde gesendet. |
|
Failed |
Übertragung fehlgeschlagen. |
|
Cancelled |
Der Faxauftrag wurde abgebrochen. |
FMResult
| Wert | Beschreibung |
|---|---|
|
Success |
Funktion erfolgreich abgeschlossen. |
|
Failure |
Funktion fehlgeschlagen. |
|
UserNotValid |
Die Benutzerdetails sind ungültig. |
|
DBError |
Fehler beim Schreiben in oder Lesen aus der Datenbank |
|
FaxImageNotFound |
Das erforderliche Faxbild wurde nicht gefunden. |
|
NoSender |
Kein oder ungültiger Absender angegeben. |
|
NoRecipients |
Kein oder ungültiger Empfänger angegeben. |
|
InvalidFaxDescription |
Ein oder mehrere Pflichtfelder wurden nicht ausgefüllt. |
Eine Hilfestellung zur Entwicklung von benutzerdefinierten Anwendungen für die GFI FaxMaker-Webdienst-API finden Sie in den bereitgestellten Beispielen.