Onboarding

Orientações para clientes que utilizam a nossa solução de Onboarding - KYC.

Introdução

Este documento tem como objetivo apoiar o cliente a compreender a integração com o produto Onboarding - KYC. Nesse documento iremos explicar o Fluxo, a autenticação e os Endpoints da integração. Para utilização destes serviços é necessário realizar a contratação do Onboarding Celcoin junto a solução do BaaS.

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.

👍

Importante

Sandbox

No ambiente de sandbox, possuímos o seguinte comportamento:
Utilize o campo phoneNumber para PF
Utilize o campo contactNumber para PJ

Final do telefone terminando em:
1 - Aprovado em ambos os webhooks e criará a conta (Independente dos demais dados informados)
2 - Reprovado no primeiro webhook (Independente dos demais dados informados)
3 - Aprova a primeira etapa do processo e reprova a segunda. (Independente dos demais dados informados)
Diferente de telefone final terminado em 1, 2 e 3 seguirá com o cenário próximo da realidade (Necessário informar dados reais em casos desse).
OBS: O comportamento respeitará a configuração utilizada para o seu caso, fluxo 1 ou fluxo 2.

Informações importantes para o processo em produção nas Considerações finais

Fluxo de integração Opção 1

É necessário escolher entre uma das opções de Fluxo: Fluxo 1 ou Fluxo 2.

Primeiramente deverá ser feita a coleta dos dados de seu cliente. (Basicamente serão os mesmos dados para criar uma conta via BaaS, conforme pontuado no Tópico de Endpoints), após a coleta de dados de seu cliente, você deverá realizar uma requisição em um dos Endpoints, realizando o método POST. Utilizando o Endpoint proposal/natural-person para caso de contas PF, e utilizando o Endpoint proposal/legal-person para casos de conta PJ.
Após essa requisição, será criada uma proposta e iremos rodar uma política de BackgroundCheck em nosso fornecedor e iremos retornar via Webhook o resultado. Caso seja aprovado, além do webhook com o resultado de “Approved” , iremos retornar um webhook com o Link para a jornada de captura da Selfie, Facematch e envio dos documentos, que deverá ser disponibilizado para o cliente do nosso cliente.
Após o seu cliente completar a jornada disponibilizada via URL, serão realizadas novas validações de políticas, como a Documentoscopia e OCR. Iremos retornar o resultado via Webhook e caso seja aprovado, além do webhook iremos também enviar o webhook de criação de conta do BaaS.

Recomendações Fluxo 1

Recomendamos esse fluxo para clientes que possuem uma jornada faseada do processo de KYC. Realizando. O grande benefício desse fluxo é que caso tenha reprovação na etapa de Backgroundcheck, não será necessário fazer a etapa de documentoscopia para aquela proposta. Caso a sua jornada seja contínua, recomendamos que olhe a documentação do fluxo 2.

Criar propostas

A criação das propostas devem ser realizadas através dos endpoints

🙍‍♂️

Pessoa Física

Se a proposta for para uma pessoa física. (onboarding-proposal/natural-person) endpoint

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/natural-person

Exemplo Request:

{
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
    "documentNumber": "91170215025", //documento
    "phoneNumber": "+5511912345678", // celular
    "email": "[email protected]", //email
    "motherName": "Teste Mãe", //nome da mãe
    "fullName": "Teste teste", //nome completo
    "socialName": "", //nome social
    "birthDate": "31-12-2000", //data de nascimento
    "address": { //Endereço
        "postalCode": "06455030", //CEP
        "street": "Alameda Xingu", //Rua
        "number": "350", //Número
        "addressComplement": "", //Complemento
        "neighborhood": "Alphaville Industrial", //Bairro
        "city": "Barueri", //Cidade
        "state": "SP" //Estado
    },
    "isPoliticallyExposedPerson": false, //Pessoa exposta politicamente
    "onboardingType": "BAAS" //Tipo do Onboarding
}

Exemplo Response:

{
   "body": {
       "proposalId": "1234cee7-cf18-44d6-ad9c-5a33cd45b9a0", //número da proposta criada
       "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
       "documentNumber": "91170215025" //documento
   },
   "version": "1.0.0", //versão
   "status": "PROCESSING" //status da proposta
}

🏛️

Pessoa Jurídica

Se a proposta for para uma pessoa jurídica. (onboarding-proposal/legal-person) endpoint

É importante informar todos os sócios do Quadro Societário da empresa, ou pelo menos os que possuem participação societária maior ou igual a 25%.

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/legal-person

Exemplo Request:

{
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
    "contactNumber": "+5511912345678", // celular
    "documentNumber": "87649940000194", //cnpj empresa
    "businessEmail": "[email protected]", //email empresa
    "businessName": "Celcoin", //nome fantasia
    "tradingName": "Celcoin Instituição de Pagamento", //razão social
    "companyType": "PJ", //tipo da empresa. Utilizar MEI,ME ou PJ
    "owner": [
        {
            "ownerType": "SOCIO", //Utilizar Socio, representante ou demais socios
            "documentNumber": "72352781027", //documento
            "fullName": "Nome Teste", //nome completo
            "phoneNumber": "+5511912345128", //celular
            "email": "[email protected]", //email
            "motherName": "Nome Mae", //nome da mãe
            "socialName": "Nome", //nome social
            "birthDate": "02-02-1990", //data de nascimento
            "address": { //Endereço
                "postalCode": "06455030", //CEP
                "street": "Alameda Xingu", //Rua
                "number": "50", //número
                "addressComplement": "", //Complemento
                "neighborhood": "Alphaville Industrial", //Bairro
                "city": "Barueri", //Cidade
                "state": "SP" //Estado
            },
            "isPoliticallyExposedPerson": false //Pessoa exposta politicamente
        }
    ],
    "businessAddress": { //Endereço Comercial
        "postalCode": "06455030", //CEP
        "street": "Alamed Xingu", //Rua
        "number": "350", //número
        "addressComplement": "", //Complemento
        "neighborhood": "Alphaville Industrial", //Bairro
        "city": "Barueri", //Cidade
        "state": "SP" //Estado
    },
    "onboardingType": "BAAS" //Tipo do Onboarding
}

