Credential & Collector states

Credential State

Credentials go through various states during their lifecycle. Understanding these states is crucial for providing appropriate UI feedback to your users.

Each credential object has a state field:

...
state: {
  index: 3,                                             // Number from -2 to 7
  max: 7,                                               // Always 7
  title: "2FA code is required",                        // Title of the current state 
  message: "A 2FA code has been sent to ***@gmail.com"  // Instructions for the current state
},
...

State	Index	Description	Possible actions
Unknown	0	Something went wrong - Unexpected state
Preparing collect	1	Initial preparation phase before collection starts
Authentication in progress	2	Authentication process is underway
2FA code required	3	Two-factor authentication code is needed from user
Performing 2FA	4	Processing the provided 2FA code
Collecting data	5	Gathering data from the collector source
Downloading invoices	6	Retrieving invoice files
Done	7	Collection completed successfully
Error	-1	An error occurred during the process
Disconnect	-2	Credential needs to be reconnected

Collector State

In addition to the credential state, each credential has a collector object with its own state field. This is important to check before interpreting the credential state:

...
collector: {
  state: "planned"  // Can be "planned", "development", "active", etc.
},
...

State	Description
Planned	The collector is under development and not yet functional. Users can still see the collector in the UI, but no invoices will be collected until it becomes active.
Development	The collector is being developed but not yet ready for production. Invoices are not yet being collected.
Active	The collector is fully developed and operational. At least one invoice has been collected successfully.

Recommended UI Mapping

When displaying users credential status in your application, it's important to consider both the credential.state and collector.state to provide accurate and user-friendly feedback. To provide the best user experience and reduce support requests, we recommend the following UI label mapping:

Condition	Suggested UI Label	Explanation
credential.collector.state == "planned"	Coming soon	The collector is under development. The user's request has been registered and will be processed once the collector is operational.
credential.collector.state != "planned" and credential.state.index < 0	Error	An error occurred (index -1) or reconnection needed (index -2)
credential.collector.state != "planned" and credential.state.index == 0	Scheduled collection	Collection is scheduled but not yet started
credential.collector.state != "planned" and (credential.state.index == 1 or credential.state.index == 2 or credential.state.index == 4)	Connection in progress	Authentication or 2FA verification is in progress
credential.collector.state != "planned" and credential.state.index == 3	2FA required	Waiting for user to provide 2FA code
credential.collector.state != "planned" and credential.state.index >= 5	Active	Collection is running or completed successfully

tip

When displaying "Coming soon" status, consider adding an explanatory message such as: "This collector is currently under development. We will notify you as soon as it becomes operational."