1. Technical Integration Guide
Version 2.6

2. What is fetchdocs about?
Fully automated documents fetching API service for your application. The engine is able to collect any kind of document and push it into your platform - for example invoices, bank statements or insurance policies.

3. Integration Types
fetchdocs.io is a whitelabel-solution, hosted in AWS, which can be integrated into your application.
It can be integrated into web portals, desktop software and mobile applications.
You have two different options to integrate the feature-set into your application.
API Integration
Plug&Play Integration
All UI is developed by your team within your own application.
The fetch engine is connected via REST API.
UI is used from the fetch engine and integrated as iFrame, Popup or Redirect. Styling is adjusted with CSS to make it look nearly 100% equal to your own application.

4. Both options have advantages and disadvantages
Comparison
Both options have advantages and disadvantages
API Integration
UI Plug & Play Integration
Pro: You have full control of your UI. You are able to make changes on your own without communication or technical dependencies.
Pro: UI will look 100% equal to the rest of the application. The user does not see any differences compared to other modules.
Con: The development effort is higher than the Plug&Play Integration.
Pro: Quickest option for integration. All UI is ready and integrated via iFrame or Popup. Effort is much less than API integration.
Pro: No maintenance efforts in case of browser updates
Pro: All data is passed around only within the separated engine, no data is passed through your stack.
Con: Design can be adjusted with CSS to make it nearly look like your application. It can be really close, but maybe little differences can be noticed by Geeks 
Con: Dependency on required UI changes

5. Wording C S C S I N Customer Supplier Credential Session Input Request
The following words are used in the technical documentation which you find in RAML-Format at C S C
Customer
Supplier
Credential
A customer is an account in your platform. It is not a user account. Users belong to a customer account.
Our word for online portals like Amazon, Google Adwords, Twitter – so any portal that will has documents which the engine will fetch.
The login information required for a user to log into a supplier portal. So “your Amazon Login” for example. A credential is most often username+password, but sometimes it requires more fields to fill. S I N
Session
Input Request
Notification
Means the Login Session of a user. The user is logged into your application and has a User Session there. This user session must be matched with another user session in the fetch engine. (Only relevant in Plug&Play integration)
Sometimes it requires that a portal requests additional information from a client on login. It can be a security question (Your birthday, what is the name of your first pet,…) or a 2-factor-code. In such cases we send a push record to your system and request “some input”.
Notifications are used to give the user a more detailed status about a credential. For example a user has access to a certain portal, but within this portal he has no access to the billing area. In that case we don’t simply return “Login failed” but a clear notification type so that you can show the user proper information.

6. Push Endpoints Documents Notifications Input Requests
No matter if API integration or Plug&Play: There are three (or just two) endpoints required where the fetch engine can push information to.
Documents
You can either pull new documents from our API endpoint “getDocumentsQueue” or get new documents pushed to your endpoint “pushDocuments”
Notifications
Endpoint: pushNotification – here you receive information for a user credential. Each notification has a “type-key”, so you can use your own wordings and translations to show proper messages to the users.
Input Requests
Endpoint: pushInputRequest – for requesting additional credential information or 2-factor-codes

7. Plug&Play Integration
Customer
Session UI
Docs
Relax
Customer
Session UI
Docs
Use “createCustomer” API method to create a customer record in the fetch engine. Store the returned customer ID and customer token in your database.
Request a user session for either a newly created customer or already existing customer. You receive back a user session token.
Load the UI via iFrame, Popup or Redirect using the received user session token.
Either get documents pushed to your endpoint or pull from from “getDocumentsQueue” API method.

8. API Integration createCustomer Getting started
API Integration also starts with “createCustomer” API call. This request is needed once only for each customer account. You need to store the returned customer ID in your database along with the “customer token”. When you want to change something for the user with “updateCustomer” API Call, you have to pass this token. It is just an extra security layer and has no other functional use.

9. API Integration listCustomerSuppliers deleteCustomerSupplier
Supplier List
listCustomerSuppliers
This function requires the customer ID as input parameter and will return you all connected suppliers with information about status and input request – if any.
deleteCustomerSupplier
If you want to delete an existing credential.
startCustomerDownloadProcess
If the user cannot wait for the next scheduled run of the fetch engine, he can enforce an adhoc-process.

10. Adding and editing a supplier
API Integration
Adding and editing a supplier
getSupplierFields
Most portals require username and password fields only.
But some portals require additional fields and for a few portals we also have specific optional settings. This function will tell you what UI fields are required.
createCustomerSupplier
Use it to save a new credential with the data entered into the dynamically rendered UI fields.
updateCustomerSupplier
To update credential information, call the update method.

11. List if all required UI Dialogs
API Integration
List if all required UI Dialogs
Update Customer
List Suppliers
Settings dialog for the user to make some standard settings for his account. For example the user can set a standard start-date until when the engine should fetch documents. So it will not download very old documents that could be of no use for the user.
All credentials of one account. User actions from here are: Edit Credential, Delete Credential, Activate/Deactivate Credential and Start Download.
Add Supplier
Notifications
User can search for suppliers by Name and add his credentials.
Show notifications somewhere to the user. If your application already has a flow to show customer notifications you most probably integrate it with that.
Input requests
Update Supplier
Request information from the user and ask him to enter something. You use “fillInputRequest” API method then. Input requests can have an optional expiration date/time. If expired, you offer a button to “Restart download” and then call the “triggerInputRequest” API method.
Save changes to the user credentials.
Suggest Supplier
Users can suggest new portals which are not available yet.

12. API Integration Data Encryption Trackers & Ads Security Notes
Store any user credentials only using an HTTPS encrypted connection.
For highest security standards also encrypt the credentials in the Client UI and send it encrypted to your server, where you unencrypt it again and encrypt it another time with the password-encryption logic that was shared with you by your account manager.
Helpful links:
Data Encryption
In case you use Tracking Software to analyze user behaviour and maybe doing A/B Testings or you use any third-party advertisments: TURN THEM OFF
Turn them off in the pages or dialogs where the credentials are entered. You have no control or insights about the external loaded codes.
Malicious or exploited JavaScript codes could be used to steal user credentials while he enters them.
Trackers & Ads

13. visit/contact/try it at
Thank you!
visit/contact/try it at