No atributo “ownerType” deverá ser informado uma das opções: “SOCIO” OU “REPRESENTANTE”. Para casos onde existe mais de um sócio, utilize a opção "SOCIO" para o primeiro Sócio e a opção “DEMAIS_SOCIOS” para os demais. Caso seja informado REPRESENTANTE no Webview será obrigatório a inclusão da Procuração de Poderes.
No atributo CompanyType deverá ser informado o tipo de empresa MEI,ME ou PJ. Em caso de dúvidas, é imprescindível questionar ao cliente, pois impactará na jornada de KYC.

Exemplo Response:

{
    "body": {
        "proposalId": "c3216c8a-df23-450b-92d5-48b0c89c8791", //número da proposta
        "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
        "documentNumber": "13935893000109" //documento
    },
    "version": "1.0.0", //versão
    "status": "PROCESSING" //status proposta
}

Consultar propostas

É possível consultar as propostas criadas e seus status utilizando o seguinte endpoint

É possível utilizar os seguintes filtros:
• Data início e data fim (Obrigatório caso não inclua o nº da proposta)
• Status proposta
• DocumentNumber
• Nº Proposta

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal

Exemplo Request:

onboarding-proposal?dateFrom=2024-02-03T06:30:00&dateTo=2024-03-25T06:30:00

Exemplo Response:

