submitCredentials

6 min

This API does three tasks:

Verify the credential format of different institution;

Each institution has its own requirements of login information and also the corresponding input format. In order to improve the user experience, partners can verify the format of each user input field by the front-end application before submitting the credential.

Partners can check out all the credentials format in attached table "Institution credentials" in the end of this documentation.

Is used to generate data collection tasks in Klavi backend;

If the credential format is correct, the Klavi backend will generate a task for this submission, backend will submit this credential to the institution to start to obtain and process the data.

Send result as callback.

When the task is completed, the result will be callback(See the callback section of this document) to the partner.Therefore, the partner needs to provide a callback URL to receive the result.

In addition, you can also call the checkStatus() API in polling mode to query the task status.

💡 Note:

Partners can extend the extraParams parameter according to business requirements, which will be transparently written into data reports and transmitted to partners.
If any one of cpf/agency/account/username/password exists in credential, it needs to be encrypted according to RSA encryption algorithm before submitting, and RSA public key is provided independently.

Example:

package main

import (
	"crypto/rand"
	"crypto/rsa"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
	"fmt"
	"os"
)

// RSAEncrypt
// plainText: Data to encrypt
// path: path of publicKey file
func RSAEncrypt(plainText []byte, path string) []byte {
	file, err := os.Open(path)
	if err != nil {
		panic(err)
	}
	defer func() {_ = file.Close()}()

	info, _ := file.Stat()
	buf := make([]byte, info.Size())
	_, _ = file.Read(buf)
	block, _ := pem.Decode(buf)
	publicKeyInterface, err1 := x509.ParsePKIXPublicKey(block.Bytes)
	if err1 != nil {
		panic(err1)
	}

	publicKey := publicKeyInterface.(*rsa.PublicKey)
	cipherText, e := rsa.EncryptPKCS1v15(rand.Reader, publicKey, plainText)
	if e != nil {
		panic(e)
	}

	return cipherText
}

func main() {
	// encrypt
	data := []byte("hello world")
	encrypt := RSAEncrypt(data, "public.pem")
	fmt.Println(base64.StdEncoding.EncodeToString(encrypt))
}

Request parameter:

Name	Type	Required	Description
cpf	String	No	cpf
agency	String	No	agency
account	String	No	User account number
userName	String	No	User name(current only for Caixa or corporate account)
password	String	Yes	Password
institutionCode	String	Yes	Institution code
cooperativaOption	String	No	Only for Ailos, 13 options in total
passwordPhrase	String	No	Only for Ailos, "Frase Secreta" phrase
accountLevel	Number	No	Only for Bradesco, 1st/2nd/3rd account for login
extraParams	Object	No	Partners can customize additional parameters, such as UUID defined by partners themselves, which will be transparently written into data reports and transmitted to partners.

extraParams special case for FGTS

If institutionCode is 5001, that is FGTS.

In case where FGTS requires email verification, if you want to control whether to send verification emails to users, you can use the fgtsEmailValidate key to control.

If fgtsEmailValidate value is true, a verification email will be sent to the user. If value is false, no verification email will be sent to the user. If not set fgtsEmailValidate key, the effect is equivalent to true.

For example(In this case, no verification email will be sent to the end-user):

"extraParams": { "fgtsEmailValidate": false }

Return data:

Name	Type	Description
traceId	String	The tracking number of the task

curl -s -L -X POST 'https://api-testing.klavi.ai/link/external/v2/submitCredentials' \
-H 'Authorization: K1-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******/2019-02-25/cbms/k1_request, SignedHeaders=content-type;host, Signature=325014a0adb8cdde5625e87b5fa29be248675c051b1fa19b727cc5a319d22ce5' \
-H 'X-Timestamp: 1551113065' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'X-Region: ap-brazil' \
--data-raw '{"cpf":"b+NPeR11I488/X/vkapEcsLfbRl4ttckHE5zPzHSctDtZ/q2pjb8QKloN7aVZGgZacRACw+P5OgGH/hvAlr4OjGca4r5Ip4ojer1rPb+g7OPwlRx02a8qMkyMdzEIcXRaIZCGZwig/0pMZ+WbeI5dK7URQaDqFgOAC8CVTxo8PI=","password":"TCQezjI75yCyV1I20Pq/5OJgkb1qjSnw2CbxEsNiCngJbGGtQlAtOEbLXQcVobIniVbYnmWpFI6aY3x5SYBbR2Po9lmAGVHTwrIWs3YgbtwyJlo7/bhu8By6g93XaudT13UNbsQmyLsER10JpNue+yv/gGfsPBqmnC4HhaS2PPY=","institutionCode":"033"}'

Return to the correct example:

{
    "code":200,
    "msg":"Solicitação realizada com sucesso",
    "data":{
        "traceId":"96oLr905aoJs0Qad5B0ASHgweFkIIOtZ"
    }
}

Examle of formatting errors:

{
    "code":410,
    "msg":"The user input the wrong credential (cpf)",
    "data":{

    }
}