De Dropbox Fax API instellen

Dit artikel bevat informatie over het instellen van de Dropbox Fax-API met behulp van de v1-eindpunten, ervoor zorgen dat deze werkt en indien nodig het aanschaffen van extra faxlijnen.

Zo stel je de Dropbox Fax-API in met behulp van de v1-eindpunten

Zo ga je aan de slag met de v1-eindpunten:

1. Stuur een e-mail naar support@hellosign.com met het e-mailadres dat je voor je Dropbox Fax -account wilt gebruiken. Je ontvangt een reactie zodra je Dropbox Fax-API-toegang is ingeschakeld. Meer informatie over de prijzen voor Dropbox Fax-API.
2. Meld je aan bij je Dropbox Fax-account. Noteer je account-GUID, want die heb je nodig voor de meeste API-aanvragen (of eindpunten).
3. Voer je eerste API-aanvraag uit en verkrijg de configuratiegegevens van je account:

Een voorbeeld hiervan is:

Een ander voorbeeld (vergeet niet om de URL te versleutelen):

Het antwoord is een JSON-weergave van je accountinstellingen.

4. Om callback-URL’s voor inkomende en uitgaande faxen opnieuw toe te voegen met een POST:

5. Om de beschikbare faxlijnen te bekijken:

Het antwoord bevat de FaxLine die je hebt gekozen bij het registreren voor je premium-abonnement.

6. Om een faxnummer te kopen, moeten we met een GET controleren welke deelstaat-netnummers beschikbaar zijn (niet alle netnummers zijn beschikbaar):

7. Koop een faxnummer uit een van de beschikbare netnummers in stap 6:

8. Om een fax te verzenden:

Hiermee wordt het proces gestart voor het verzenden van een fax. Als je het HTTP-antwoord 200 ontvangt, is dat geen garantie dat de fax ook doorkomt; er kan een fout optreden bij de bestandsconversie. Zodra de StatusCode van de fax echter verandert in E (‘Error’) of S (‘Succes’), ontvang je een POST op de callback-URL die je in stap 4 hebt opgegeven. Meer informatie over callback-gebeurtenissen.

Mogelijke waarden van de StatusCode:

• T = bezig met verzenden/versturen.
• P = in afwachting/bezig met converteren.
• S = verzenden gelukt.
• E = fout. Kan niet volledig converteren of verzenden.
• H = in de wacht. Deze fout treedt op als je een onbevestigd account hebt of als je geen maandabonnement hebt en daardoor niet genoeg faxpagina’s hebt.

Mogelijke ErrorCode-waarden (alleen raadplegen wanneer StatusCode is ingesteld op E):

• B = het signaal ‘bezet’ ontvangen.
• N = geen antwoord.
• A = niet-toegewezen nummer (betekent meestal dat de verbinding verbroken is).
• D = de lijn is verbroken of onbereikbaar.
• L = dit nummer staat op de lijst met geweigerde nummers (zou niet moeten gebeuren bij een nummer in de VS).
• U = onbekende fout. Dit gebeurt meestal wanneer een persoon de lijn opneemt of als er een fout is opgetreden tijdens het verzenden van de fax.
  

Opmerkingen:

• Als je een fax verstuurt en het faxapparaat van de ontvanger ondersteunt het lezen van de zogenaamde abonnee-identificatie (CSID), dan zal de nummerweergavefunctie je primaire faxnummer weergeven, of het faxnummer dat je opgeeft in de parameter ‘Van’. Je primaire faxnummer wordt ook op de fax zelf vermeld. Als je meerdere Dropbox Fax-lijnen hebt, kun je kiezen welke je wilt gebruiken als het verzendende faxapparaat door de parameter ‘Van’ op te nemen in de URL:

Zie voor de notatie van de waarde ‘Van’ het veld ‘Nummer’ dat wordt teruggestuurd bij het aanroepen van /FaxLines. (zie stap 5 hierboven).

• Je kunt meerdere bestanden uploaden en meerdere faxen verzenden in één aanroep. Stel hiervoor de parameterarrays ‘bestand’ en/of ‘Naar’ in als:

of

• Je kunt een door Dropbox Fax gegenereerde omslagpagina toevoegen door een of meer van de volgende parameters op te geven: CoverPageTo, CoverPageFrom en CoverPageMessage.
• Faxen die door de API worden verzonden worden niet op onze servers opgeslagen nadat het verzenden van de fax is gelukt; ze worden verwijderd. Daarom kun je ze niet bekijken in de UI. Inkomende faxen die met succes naar je callback zijn ge-POST worden echter wel opgeslagen op onze servers en deze kun je bekijken in het scherm ‘documenten’.
• Er geldt een limiet van 200 faxen in de wachtrij per dag. Als je deze limiet bereikt, krijg je een foutmelding ‘429’:

Hoe raadpleeg ik de statussen van faxen?

1. Je kunt het Verzend-GUID terugvinden in het JSON-antwoord dat is teruggestuurd na de API-aanroep in stap 8. Daarnaast kun je de status van al je verzendingen controleren door het Verzend-GUID weg te laten:

Deze resultaten worden gepagineerd. Je kunt verschillende pagina's krijgen door de URL-parameters 'Page' en 'PageSize' op te geven. Raadpleeg de reactie-elementen FirstPageUri, NextPageUri, PreviousPageUri en LastPageUri voor informatie over hoe paginering werkt.

2. Zodra de faxstatuscode is ingesteld op S of E, controleer je of je callback-URL voor uitgaande faxen is geactiveerd. Deze zou een POST moeten ontvangen met een parameter genaamd ‘json’ die alles bevat wat je zou krijgen als antwoord op een aanroep (zie stap 1).

Als een geslaagde POST-callback wordt verhinderd door een server- of netwerkprobleem, probeert Dropbox het opnieuw met deze intervallen:

• 15 minuten
• 45 minuten
• 1 uur en 30 minuten
• 2 uur en 45 minuten
• 4 uur
• 8 uur en 15 minuten
• 16 uur en 30 minuten

Bij elk interval kan Dropbox de POST meerdere keren proberen als er geen antwoordcode ‘200’ is ontvangen.

3. Als je de fax naar je eigen Dropbox-faxnummer hebt gestuurd (handig voor het testen), controleer dan of de callback-URL van je inkomende fax ook is geactiveerd.
4. Overzicht van de faxlijnen die je hebt gekocht:

5. Om een faxlijn te verwijderen, voer je een DELETE-aanroep uit naar de URi van die faxlijn (aangegeven in het antwoord op de vorige stap):

Als de operatie succesvol is, krijg je de reactie '200'.