{
    "body": {
        "limit": 200,
        "currentPage": 1,
        "limitPerPage": 200,
        "totalPages": 1,
        "proposal": [
            {
                "proposalId": "8cf4b988-a2f7-4f48-9075-384ca287d993", //número da proposta
                "clientCode": "8904ec29-cf6b-42ea-b8a5-b12aa58b80d2", //código cliente
                "documentNumber": "43512350800", //documento atrelado a proposta
                "status": "RESOURCE_CREATED", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:58:50.073Z", //data de criação da proposta
                "updatedAt": "2024-03-13T14:59:15.512Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43512350800", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/3214bf523eeeb818894ee575e284d8b6", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:58:52.957Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T14:59:20.01Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "253942c5-dbdc-4d1f-b985-28a727d56b81", //número da proposta
                "clientCode": "60a1f00a-b72f-4e99-b7e6-6a59ccf884f7", //código cliente
                "documentNumber": "43561230800", //documento atrelado a proposta
                "status": "PENDING_DOCUMENTSCOPY", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:59:34.142Z", //data de criação da proposta
                "updatedAt": "2024-03-13T15:00:08.856Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43561230800", //número do documento
                        "status": "PENDING", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c923e78", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:59:34.716Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T15:00:09.897Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "7b4bbe6d-d156-4297-b7cc-3db2ba2b5cdc", //número da proposta
                "clientCode": "4cd7589f-a3d1-45c3-8418-9dd86439432c", //código cliente
                "documentNumber": "32113434101", //documento atrelado a proposta
                "status": "RESOURCE_ERROR", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T16:58:13.215Z", //data de criação da proposta
                "updatedAt": "2024-03-13T16:59:15.771Z", //data de atualização
                "rejectedReason":{ //motivo da reprovação ao criar a conta
                  "errorCode": "CBE123", //código de erro BaaS
                  "message": "error message." //mensagem de erro
                },
                "documentscopys": [
                    {
                        "documentNumber": "91513434101", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c913e98", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T16:58:14.547Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T18:58:14.547Z" //data de atualização da documentoscopia
                    }
                ]
            
            }
        ]
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Buscar documentos

É possível buscar os documentos associados as propostas através do endpoint

É possível utilizar os seguintes filtros:
• Nº Proposta (ProposalId)
• ClientCode

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: As URLs retornadas possuem duração de 15minutos, após a expiração é necessário realizar uma nova chamada.

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/files

Exemplo Request:

onboarding-proposal/files?ProposalId=3257b215-bef9-402b-a779-104441b520b4

Exemplo Response:

{
  "body": {
    "proposalId": "3d81a091-1023-48c2-8a10-f5307a6c06ef",
    "clientCode": "28c6d5f9-8dbc-4192-80c0-ad7d757f99d1",
    "documentNumber": "52154397000170",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "files": [
      {
        "type": "CNH_FRONT",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_CNH_FRONT.jpg?sv=2023-11-03&se=2024-05-02T20%3A24%3A07Z&sr=b&sp=r&sig=SSAlANYbRSmrQ7vxO%2BRhd46WIJxmRSwQjfORLwCDmMk%3D",
        "expirationTime": "2024-05-02T17:24:07Z"
      },
      {
        "type": "SELFIE",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_SELFIE.png?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=5VDYJ%2B8ampW%2Bwn5UplNpEiAMXhwdI%2B%2BM34tWuuCVYJ0%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      },
      {
        "type": "CONTRATO_SOCIAL",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_CONTRATO_SOCIAL.pdf?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=ainZ0FEJkNfhdg%2FMXqyokBXZb5pWuO5rycHI593Y3i8%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      }
    ],
    "createTimestamp": "2024-05-02T17:09:08Z",
    "entity": "onboarding-file"
  },
  "webhookId": "f57d7b86-49f3-430e-b870-e0f48555e7c1"
}

Buscar tagueamento jornada webview

É possível buscar os dados referentes a jornada Webview através do endpoint
Através do retorno é possível identificar em qual etapa da jornada o usuário parou o processo de envio dos documentos e selfie.

É possível utilizar os seguintes filtros:
• Nº Proposta (ProposalId)
• ClientCode

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: Os dados retornados possuem um pequeno delay para retornar no endpoint, após o abandono/conclusão da jornada. Temos uma limitação de 10 requests por minuto por proposta.

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/tagging-journey

Exemplo Request:

onboarding-proposal/tagging-journey?ProposalId=3257b215-bef9-402b-a779

{
  "version": "1.0.0", //versão
  "status": "SUCCESS", //status
  "body": {
    "proposalId": "12334dfb-4c4e-43fb-ad93-fa28e3123473", //número da proposta
    "clientCode": "1234ab7c-2855-436b-9d19-8abcdc198e984",  //clientCode atrelado a proposta
    "documentNumber": "12345678", //documento atrelado a proposta
    "status": "COMPLETED", //status da jornada
    "link": "https://cadastro.io/e32b99c477a00171716aas", //link do webview
    "totalDevices": 1, //total dispositivos
    "devices": [ //dispositivos
      {
        "browser": { //navegador
          "name": "Chrome", 
          "version": "126.0.0.0"
        },
        "os": {
          "name": "Android", //sistema operacional
          "version": "10",
          "versionname": "10.1.0"
        },
        "platform": { //plataforma
          "type": "Crowdfunding",
          "vendor": "Crowdcube",
          "model": "Equity-Based"
        },
        "engine": { //motor do browser
          "name": "Google",
          "version": "126.0.0.0"
        },
        "useragent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36"
      }
    ],
    "lastStep": { //última etapa da jornada
      "timestamp": "2024-07-25 18:19:54.11", //horário que iniciou a etapa
      "stepName": "STEP_DONE-1", //nome da etapa
      "deviceBrowserName":"", 
      "deviceOsName":"",
      "deviceOsVersion":"",
      "devicePlatformType":"",
      "secondsFromPrevious": -32, //tempo na etapa anterior
      "secondsFromNext": 1 //tempo na etapa informada
    },
    "stepsArray": [
      {
        "timestamp": "2024-07-25 18:19:54.11",
        "stepName": "STEP_DONE-1",
        "deviceBrowserName":"",
        "deviceOsName":"",
        "deviceOsVersion":"",
        "devicePlatformType":"",
        "secondsFromPrevious": -32,
        "secondsFromNext": 1
      }
    ]
  }
}

Eventos da jornada do KYC

Evento: onboarding-backgroundcheck

Evento que informa o status do processo de Backgroundcheck.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "PENDING",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Em caso de aprovação ou reprovação do Backgroundcheck. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252jj",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T18:02:10Z",
  "entity": "onboarding-backgroundcheck",
  "status": "APPROVED",
  "webhookId": "dce44989-dd518-4abe-85ec-9c863cf39295"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "REPROVED",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Evento: onboarding-documentscopy

Evento que informa o status do processo de Documentoscopia.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "urlDocumentscopy": "https://celcoin.beta.cadastro.io/a1258b5d8212d80f360139418e7d5123"
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PENDING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

O campo “urlDocumentscopy” consiste no link com a jornada para a captura dos documentos do seu cliente e também a captura da selfie. A URL não possui tempo de expiração.

Quando o cliente finalizar a jornada da URL
Status = Processing

//Exemplo Processing
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PROCESSING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

Em caso de aprovação ou reprovação da Documentoscopia. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "APPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "REPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

Evento: webhook onboarding-file

Evento que envia a URL que contém os documentos enviados pelo cliente na jornada. Esse evento será enviado após o webhook onboarding-documentscopy com status Processing.

Para saber quais os tipos de documentos possíveis consulte a tabela de apoio no final da documentação.

{
  "body": {
    "proposalId": "3d81a091-1023-48c2-8a10-f5307a6c12ef",
    "clientCode": "28c6d5f9-8dbc-4192-80c0-ad7d757f12d1",
    "documentNumber": "52154397000170",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "files": [
      {
        "type": "CNH_FRONT",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_CNH_FRONT.jpg?sv=2023-11-03&se=2024-05-02T20%3A24%3A07Z&sr=b&sp=r&sig=SSAlANYbRSmrQ7vxO%2BRhd46WIJxmRSwQjfORLwCDmMk%3D",
        "expirationTime": "2024-05-02T17:24:07Z"
      },
      {
        "type": "SELFIE",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_SELFIE.png?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=5VDYJ%2B8ampW%2Bwn5UplNpEiAMXhwdI%2B%2BM34tWuuCVYJ0%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      },
      {
        "type": "CONTRATO_SOCIAL",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_CONTRATO_SOCIAL.pdf?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=ainZ0FEJkNfhdg%2FMXqyokBXZb5pWuO5rycHI593Y3i8%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      }
    ],
    "createTimestamp": "2024-05-02T17:09:08Z",
    "entity": "onboarding-file"
  },
  "webhookId": "f57d7b86-49f3-430e-b870-e0f48555e7c1"
}

Evento: onboarding-proposal

Resultado da proposta, status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "APPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "bb3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[ //motivo da reprovação
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "REPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

Após a aprovação da proposta, uma conta com os dados respectivos será criada no BaaS e o Webhook do BaaS irá retornar as informações.

Evento: onboarding-create

Criação da conta no BaaS

O Status será sempre CONFIRMED ou ERROR caso ocorra algum erro na criação.

O onboardingId retornado nesse webhook é o mesmo dado do proposalId.

{
  "entity": "onboarding-create",
  "createTimestamp": "2022-11-04T10:35:16.0511474",
  "status": "CONFIRMED",
  "body": {
    "account": {
      "branch": "0001", //agência da conta
      "account": "30053912934", //número da conta
      "name": "Ms. Rodolfo Marvin",
      "documentNumber": "86913161280"
    },
    "onboardingId": "1e39442d-270f-4f9a-b752-9c08456c6e14", //será o mesmo dado do proposalId
    "clientCode": "1f8ff32f-2d1f-4c28-b316-8020b3d13d43",
    "createDate": "2022-11-04T10:35:16.0511474"
  }
}

Fluxo de integração Opção 2

É necessário escolher entre uma das opções de Fluxo: Fluxo 1 ou Fluxo 2.

Primeiramente deverá ser feita a coleta dos dados de seu cliente. (Basicamente serão os mesmos dados para criar uma conta via BaaS, conforme pontuado no Tópico de Endpoints), após a coleta de dados de seu cliente, você deverá realizar uma requisição em um dos Endpoints, realizando o método POST. Utilizando o Endpoint proposal/natural-person para caso de contas PF, e utilizando o Endpoint proposal/legal-person para casos de conta PJ.
Após essa requisição, será criada uma proposta e após processamentos internos, será retornado a URL da jornada (Via Webhook) que deverá ser disponibilizada para o seu cliente realizar a captura da Selfie, Facematch e envio dos documentos.
Após o seu cliente completar a jornada disponibilizada via URL, será disparado um webhook informando que a jornada foi concluída, e iremos rodar nossas políticas de KYC, como a Documentoscopia,OCR e BackgroundCheck. Iremos retornar o resultado da proposta via Webhook e caso seja aprovado/reprovado, além dos webhooks da proposta iremos também enviar o webhook de criação de conta do BaaS. As contas no BaaS serão criadas apenas em caso de aprovação das propostas.

Recomendações Fluxo 2

Recomendamos esse fluxo para clientes que possuem uma jornada contínua do processo de KYC. Nesse fluxo é realizado a Documentoscopia primeiro e depois o Backgroundcheck. Caso a sua jornada seja faseada, recomendamos que olhe a documentação do fluxo 1.

Criar propostas

A criação das propostas devem ser realizadas através dos endpoints

🙍‍♂️

Pessoa Física

Se a proposta for para uma pessoa física. (onboarding-proposal/natural-person) endpoint

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/natural-person

Exemplo Request:

{
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
    "documentNumber": "91170215025", //documento
    "phoneNumber": "+5511912345678", // celular
    "email": "[email protected]", //email
    "motherName": "Teste Mãe", //nome da mãe
    "fullName": "Teste teste", //nome completo
    "socialName": "", //nome social
    "birthDate": "31-12-2000", //data de nascimento
    "address": { //Endereço
        "postalCode": "06455030", //CEP
        "street": "Alameda Xingu", //Rua
        "number": "350", //Número
        "addressComplement": "", //Complemento
        "neighborhood": "Alphaville Industrial", //Bairro
        "city": "Barueri", //Cidade
        "state": "SP" //Estado
    },
    "isPoliticallyExposedPerson": false, //Pessoa exposta politicamente
    "onboardingType": "BAAS" //Tipo do Onboarding
}

Exemplo Response:

{
   "body": {
       "proposalId": "1234cee7-cf18-44d6-ad9c-5a33cd45b9a0", //número da proposta criada
       "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
       "documentNumber": "91170215025" //documento
   },
   "version": "1.0.0", //versão
   "status": "PROCESSING" //status da proposta
}

🏛️

Pessoa Jurídica

Se a proposta for para uma pessoa jurídica. (onboarding-proposal/legal-person) endpoint

É importante informar todos os sócios do Quadro Societário da empresa, ou pelo menos os que possuem participação societária maior ou igual a 25%.

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/legal-person

Exemplo Request:

{
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
    "contactNumber": "+5511912345678", // celular
    "documentNumber": "87649940000194", //cnpj empresa
    "businessEmail": "[email protected]", //email empresa
    "businessName": "Celcoin", //nome fantasia
    "tradingName": "Celcoin Instituição de Pagamento", //razão social
    "companyType": "PJ", //tipo da empresa. Utilizar MEI,ME ou PJ
    "owner": [
        {
            "ownerType": "SOCIO", //Utilizar Socio, representante ou demais socios
            "documentNumber": "72352781027", //documento
            "fullName": "Nome Teste", //nome completo
            "phoneNumber": "+5511912345128", //celular
            "email": "[email protected]", //email
            "motherName": "Nome Mae", //nome da mãe
            "socialName": "Nome", //nome social
            "birthDate": "02-02-1990", //data de nascimento
            "address": { //Endereço
                "postalCode": "06455030", //CEP
                "street": "Alameda Xingu", //Rua
                "number": "50", //número
                "addressComplement": "", //Complemento
                "neighborhood": "Alphaville Industrial", //Bairro
                "city": "Barueri", //Cidade
                "state": "SP" //Estado
            },
            "isPoliticallyExposedPerson": false //Pessoa exposta politicamente
        }
    ],
    "businessAddress": { //Endereço Comercial
        "postalCode": "06455030", //CEP
        "street": "Alamed Xingu", //Rua
        "number": "350", //número
        "addressComplement": "", //Complemento
        "neighborhood": "Alphaville Industrial", //Bairro
        "city": "Barueri", //Cidade
        "state": "SP" //Estado
    },
    "onboardingType": "BAAS" //Tipo do Onboarding
}

No atributo “ownerType” deverá ser informado uma das opções: “SOCIO” OU “REPRESENTANTE”. Para casos onde existe mais de um sócio, utilize a opção "SOCIO" para o primeiro Sócio e a opção “DEMAIS_SOCIOS” para os demais. Caso seja informado REPRESENTANTE no Webview será obrigatório a inclusão da Procuração de Poderes.
No atributo CompanyType deverá ser informado o tipo de empresa MEI,ME ou PJ. Em caso de dúvidas, é imprescindível questionar ao cliente, pois impactará na jornada de KYC.

Exemplo Response:

{
    "body": {
        "proposalId": "c3216c8a-df23-450b-92d5-48b0c89c8791", //número da proposta
        "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
        "documentNumber": "13935893000109" //documento
    },
    "version": "1.0.0", //versão
    "status": "PROCESSING" //status proposta
}

Consultar propostas

É possível consultar as propostas criadas e seus status utilizando o seguinte endpoint

É possível utilizar os seguintes filtros:
• Data início e data fim (Obrigatório caso não inclua o nº da proposta)
• Status proposta
• DocumentNumber
• Nº Proposta

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal

Exemplo Request:

onboarding-proposal?dateFrom=2024-02-03T06:30:00&dateTo=2024-03-25T06:30:00

Exemplo Response:

{
    "body": {
        "limit": 200,
        "currentPage": 1,
        "limitPerPage": 200,
        "totalPages": 1,
        "proposal": [
            {
                "proposalId": "8cf4b988-a2f7-4f48-9075-384ca287d993", //número da proposta
                "clientCode": "8904ec29-cf6b-42ea-b8a5-b12aa58b80d2", //código cliente
                "documentNumber": "43512350800", //documento atrelado a proposta
                "status": "RESOURCE_CREATED", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:58:50.073Z", //data de criação da proposta
                "updatedAt": "2024-03-13T14:59:15.512Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43512350800", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/3214bf523eeeb818894ee575e284d8b6", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:58:52.957Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T14:59:20.01Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "253942c5-dbdc-4d1f-b985-28a727d56b81", //número da proposta
                "clientCode": "60a1f00a-b72f-4e99-b7e6-6a59ccf884f7", //código cliente
                "documentNumber": "43561230800", //documento atrelado a proposta
                "status": "PENDING_DOCUMENTSCOPY", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:59:34.142Z", //data de criação da proposta
                "updatedAt": "2024-03-13T15:00:08.856Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43561230800", //número do documento
                        "status": "PENDING", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c923e78", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:59:34.716Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T15:00:09.897Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "7b4bbe6d-d156-4297-b7cc-3db2ba2b5cdc", //número da proposta
                "clientCode": "4cd7589f-a3d1-45c3-8418-9dd86439432c", //código cliente
                "documentNumber": "32113434101", //documento atrelado a proposta
                "status": "RESOURCE_ERROR", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T16:58:13.215Z", //data de criação da proposta
                "updatedAt": "2024-03-13T16:59:15.771Z", //data de atualização
                "rejectedReason":{ //motivo da reprovação ao criar a conta
                  "errorCode": "CBE123", //código de erro BaaS
                  "message": "error message." //mensagem de erro
                },
                "documentscopys": [
                    {
                        "documentNumber": "91513434101", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c913e98", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T16:58:14.547Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T18:58:14.547Z" //data de atualização da documentoscopia
                    }
                ]
            
            }
        ]
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Buscar documentos

É possível buscar os documentos associados as propostas através do endpoint

É possível utilizar os seguintes filtros:
• Nº Proposta (ProposalId)
• ClientCode

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: As URLs retornadas possuem duração de 15minutos, após a expiração é necessário realizar uma nova chamada.

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/files

Exemplo Request:

onboarding-proposal/files?ProposalId=3257b215-bef9-402b-a779-104441b520b4

Exemplo Response:

{
  "body": {
    "proposalId": "3d81a091-1023-48c2-8a10-f5307a6c06ef",
    "clientCode": "28c6d5f9-8dbc-4192-80c0-ad7d757f99d1",
    "documentNumber": "52154397000170",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "files": [
      {
        "type": "CNH_FRONT",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_CNH_FRONT.jpg?sv=2023-11-03&se=2024-05-02T20%3A24%3A07Z&sr=b&sp=r&sig=SSAlANYbRSmrQ7vxO%2BRhd46WIJxmRSwQjfORLwCDmMk%3D",
        "expirationTime": "2024-05-02T17:24:07Z"
      },
      {
        "type": "SELFIE",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_SELFIE.png?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=5VDYJ%2B8ampW%2Bwn5UplNpEiAMXhwdI%2B%2BM34tWuuCVYJ0%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      },
      {
        "type": "CONTRATO_SOCIAL",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c06ef/52154397000170_6633e343bfe9a000089a10ce_CONTRATO_SOCIAL.pdf?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=ainZ0FEJkNfhdg%2FMXqyokBXZb5pWuO5rycHI593Y3i8%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      }
    ],
    "createTimestamp": "2024-05-02T17:09:08Z",
    "entity": "onboarding-file"
  },
  "webhookId": "f57d7b86-49f3-430e-b870-e0f48555e7c1"
}

Buscar tagueamento jornada webview

É possível buscar os dados referentes a jornada Webview através do endpoint
Através do retorno é possível identificar em qual etapa da jornada o usuário parou o processo de envio dos documentos e selfie.

É possível utilizar os seguintes filtros:
• Nº Proposta (ProposalId)
• ClientCode

Também é possível utilizar ambos os filtros, porém caso um dos parâmetros estejam errados não irá retornar nada.

Observação: Os dados retornados possuem um pequeno delay para retornar no endpoint, após o abandono/conclusão da jornada. Temos uma limitação de 10 requests por minuto por proposta.

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/tagging-journey

Exemplo Request:

onboarding-proposal/tagging-journey?ProposalId=3257b215-bef9-402b-a779

{
  "version": "1.0.0", //versão
  "status": "SUCCESS", //status
  "body": {
    "proposalId": "12334dfb-4c4e-43fb-ad93-fa28e3123473", //número da proposta
    "clientCode": "1234ab7c-2855-436b-9d19-8abcdc198e984",  //clientCode atrelado a proposta
    "documentNumber": "12345678", //documento atrelado a proposta
    "status": "COMPLETED", //status da jornada
    "link": "https://cadastro.io/e32b99c477a00171716aas", //link do webview
    "totalDevices": 1, //total dispositivos
    "devices": [ //dispositivos
      {
        "browser": { //navegador
          "name": "Chrome", 
          "version": "126.0.0.0"
        },
        "os": {
          "name": "Android", //sistema operacional
          "version": "10",
          "versionname": "10.1.0"
        },
        "platform": { //plataforma
          "type": "Crowdfunding",
          "vendor": "Crowdcube",
          "model": "Equity-Based"
        },
        "engine": { //motor do browser
          "name": "Google",
          "version": "126.0.0.0"
        },
        "useragent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Mobile Safari/537.36"
      }
    ],
    "lastStep": { //última etapa da jornada
      "timestamp": "2024-07-25 18:19:54.11", //horário que iniciou a etapa
      "stepName": "STEP_DONE-1", //nome da etapa
      "deviceBrowserName":"", 
      "deviceOsName":"",
      "deviceOsVersion":"",
      "devicePlatformType":"",
      "secondsFromPrevious": -32, //tempo na etapa anterior
      "secondsFromNext": 1 //tempo na etapa informada
    },
    "stepsArray": [
      {
        "timestamp": "2024-07-25 18:19:54.11",
        "stepName": "STEP_DONE-1",
        "deviceBrowserName":"",
        "deviceOsName":"",
        "deviceOsVersion":"",
        "devicePlatformType":"",
        "secondsFromPrevious": -32,
        "secondsFromNext": 1
      }
    ]
  }
}

Eventos da jornada do KYC

Evento: onboarding-documentscopy

Evento que informa o status do processo de Documentoscopia.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "urlDocumentscopy": "https://celcoin.beta.cadastro.io/a1258b5d8212d80f360139418e7d5123"
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PENDING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

O campo “urlDocumentscopy” consiste no link com a jornada para a captura dos documentos do seu cliente e também a captura da selfie. A URL não possui tempo de expiração.

Quando o cliente finalizar a jornada da URL
Status = Processing

//Exemplo Processing
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PROCESSING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

Em caso de aprovação ou reprovação da Documentoscopia. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "APPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "REPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

Evento: webhook onboarding-file

Evento que envia a URL que contém os documentos enviados pelo cliente na jornada. Esse evento será enviado após o webhook onboarding-documentscopy com status Processing.

Para saber quais os tipos de documentos possíveis consulte a tabela de apoio no final da documentação.

Observação: As URLs retornadas possuem duração de 15minutos, após a expiração é necessário realizar uma nova chamada através do Endpoint de Buscar Arquivos.

{
  "body": {
    "proposalId": "3d81a091-1023-48c2-8a10-f5307a6c12ef",
    "clientCode": "28c6d5f9-8dbc-4192-80c0-ad7d757f12d1",
    "documentNumber": "52154397000170",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "files": [
      {
        "type": "CNH_FRONT",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_CNH_FRONT.jpg?sv=2023-11-03&se=2024-05-02T20%3A24%3A07Z&sr=b&sp=r&sig=SSAlANYbRSmrQ7vxO%2BRhd46WIJxmRSwQjfORLwCDmMk%3D",
        "expirationTime": "2024-05-02T17:24:07Z"
      },
      {
        "type": "SELFIE",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_SELFIE.png?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=5VDYJ%2B8ampW%2Bwn5UplNpEiAMXhwdI%2B%2BM34tWuuCVYJ0%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      },
      {
        "type": "CONTRATO_SOCIAL",
        "url": "https://onboardingexterno.blob.core.windows.net/onboarding/HML/123/52154397000170/3d81a091-1023-48c2-8a10-f5307a6c12ef/52154397000170_6633e343bfe9a000089a10ce_CONTRATO_SOCIAL.pdf?sv=2023-11-03&se=2024-05-02T20%3A24%3A08Z&sr=b&sp=r&sig=ainZ0FEJkNfhdg%2FMXqyokBXZb5pWuO5rycHI593Y3i8%3D",
        "expirationTime": "2024-05-02T17:24:08Z"
      }
    ],
    "createTimestamp": "2024-05-02T17:09:08Z",
    "entity": "onboarding-file"
  },
  "webhookId": "f57d7b86-49f3-430e-b870-e0f48555e7c1"
}

Evento: onboarding-backgroundcheck

Evento que informa o status do processo de Backgroundcheck.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "PENDING",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Em caso de aprovação ou reprovação do Backgroundcheck. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252jj",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T18:02:10Z",
  "entity": "onboarding-backgroundcheck",
  "status": "APPROVED",
  "webhookId": "dce44989-dd518-4abe-85ec-9c863cf39295"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "REPROVED",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Evento: onboarding-proposal

Resultado da proposta, status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "APPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "bb3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "rejectedReason":[ //motivo da reprovação
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "REPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

Após a aprovação da proposta, uma conta com os dados respectivos será criada no BaaS e o Webhook do BaaS irá retornar as informações.

Evento: onboarding-create

Criação da conta no BaaS

O Status será sempre CONFIRMED ou ERROR caso ocorra algum erro na criação.

O onboardingId retornado nesse webhook é o mesmo dado do proposalId.

{
  "entity": "onboarding-create",
  "createTimestamp": "2022-11-04T10:35:16.0511474",
  "status": "CONFIRMED",
  "body": {
    "account": {
      "branch": "0001", //agência da conta
      "account": "30053912934", //número da conta
      "name": "Ms. Rodolfo Marvin",
      "documentNumber": "86913161280"
    },
    "onboardingId": "1e39442d-270f-4f9a-b752-9c08456c6e14", //será o mesmo dado do proposalId
    "clientCode": "1f8ff32f-2d1f-4c28-b316-8020b3d13d43",
    "createDate": "2022-11-04T10:35:16.0511474"
  }
}

Integração com o Webview

Esta seção oferecerá suporte à integração do WebView, a jornada que o seu cliente envia os documentos.

Recomendamos a utilização do Webview nos seguintes navegadores: Google Chrome, Mozilla Firefox e Safari.

Android

Para que as integrações para Android funcionem corretamente, é necessário que setDomStorageEnabled esteja definido como true. Exemplo abaixo:

myWebView.getSettings().setDomStorageEnabled(true);

iOS

Para que as integrações para iOS funcionem corretamente, é necessário customizar a configuração para permitir a reprodução de mídia sem solicitação de ação do usuário e para reproduzir a mídia. Exemplo abaixo:

let webView: WKWebView

init() {
    let audioVisualMediaType: WKAudiovisualMediaTypes = []
    let configuration = WKWebViewConfiguration()
    configuration.mediaTypesRequiringUserActionForPlayback = audioVisualMediaType
    configuration.allowsInlineMediaPlayback = true

    webView = WKWebView(frame: .zero, configuration: configuration)
}

Outras plataformas

Em outras plataformas, por exemplo, Flutter e React Native, você deve procurar as configurações do WebView para permitir a reprodução de mídia sem exigir gestos do usuário e para reproduzir o vídeo da câmera inline, não no controlador nativo de tela cheia.

Tabelas para apoio


Documentos obrigatórios


TipoDocumentos Obrigatórios
PF• RG ou CNH ou RNE
• Selfie
PJ• RG ou CNH ou RNE
• Selfie
• Contrato Social
OBS: Em caso de Representante é obrigatório a procuração de poderes.
ME• RG ou CNH ou RNE
• Selfie
MEI• RG ou CNH ou RNE
• Selfie

Parâmetro, possíveis valores e significado

ParâmetroPossíveis valoresSignificado
proposalTypePF ou PJTipo de proposta, se é pessoa física ou pessoa jurídica.
companyTypePJ, MEI ou METipo de empresa. (Utilizado para proposalType = PJ)
ownerTypeSOCIO, REPRESENTANTE ou DEMAIS_SOCIOSTipo de pessoa atrelado ao quadro societário.
isPoliticallyExposedPersonTrue ou FalseSe a pessoa informada na proposta é politicamente exposta.
onboardingTypeBAASTipo de Onboarding. (Por agora única opção disponível BAAS)
fileTypeCNH_FRONT, CNH_BACK, RG_FRONT, RG_BACK, RNE_FRONT, RNE_BACK, CONTRATO_SOCIAL, DOCUMENTO_FINANCEIRO, PROCURACAO_PODERES, SELFIETipo de arquivo enviado pelo cliente.

Entidades, possíveis status e significado do status

EntidadeStatusSignificado
Proposal StatusCreatedProposta criada.
Proposal StatusPendingPendente Backgroundcheck (Nesse Status está sendo feito o backgroundcheck).
Proposal StatusPending_DocumentscopyPendente Documentoscopia (Nesse Status está pendente a realização do envio dos documentos por parte do seu cliente via jornada).
Proposal StatusProcessing_DocumentscopyProcessando a Documentoscopia (Nesse Status seu cliente já finalizou a jornada e estamos processando as informações enviadas).
Proposal StatusReprovedProposta reprovada.
Proposal StatusResource_errorErro ao criar a conta no BaaS.
Proposal StatusResource_CreatedProposta aprovada e conta criada no BaaS.
Documentscopys StatusCreatedDocumentoscopia criada.
Documentscopys StatusPendingPendente Documentoscopia (Nesse Status está pendente a realização do envio dos documentos por parte do seu cliente via jornada).
Documentscopys StatusProcessingProcessando a Documentoscopia (Nesse Status seu cliente já finalizou a jornada e estamos processando as informações enviadas).
Documentscopys StatusReprovedDocumentoscopia reprovada.
Documentscopys StatusApprovedDocumentoscopia aprovada.

Regras Campos

CampoRegrasTamanho máximo
NameRegex = ("^([A-Za-zÀ-ÖØ-öø-ÿ' -]+)$"));120 caracteres
BusinessNameRegex = ("^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\\$%\d' -]+)$"));350 caracteres

Tabela de erros

CódigoMensagem
OBE001Token de autorização não enviado.
OBE002Token enviado está no formato incorreto.
OBE003Token inválido.
OBE004Token expirado.
OBE005Usuario não encontrado.
OBE006Cliente não possui produto Onboarding ativo.
OBE007O campo clientCode é obrigatório.
OBE008O campo documentNumber é obrigatório e deve ser um CPF válido.
OBE009O campo documentNumber é obrigatório e deve ser um CNPJ válido.
OBE010O campo phoneNumber ou contactNumber é obrigatório e deve ser um telefone válido.
OBE011O campo email é obrigatório e deve ser um email válido.
OBE012O campo motherName é obrigatório e deve ser completo.
OBE013O campo fullName é obrigatório e deve ser completo.
OBE014O campo fullName possui tamanho máximo de 120 caracteres.
OBE015socialName inválido.
OBE016O campo birthDate é obrigatório e deve ser no formato (DD-MM-YYYY).
OBE017O campo address é obrigatório.
OBE018O campo onboardingType é obrigatório e deve conter um tipo válido.
OBE019O campo postalCode é obrigatório e deve ser um CEP existente.
OBE020O campo street é obrigatório deve respeitar o limite de caracteres e conter um formato de texto válido.
OBE021Number inválido.
OBE022AddressComplement inválido.
OBE023O campo neighborhood é obrigatório e deve conter um formato de texto válido.
OBE024O campo city é obrigatório e deve conter um formato de texto válido.
OBE025O campo state é obrigatório e deve ser uma estado valido.
OBE026O campo businessEmail é obrigatório e deve ser um email válido.
OBE027O campo businessName é obrigatório e deve conter um formato de texto válido.
OBE028O campo tradingName é obrigatório deve respeitar o limite de caracteres e conter um formato de texto válido.
OBE029O campo owner.documentNumber é obrigatório e deve ser um CPF ou CNPJ válido.
OBE030O campo owner.name é obrigatório e deve ser completo.
OBE031O campo owner.email é obrigatório e deve ser um email válido.
OBE032O campo owner.address é obrigatório.
OBE033Cadastro não permitido para menores de idade.
OBE034Formato do JSON esta fora do padrão. Verifique a documentação.
OBE035Não foi possivel realizar essa operação. Tente novamente mais tarde.
OBE036CompanyType inválido.
OBE037O campo Owners deve conter um array de no mínimo 1 e máximo 10.
OBE038Owners não podem ser duplicados.
OBE039O campo businessAddress é obrigatório.
OBE040O campo ownerType é obrigatório e deve conter um valor válido.
OBE041BackgroundCheck não encontrado ou com status diferente de pendente.
OBE042Erro ao atualizar backgroundCheck.
OBE043Documentscopy não encontrado ou com status diferente de pendente.
OBE044Erro ao atualizar documentscopy.
OBE045Status da proposta inexistente verifique a documentação por favor.
OBE046Data inválida.
OBE047Limite inserido inválido. Os campos limit ou limitPerPage devem ter valores entre 1 e 200.
OBE048O campo documentNumber deve ser um CPF ou CNPJ válido.
OBE049Não foi encontrada nenhuma proposta referente aos dados informados.
OBE050A data inicial não pode ser maior que a data final.
OBE051Ao não enviar o proposalId os campos data inicial e a data final são obrigatórios.
OBE052O intervalo de dias entre a data inicial e a data final não deve ser maior que {0} dias.
OBE053O campo ownerType deve conter pelo menos um sócio ou representante
OBE054ProposalId e clientCode não enviados. Ao menos um desses parametros deve ser enviado.
OBE055Não foram encontrados arquivos para o proposalId ou clientCode informado(s).
OBE056Não foram encontradas documentoscopias referentes ao proposalId ou clientCode enviado.
OBE057Ocorreu um erro ao buscar documentos.
OBE058ClientType inválido.
OBE059SourceType inválido.
OBE060O campo clientId é obrigatório.
OBE061Source inválido.
OBE062ClientCode já vinculado a outra proposta, esse campo deve ser único por proposta.
OBE063Não foram encontrados registros para a sua requisição.
OBE064Já existe uma proposta em aberto para esse documentNumber.
OBE065O campo dateFrom é obrigatório.
OBE066O campo dateTo é obrigatório.
OBE067O campo partner.partnerName deve conter um valor válido.
OBE068O campo partner.parameter deve ser preenchido.
OBE069Ao enviar os campos partner.parameters, o campo partner.partnerName deve ser obrigatório.
OBE070Não foram encontrados dados, pois o usuário ainda não iniciou a jornada webview. Tente novamente mais tarde.
OBE071Ocorreu um erro ao consultar parceiro. Favor tentar novamente mais tarde.
OIE999Ocorreu um erro interno durante a chamada da api

Customização

📚

Customização da jornada

A jornada disponibilizada via URL é passível de customização, permitindo incluir cores e a logo da sua empresa, para solicitar a customização é necessário abrir um chamado no suporte e enviar o código hexadecimal das cores, dividido por cor primária e cor secundária, Favicon e Logo da empresa. (Não é necessário enviar em dimensões específicas pois o ajuste é feito automaticamente).
O subdomínio também é passível de alteração, basta informar o nome que desejam para ficar na URL valor informado.cadastro.io

Considerações finais

❗️

Sobre os Fluxos

Os Endpoints e Webhooks dos fluxos são os mesmos, o que muda são as ordens dos webhooks conforme ordenação descrita na documentação.

Os fluxos são parametrizáveis, ou seja, caso seja necessário alterar do Fluxo 1 para o Fluxo 2 será necessário abrir um chamado para o suporte.

🚧

Requisição individual por proposta

Atualmente não é possível criar diversas contas em uma única requisição, em casos desses é necessário enviar em diferentes requisições.

Quantidade de propostas por documentos
Temos uma validação onde é permitido criar 1 proposta por documento a cada 24 horas. Logo não é possível criar várias propostas para o mesmo documento enquanto a anterior não estiver finalizada e não tenha passado as 24 horas.

📘

Resultado das propostas

Em produção, o resultado das análises, tanto da PF quanto da PJ, pode levar até 48horas úteis para ser concluída.


❗️

Envio categorizado corretamente

Importante realizar o envio correto do tipo de empresa PJ, caso seja realizado um envio incorreto. Exemplo: deveria ser enviado MEI porém foi enviado PJ, isso pode fazer com que ocorra uma reprovação e também será cobrado o valor do tipo enviado.

👍

Importante

Documentação

PF: Aceitamos documentos físicos originais RG, CNH e RNE (não serão aceitos documentos digitalizados ou cópias autenticadas) e no caso de CNH Digital é imprescindível que tenha o QR Code.
PJ: Contrato Social ou em casos de clientes MEI, o Certificado da Condição do Microempreendedor Individual (CCMEI) + documentação PF do sócio.

Webhooks

Em caso de não receber o webhook é possível realizar uma chamada para receber o reenvio, para mais informações acesse a documentação de reenvio clicando aqui.

Motivos de Reprovação

O campo RejectedReason nos Webhooks quando a proposta é reprovada, informará o motivo da reprovação.
Caso o motivo não seja permitido por políticas internas resultarão na mensagem: “Cliente reprovado por política de compliance ou regra de negócio."

Envio categorizado corretamente

É importante realizar o envio correto do tipo de empresa PJ, caso seja realizado um envio incorreto. Exemplo: deveria ser enviado MEI porém foi enviado PJ, isso pode fazer com que ocorra uma reprovação e também será cobrado o valor do tipo enviado.

ClientCode e ProposalId

ClientCode é um identificador único por transação criado por você.
ProposalId é um identificador único que geramos após a criação da proposta, esse identificador será utilizado para realizar consultas.Recomendamos você guardar esses campos.