Basic WhiteLabel

4min

1. Generate a Link URL
﻿
The Basic WhiteLabel is the easiest way to use Klavi services when you lack technical development resources. You just need to contact the business personnel([email protected]) to request a pre generated URL from Klavi for you. You can integrate this URL into your service and directly send it to your users.
﻿
The generated URL is similar to this:

https://conecte-sandbox.klavi.ai/data/v1/basic-links/yourappid﻿
﻿
If you were a klavi customer before 22/11/2024, you may be able to use the links according to the old nomenclature, then, it should be similar to this:
https://open-sandbox.klavi.ai/data/v1/basic-links/yourappid﻿
﻿
﻿
According to your business needs, if you want to lock end users or prevent users from entering CPF again, you can add personal_tax_id to the above URL, similar to this:
﻿https://conecte-sandbox.klavi.ai/data/v1/basic-links/yourappid?personal_tax_id=76109277673
﻿
If you were a klavi customer before 22/11/2024, you may be able to use the links according to the old nomenclature, then, it should be similar to this:
https://open-sandbox.klavi.ai/data/v1/basic-links/yourappid?personal_tax_id=76109277673﻿
﻿
As mentioned above, the path parameter supports the following parameters:
Parameter name
Type
Description
personal_tax_id
String
The CPF of the end-user, for Personal Accounts only
business_tax_id
String
The CNPJ of the company, for Business Accounts only
email
String
End user's email, compliance needs
phone
String
End user's phone, compliance needs
institution_code
String
Pre set parameters, the purpose is to avoid users choosing specific institutions
redirect_url
String
The URL for redirection upon successful link initialization.
It's value must be processed in encodeURIComponent() function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=”
products_callback_url
String
Report products callback URL, for Open finance only.
It's value must be processed in encodeURIComponent() function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=”
external_info
String
Used for partners to transmit information, which will be carried in reports sent to partners. 
It's value must be processed in encodeURIComponent() function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=”
connection_key
String
Connection key, the connectionKey has been sent to the partner in the report, for Open data update case only
application_link
String
After the institution authorization is completed, it will jump to the applicationLink address with the link_callback_url parameter (only useful when using WhiteLabel)
Perhaps you have noticed that the above parameters similar to the Create a Link﻿ API parameters except for changing from a camelCase to snake_case. That's right, it's like this because these parameters are in the body of the API when Create a Link﻿, so camelCase is used. However, if you want to use path parameters to pass, it's best to use a snake_case.
Another very important point:
1.redirect_url to being a URL, If you want to use this parameters, remember to encode them.
JSON
console.log(`?x=${encodeURIComponent('https://mydomain.com?uuid=22222')}`);
Output:
> "?x=https%3A%2F%2Fmydomain.com%3Fuuid%3D22222"
console.log(`?x=${encodeURIComponent('https://mydomain.com?uuid=22222')}`);
Output:
> "?x=https%3A%2F%2Fmydomain.com%3Fuuid%3D22222"
﻿
2.products_callback_url and external_info is object type in Create a Link﻿ API, If you want to use these parameters, remember to stringify and  encode them.
JSON
external_info=encodeURIComponent(JSON.stringify({ 'uuid': 'xxx-122-333-111'})
external_info=encodeURIComponent(JSON.stringify({ 'uuid': 'xxx-122-333-111'})
﻿
2. Fetch Product Data
You can use web or webview to open the Link URL, make subsequent selection of institutions, redirect to that institution for authentication, and return to the final result web page.
Klavi backend will send you the results through event webhook(even if it is a failed state), after the status change to AUTHORISED, you can send the specific report generation request you want based on the end user type(personal or business, their endpoints are different).
Command:
Shell
curl --location 'https://api-sandbox.klavi.ai/data/personal/institution-data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer JhbGciOiJFUzI1NiIs.QtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.nlTqpAZHeq4P2xFD' \
--data '{"taxId":"string","institutionId":"string","linkId":"String","consentId":"Array","products":"Array","productsCallbackURL":"Object"}'
curl --location 'https://api-sandbox.klavi.ai/data/personal/institution-data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer JhbGciOiJFUzI1NiIs.QtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.nlTqpAZHeq4P2xFD' \
--data '{"taxId":"string","institutionId":"string","linkId":"String","consentId":"Array","products":"Array","productsCallbackURL":"Object"}'
﻿
Expected response:
JSON
{
    "requestId": "1325412e-e566-4f4e-ac5b-2f4471586b89",
    "message": "ok"
}
{
    "requestId": "1325412e-e566-4f4e-ac5b-2f4471586b89",
    "message": "ok"
}
﻿
After you submit a request to generate specific or all report(The report you want to purchase has already been limited by Klavi backend), Klavi randomly starts retrieving data from the institution and processing it to generate the corresponding report, which will be sent to you through the report webhook.
Klavi also supports not having to actively call this endpoint. After you move to production, Klavi can proactively send all the reports to your webhook, or send them to Klavi's storage space. You can download them at any time through the Klavi Console.
﻿

Parameter name	Type	Description
personal_tax_id	String	The CPF of the end-user, for Personal Accounts only
business_tax_id	String	The CNPJ of the company, for Business Accounts only
email	String	End user's email, compliance needs
phone	String	End user's phone, compliance needs
institution_code	String	Pre set parameters, the purpose is to avoid users choosing specific institutions
redirect_url	String	The URL for redirection upon successful link initialization. It's value must be processed in encodeURIComponent() function as below, for example: “%3a” replaces “:” “%2f” replaces “/” “%3f” replaces “?” “%3d” replaces “=”
products_callback_url	String	Report products callback URL, for Open finance only. It's value must be processed in encodeURIComponent() function as below, for example: “%3a” replaces “:” “%2f” replaces “/” “%3f” replaces “?” “%3d” replaces “=”
external_info	String	Used for partners to transmit information, which will be carried in reports sent to partners. It's value must be processed in encodeURIComponent() function as below, for example: “%3a” replaces “:” “%2f” replaces “/” “%3f” replaces “?” “%3d” replaces “=”
connection_key	String	Connection key, the connectionKey has been sent to the partner in the report, for Open data update case only
application_link	String	After the institution authorization is completed, it will jump to the applicationLink address with the link_callback_url parameter (only useful when using WhiteLabel)

Updated 21 Nov 2024

Did this page help you?

How to integrate Link

Advance WhiteLabel

Basic WhiteLabel

1. Generate a Link URL

Supported path parameters

2. Fetch Product Data