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:

Some companies require a contract before an account can be created, so we cannot always make a separate test account for every collector. And when a test account is available, it may not contain invoices, which means we cannot verify the full collection flow. For this reason, implementing a collector can require testing with the credentials of users who already have an account with invoices. A collector in development is being implemented and validated this way; it is not yet considered ready for general use, and collection may be limited while testing is underway.

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

State	Description
Planned	The collector is planned but is not yet available for account connection or invoice collection.
Development	The collector is being implemented and tested, sometimes using credentials from users with existing accounts and invoices when separate test accounts are unavailable or lack invoice data. It is not yet ready for general use, and collection may be limited during testing.
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 is scheduled but not yet started
credential.collector.state != "planned" and 0 < credential.state.index < credential.state.max	In progress	Collection is in progress
credential.collector.state != "planned" and credential.state.index == credential.state.max	Up and running	Collection is running or completed successfully

astuce

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."