Skip to content

Fetchdocs 📲

Yoli internally is connected to one of our other services: Fetchdocs

Fetchdocs allows you to log into one of thousands of online portals that issue invoices (i.e. Telekom or Amazon) and fetches them periodically.

We use this to automatically import them into the documents of a user.

Available Portals

To list all available portals you can use the fetchdocsSuppliers query. Logos are also provided, which you may use to display them nicely to users.

{
  fetchdocsSuppliers {
    prim_uid
    name
    supplier_logo_url
  }
}
{
  "data": {
    "fetchdocsSuppliers": [
      {
        "prim_uid": 4242,
        "name": "Regenbogen GmbH",
        "supplier_logo_url": "<regenbogen logo url>"
      },
      ...
    ]
  }
}

Adding a Portal

As with adding bank accounts, adding online portals is also a complex process, as there are many different authentication methods (including 2FA) and other possible fail states.

After a portal is added, documents will be downloaded periodically and imported into Yoli.

Getting the Required Login Fields

Portals may require different login information, for example a username, a password and a secondary PIN. Though there might be a lot less or a lot more required.

To get the required fields for a portal, you can use the fetchdocsSupplierFields query with the id of the supplier.

{
  fetchdocsSupplierFields(supplierid: 5680, lang: "de") {
    field_key
    label
    help_text
    mandatory
    type
    dependency
  }
}
{
  "data": {
    "fetchdocsSupplierFields": [
      {
        "field_key": "USERNAME",
        "label": "Benutzername",
        "help_text": "",
        "mandatory": true,
        "type": "text",
        "dependency": ""
      },
      {
        "field_key": "PASSWORD",
        "label": "Passwort",
        "help_text": "",
        "mandatory": true,
        "type": "password",
        "dependency": ""
      }
    ]
  }
}

Starting a Login Process

To start a login process simply send the credentials and the supplier id to the addFetchDocsSupplier mutation. You will get the id of the newly added UserSupplier back.

mutation {
  addFetchdocsSupplier(input: {
    supplierid: 4242, 
    fields: [
      {key: "USERNAME", value: "rainbow"}, 
      {key: "PASSWORD", value: "1234"}
    ]
    })
}

To check the status of a login process, you can query the UserSupplier for last_status_key. If further action is required (i.e. 2FA) input_request_prim_uid will be non 0.

{
  me {
    fetchdocsSuppliers {
      last_status_key
    }
  }
}
{
  "data": {
    "me": {
      "fetchdocsSuppliers": {
        "last_status_key": "SUCCESS"
      }
    }
  }
}

Notifications and Input Requests

Yoli also stores notifications you can use to display required actions to the user. For example a notification might indicate to the user that they entered a wrong password.

You can fetch notifications using the fetchdocsNotifications and fetchdocsInputRequests fields in the user.

{
  me {
    fetchdocsInputRequests {
      id
      text
    }
  }
}
{
  "data": {
    "me": {
      "fetchdocsInputRequests": [{
        "id": "4242"
      }]
    }
  }
}

After the user has dealt with them you can dismiss them with the removeNotification and removeInputRequests mutations.

mutation {
  removeInputRequest(id:"4242")
}

Fulfilling Input Requests

To fill an input request you first need to trigger it (this will for example send out a 2FA sms). This can be done via the triggerInputRequest mutation.

mutation {
  triggerFetchdocsInputRequest(customerSupplierId: 4242, inputRequestId: 4242)
}

To answer an input request, you also need to know what kind of input request you are dealing with. All relevant information (including the texts to be displayed to the user) can be accessed in the fetchdocsInputRequests field of the user.

To finally fill an input request simply send its id and the code the user entered to the fillFetchdocsInputRequest mutation.

mutation {
  fillFetchdocsInputRequest(requestid:4242, code: "1234")
}

Removing a Portal

To stop syncing a portal simple use the removeFetchdocsSupplier mutation.

mutation {
  removeFetchdocsSupplier(customerSupplierid: 4242)
}

Editing a Portal

You can also edit the credentials of a portal (i.e. if the user entered the wrong ones) with the updateFetchdocsSupplier mutation.

mutation {
  updateFetchdocsSupplier(input: {
    supplierid: 4242
    fields: [
      {key: "USERNAME", value: "rainbow"}, 
      {key: "PASSWORD", value: "1234"}
    ]
  })
}

Accessing a Portal's Documents and the Portal of a Document

All fetchdocsUserSuppliers have a field documents, which you can use to access their documents.

{
  me {
    fetchdocsSuppliers {
      documents {
        name
      }
    }
  }
}
{
  "data": {
    "me": {
      "fetchdocsSuppliers": {
        "documents": [
          {
            "name": "Regenbogenrechnung"
          }
        ]
      }
    }
  }
}

Documents added through fetchdocs also have a fetchdocsUserSupplier field, which you can use to access that supplier.