2. Add a credential

Invoice-Collector offers two flexible integration approaches to the credential addition process. Whether you prefer a quick, embedded solution or full control over the user experience, we have you covered.

Comparison Table

Feature	iFrame Integration	Full API Integration
Setup Time	48 hours	2 weeks
Customization	Limited (CSS theming)	Complete control
Maintenance	Automatic	Manual updates needed
API Calls	Handled internally	You manage all calls
WebSocket Management	Automatic	You implement
UI Consistency	Invoice-Collector branded	Your brand
Technical Complexity	Low	Medium to High
Best For	Quick implementation	Custom experiences

---

1. Iframe integration (Quick & Easy)

The iFrame integration is the fastest way to add Invoice-Collector to your application. With this approach, the credential addition process is embedded in our pre-built interface. All the complex API interactions are handled automatically within the iframe, especialy the WebSocket connection and events handling.

The only thing to do is display an iframe with url:

/ui?token=${token}

Key Benefits:

• ⚡ Fastest integration - Get up and running in minutes
• 🔒 Secure by default - Credentials never pass through your frontend
• 🎨 Pre-built UI - No need to design credential collection forms
• 🔄 Automatic updates - Always get the latest features and collectors
• 📱 Responsive design - Works seamlessly on all devices

Perfect for:

• MVPs and rapid prototyping
• Teams with limited frontend resources
• Applications that want to minimize maintenance
• Projects prioritizing time-to-market

Implementation

Step	Side	Description
1	Frontend	Create a hidden iframe with no href.
2	Frontend	User clicks on the "Add collector" button.
3	Frontend	Update the iframe href to /ui?token=${token} and display the iframe.
4	Frontend	Listen for events sent from the iframe to parent (see the next section).

Events from iframe to parent

In order to integrate the iframe seamlessly in your frontend, our iframe send events to your frontend to notify what panel is currently displayed in the iframe. These events can be used to adapt the size of the iframe during the credential addition process.

Here are the events sent from the iframe to your frontend :

Name	Format	Description	Recommended Embedding
Close	{ type: 'ic-close' }	The credential addition process in finished. The iframe can be closed.
Panel Search	{ type: 'ic-panel-search' }	Current panel is "Search". User can search for a collector in the list.
Panel Form	{ type: 'ic-panel-form' }	Current panel is "Form". User inputs are asked in a form.
Panel Feedback	{ type: 'ic-panel-feedback' }	Current panel is "Feedback". A small feedback form is displayed.
Panel Progress	{ type: 'ic-panel-progress' }	Current panel is "Progress". Credential collect is in progress.
Panel Canvas	{ type: 'ic-panel-canvas' }	Current panel is "Canvas". User needs to authenticate using video stream.

In your application, here is how the events can be catch:

window.addEventListener('message', function(event) {
    //Message received from an iframe

    // If event comes from Invoice-Collector
    if (event.origin === "https://api.invoice-collector.com") {
        if (event.data.type === 'ic-close') {
            //Close the iframe
        }
        else if (event.data.type === 'ic-panel-search') {
            //Panel "Search" is displayed
            //Recommended: Resize the iframe to full screen (eg: 100%, 100%)
        }
        else if (event.data.type === 'ic-panel-form') {
            //Panel "Form" is displayed
            //Recommended: Resize the iframe to full screen (eg: 100%, 100%)
        }
        else if (event.data.type === 'ic-panel-progress') {
            //Panel "Progress" is displayed
            //Recommended: Resize the iframe to small size (eg: 500px, 500px)
        }
        else if (event.data.type === 'ic-panel-canvas') {
            //Panel "Canvas" is displayed
            //Recommended: Resize the iframe to big size (eg: 1200px, 600px)
        }
        else if (event.data.type === 'ic-panel-feedback')
            //Panel "Progress" is displayed
            //Recommended: Resize the iframe to small size (eg: 600px, 600px)
        }
    } else {
        //Event origin is not Invoice-Collector
    }
});

You may resize the iframe to match your desired UX, the choice is yours.

How it works

---

2. Full integration (Complete Control)

The Full API integration gives you complete control over the user experience. Build your own interface while leveraging our powerful backend infrastructure for credential management and invoice collection.

Key Benefits:

• 🎨 Full UI customization - Design matches your brand perfectly
• 🔧 Maximum flexibility - Control every aspect of the user flow
• 📊 Custom analytics - Track user interactions your way
• 🌐 Multi-platform - Reuse logic across web, mobile, and desktop

Perfect for:

• Enterprise applications with specific branding requirements
• Teams with strong frontend capabilities
• Applications requiring deep integration with existing workflows
• Projects needing custom validation or user guidance

Implementation

Step	Side	Description
1	Frontend	Create a page to display all the available collectors.
2	Frontend	Create a page to ask for credentials.
3	Frontend	Create a page to display addition progress.
4	Frontend	User clicks on the "Add collector" button.
5	Backend	Call POST /user to create a user in our database and get the user.
6	Backend	Call GET /collectors to list all the available collectors.
7	Backend	Call POST /user/{user_id}/credential to create a new credential.
8	Frontend	Implement WebSocket connection /ws and events (state, screenshot, twofa, close).

WebSocket connection

When implementing the Full API integration, you'll need to establish a WebSocket connection to receive real-time updates about the credential collection process.

Messages Received from API:

• State - Progress updates and state changes
• Screenshot - For interactive login when needed

Messages Sent to API:

• Twofa - Two-factor authentication code
• Click - Mouse click simulation during interactive login
• Keydown - Keyboard input during interactive login
• Text - Text input during interactive login
• Close - Complete interactive login session

For detailed information about WebSocket messages, refer to the Websocket Messages documentation.

How it works