Número de contas

Introdução à Migração do Número de Contas

Atualmente, nosso Banking as a Service utiliza um formato de número de conta que pode ter até 20 caracteres. Esse padrão foi adotado para acomodar um grande número de contas e fornecer flexibilidade na identificação de cada uma delas. No entanto, temos identificado um problema significativo: alguns serviços financeiros, como TED e SLC, apresentam limitações ao processar transações para contas com mais de 13 caracteres. Essa incompatibilidade tem causado transtornos para nossos clientes ao realizar transações, resultando em falhas e atrasos indesejados.

Para resolver essa questão, estamos implementando um novo formato de número de conta que terá um máximo de 13 caracteres. Esse novo padrão garantirá que todas as contas possam ser processadas corretamente por serviços financeiros que impõem restrições de comprimento. Com essa mudança, buscamos otimizar a compatibilidade e melhorar a experiência de nossos clientes ao realizar transações.

O que muda com a nova implementação:

Número de Conta Antigo: Os números de conta antigos iniciam com o dígito '3' e podem ter até 20 caracteres.

Novo Número de Conta: O novo formato de número de conta começará com o dígito '4' e terá um comprimento máximo de 13 caracteres. Esse padrão será adotado para atender a todos os clientes e garantir a plena compatibilidade com as plataformas de pagamento e transações.

Endpoint de Migração: Para facilitar a transição, criamos um novo endpoint de migração. Este endpoint permitirá a troca automática dos números de conta antigos pelo novo padrão, minimizando o impacto para nossos clientes e assegurando a continuidade das operações sem interrupções.

Como migrar um número de conta?

Pré requisitos para migração:

• Não possuir nenhuma chave Pix cadastrada para essa conta. É necessário excluir a chave Pix e criar novamente a mesma na conta migrada.
• Conta não pode ter transações pendentes
• Conta não pode ter cobranças em aberto
• Conta tem que ser ativa
• Conta não pode ter sido migrada anteriormente (comandar uma 2ª migração de conta via endpoint).

Passos para migrar

1. Realizar autenticação na API - [API Reference]
2. Solicitar Migração - [API Reference]
3. Receber o novo número de contas
   1. Via Webhook - event: account-migration
   2. Consultar status da conta via - onboardingId

cURL da chamada

curl -X 'PUT' \
  'https://sandbox.openfinance.celcoin.dev/baas-accountmanager/v1/account/migration/newAccount' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "account": "3005406551206"
}'

Retorno com Sucesso

👍

Sucesso 200

{
    "version": "1.0.0",
    "status": "PROCESSING",
    "entity": "account-migration",
    "body": {
        "account": "3005406551206",
        "documentNumber": "89431042517",
        "name": "Loretta Dooley",
        "onboardingId": "e69415e0-83b6-4dda-b47a-ab522e0dbb5e"
    }
}

❗

Error 400

{
  "status": "string",
  "version": "string",
  "error": {
    "errorCode": "string",
    "message": "string"
  }
}

Tabela de errorCode

Como descobrir o novo número de conta?

Existem duas abordagens para esse caso:

1. Webhook -> Evento "account-migration":
   Sempre que um novo número de conta for gerado como parte do processo de migração, será enviado um evento de webhook denominado "account-migration".

Exemplo:

{
  "entity": "account-migration",
  "createTimestamp": "2024-08-12T12:31:10.5744173",
  "status": "CONFIRMED",
  "body": {
    "onboardingId": "e69415e0-83b6-4dda-b47a-ab522e0dbb5e",
    "documentNumber": "89431042517",
    "createDate": "2024-08-12T12:31:10.5745199",
    "lastUpdateDate": "2024-08-12T12:31:10.5745413",
    "account": "41103",
    "name": "Loretta Dooley",
    "oldAccount": "3005406551206"
  },
  "webhookId": "c8027dc9-f51c-44bf-8f20-3d9dd4e6c39d"
}

2. Consulta via onboardingId:
   Além disso, após a chamada de migração, o sistema retornará um onboardingId, que poderá ser usado para consultar e confirmar o novo número de conta associado. Essa opção oferece uma maneira adicional para os clientes verificarem e obterem o novo número de conta, garantindo maior flexibilidade no processo de migração.

Exemplo da chamada:

curl --location 'https://sandbox.openfinance.celcoin.dev/baas-onboarding/v1/account/check?onboardingId=e69415e0-83b6-4dda-b47a-ab522e0dbb5e' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}'

Retorno da chamada:

{
    "version": "1.0.0",
    "status": "CONFIRMED",
    "body": {
        "onboardingId": "e69415e0-83b6-4dda-b47a-ab522e0dbb5e",
        "clientCode": "676",
        "createDate": "2024-08-12T11:51:09",
        "entity": "onboarding-create",
        "account": {
            "branch": "0001",
            "account": "41103",
            "name": "Loretta Dooley",
            "documentNumber": "89431042517",
            "isbp": "13935893"
        }
    }
}