Utilização do KYC Celcoin
Orientações para clientes que utilizam o nosso KYC.
Introdução
Utilize esta API para enviar os documentos coletados dos usuários e validá-los através da nossa documentoscopia. Para utilização destes serviços é necessário realizar a contratação do KYC Celcoin junto a solução do BaaS.
Aos usuários que utilizam esta API para inserir relatórios de KYC EXTERNO, as análises serão realizadas pelo nosso time de riscos. Veja mais detalhes sobre isso no último tópico dessa página "Caso não utilize o KYC Celcoin".
Pré requisitos para implementação:
-
Possuir uma chave API da Celcoin, essa chave API é enviada após contratar o serviço conosco. link.
-
Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.
-
Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.
Fluxo de integração
Enviar documentos
Documentos que devem ser enviados através do endpoint /fileupload:
- Pessoa Física: os documentos obrigatórios que devem ser enviados frente e verso, são RG (contendo o CPF) ou CNH . Apenas documentação original, não aceitamos cópias mesmo que autenticadas.
- Pessoa Jurídica: os documentos obrigatórios são: cópia atualizada do contrato social e faturamento (ou balanço).
Também será obrigatória a foto frente e verso do RG (contendo o CPF) ou CNH de pelo menos um dos sócios administradores . Apenas documentação original, não aceitamos cópias mesmo que autenticadas.
Tabela de arquivos disponíveis para inserção no campo filetype
Tipo de arquivo | Descrição |
---|---|
RG | Registro Geral |
CNH | Cadastro Nacional de Habilitação |
RNE | Registro Nacional de Estrangeiros |
SELFIE | Selfie do cliente |
CONTRATO_SOCIAL | Certidão de Nascimento da empresa. Necessário inserir a cópia atualizada do contrato social |
BALANCO | Balanço patrimonial da empresa |
CARTAO_CNPJ | Cartão CNPJ |
FATURAMENTO | Relatório de faturamento da empresa assinado pelo contador |
Quando realizar os documentos?
Antes da realização do envio dos documentos, é importante já ter realizado o processo de abertura de conta. Após a realização do processo, será enviado um evento sinalizando a pendencia de documentação (você pode acessar os templates de webhooks para mais detalhes).
Exemplo:
{
"entity": "kyc",
"createTimestamp": "2023-07-26T19:31:14.803Z",
"status": "PENDING",
"body": {
"clientCode": "416bbac2-47b6-4518-8520-a7ae20df0e",
"documentNumber": "85467256084",
"onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e"
}
}
Modelos de request:
O envio de documentos poderá ocorrer das seguintes formas:
Pessoa Física
Se o envio for de um documento de pessoa física:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{access_token}}' \ -F'cnpj='//cnpj vazio -F'documentnumber=66668506020'//numero do CPF -F'filetype=CNH'//tipo de documento -F'front=@/path/cnh.jpeg'//foto da cnh aberta
Pessoa Jurídica
Neste caso, o envio será tanto dos documentos da empresa (cópia de contrato social, cartão cnpj e balanço (ou faturamento), quanto os documentos de cada sócio dessa empresa ou pelo menos do sócio administrador. Envie as requisições dessa forma:
- Documentos da empresa:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \ --header 'Content-Type: multipart/form-data' \ --header 'Authorization: Bearer {{access_token}}' \ -F'cnpj=22506895000173'//numero do CNPJ -F'documentnumber=22506895000173'//numero do CNPJ -F'filetype=CONTRATO_SOCIAL'//tipo de documento -F'front=@/path/contrato_social.pdf'//arquivo pdf do cartao cnpj
- Documentos dos sócios:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \ --header 'Content-Type: multipart/form-data' \ --header 'Authorization: Bearer {{access_token}}' \ -F'cnpj=22506895000173'//numero do CNPJ da empresa -F'documentnumber=21912051001'//numero do CPF do socio -F'filetype=RG'//tipo de documento -F'front=@/path/rg_frente.jpeg'//foto da frente do RG do sócio -F'verse=@/path/rg_verso.jpeg'//foto do verso do RG do sócio
Envie o arquivo de documento sempre como Multipart/Form
Multipart envia arquivos/dados para o servidor no formato de array de bytes. Dados de várias partes/formulários são aplicados a um formulário, portanto, você pode enviar tudo em um formulário, incluindo dados "regulares" também.
⚠ Nunca envie os arquivos em base64 ⚠
Requisição individual por documento
Se for enviar mais de um documento por pessoa física ou jurídica, envie esses em diferentes requisições.
No caso de empresas que têm mais que um sócio, por exemplo, caso opte por enviar o documento de todos os sócios, será necessário o envio individual do documento de cada sócio.
Entenda com quais informações os campos devem ser preenchidos
- O campo
cnpj
deverá ser preenchido sempre com um número de CNPJ válido e sem pontos e traços. - O campo
documentnumber
pode ser preenchido por um CNPJ ou CPF, mas nunca com outros documentos. Esse campo também deve ser preenchido sem pontos e traços. - Preencha o campo
filetype
com maiúsculas, da forma como descrevemos na tabela de arquivos acima. - No campo
front
, insira a foto da parte da frente do documento enviado ou, no caso de um documento de face única, utilize este parâmetro para enviar o arquivo.
Serão aceitos arquivos nos formatos: jpeg , jpg e pdf, mas especificamente para RG e CNH, o formato do arquivo deve ser jpeg ou jpg, os demais tipos de arquivos poderão ser enviados no formato de pdf. - No campo
verse
, insira a foto do verso do documento.
Serão aceitos arquivos nos formatos: jpeg , jpg e pdf, mas especificamente para RG e CNH, o formato do arquivo deve ser jpeg ou jpg, os demais tipos de arquivos poderão ser enviados no formato de pdf. - Tamanho máximo de arquivo aceito de 12 MB.
Os envios devem ser realizados após a solicitação de criação de conta
Importante apenas chamar este serviço de inclusão de documentos após já ter realizado a solicitação de criação de conta. Em caso de erro 404, realize uma nova tentativa após no mínimo 30 segundos.
OBS: Recomendável que seja realizado no mínimo 30 segundos após a solicitação de criação de conta.
Modelo de response:
{
"status": 200,
"message":"Arquivo enviado com sucesso"
}
Quando não houver um registro de background check, ou seja, uma solicitação de criação de conta (conforme observação no quadro acima), o response virá da seguinte forma:
{
"errorCode": 404,
"errorMessage": "BackgroundCheck nao encontrado!"
}
Estrutura do response:
Campo | Tipo | Descrição |
---|---|---|
status | int | Status http da requisição |
message | string | Mensagem de retorno sobre o envio do documento |
Eventos de aprovação ou rejeição do KYC
Assim como o evento de pendencia, após as análises (que possuem o SLA de até 48h), enviaremos um evento via webhook, com os seguintes cenários:
Em caso de aprovação:
{
"entity": "kyc",
"createTimestamp": "2023-07-26T21:13:04.856Z",
"status": "APPROVED",
"body": {
"clientCode": "416bbac2-47b6-4518-8520-a487aedf0e",
"documentNumber": "85467256084",
"onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e"
}
}
Em caso de negativa:
{
"entity": "kyc",
"createTimestamp": "2023-07-26T15:18:36.210Z",
"status": "REJECTED",
"body": {
"clientCode": "b16e3672-d047-46fa-ad70-ec0c4bf3bf",
"documentNumber": "85467256084",
"onboardingId": "03c2b4e0-6e2c-49e5-ac9b-753d33d5d9df"
}
}
Em caso de pendenciamento: (Casos de pendenciamento ocorrem quando faltou alguma documentação para a análise do KYC, ou seja, é necessário fazer um novo envio com o documento informado no campo "pendingReason".)
{
"entity": "kyc",
"createTimestamp": "2023-07-26T21:13:04.856+00:00",
"status": "PENDING",
"body": {
"clientCode": "416bbac2-47b6-4518-8520-a487aedf0e",
"documentNumber": "85467256084",
"onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e",
"pendingReason": "Motivo da pendencia"
}
Considerações finais
O resultado das análises, tanto da PF quanto da PJ, pode levar até 48h úteis para ser concluída.
Importante
Os retornos das análises do KYC serão direcionados no Webhook disponível na documentação do BaaS. Para mais detalhes sobre os templates, utilize o link recomendado abaixo.
Em casos de reprovação é possível reenviar os documentos pelo mesmo endpoint atual. Após o envio dos documentos, a solicitação terá seu status alterado para "Pendente", e a conta passará por novas análises, podendo ser aprovada ou reprovada. Esta ação implicará em uma nova análise do processo. Os valores de cobrança serão devidamente aplicados conforme os critérios estabelecidos. O reenvio da documentação não garante a aprovação automática do processo de KYC.
Sandbox
No ambiente de sandbox, possuímos o seguinte comportamento:
Caso crie uma conta com final de documento número par, receberá um webhook de approved.
Caso crie uma conta com final de documento ímpar, receberá um webhook de rejected.
Updated 23 days ago