Ctrlk
Status

Conta PJ

Por que o V2?

A Circular nº 3.978/2020 do Banco Central passou a exigir verificação biométrica facial obrigatória no onboarding de contas PJ. Com isso, cada entidade vinculada à conta (sócio, representante legal) precisa realizar uma verificação de identidade com biometria facial (liveness + facematch + OCR de documento) além do KYC cadastral já existente.

O endpoint v2 foi criado para incorporar esse fluxo sem impactar os parceiros que ainda utilizam o v1. Os dois endpoints coexistem durante o período de migração — parceiros migram de v1 para v2 individualmente.

Aviso de descontinuação: O endpoint v1 será descontinuado em 30/06/2026. Parceiros devem migrar para o v2 antes dessa data. Consulte também o aviso na documentação de Business Accounts.

O que muda em relação ao v1?

v1
v2

Biometria facial

Não

Sim — obrigatória para cada entidade

tradingName

Presente

Removido

foundingDate

Presente

Removido

businessType

Presente

Removido

mainActivity

Presente

Removido

motherName (sócios)

Presente

Removido

annualRevenueRange

Ausente

Obrigatório

monthlyRevenueRange (sócios)

Ausente

Opcional

occupation (sócios)

Ausente

Opcional

address.country

Ausente

Opcional (default: BRA)

legalRelationships

Ausente

Opcional

Resposta

Sem sessões biométricas

Inclui biometricSessions[]

Ciclo de Vida

O fluxo de abertura de conta no v2 envolve duas etapas independentes que precisam ser aprovadas para cada entidade:

  • KYC cadastral — validação dos dados da empresa e dos indivíduos vinculados.

  • Biometria facial — verificação de identidade com liveness, facematch e OCR de documento.

Ambas as etapas são processadas de forma assíncrona. O account holder só é aprovado quando KYC e biometria estiverem aprovados para todas as entidades da conta.

A biometria precisa ser refeita (via retry) somente nos casos de: reprovação, atualização de dados de uma entidade ou inclusão de novo sócio.

Fluxo com KYC e Biometria Aprovados

Fluxo com KYC e Biometria Rejeitados (Retry)

Fluxo com Token Expirado (Refresh)

Status da Conta

Status
Descrição

PENDING

KYC e biometria em processamento

KYC_APPROVED

KYC e biometria aprovados, aguardando ativação

KYC_REPROVED

KYC ou biometria rejeitados, necessário retentar

ACTIVE

Conta ativa e operacional

BLOCKED

Conta bloqueada temporariamente

CLOSED

Conta encerrada permanentemente

Simulação de KYC em Testes

No ambiente de testes, o resultado do KYC é determinado pelo primeiro dígito do CPF do account holder ou do primeiro shareholder:

Primeiro dígito
Resultado do KYC

0 a 4

Aprovado automaticamente

5 a 6

Reprovado automaticamente

7

Entra em análise manual, seguido de aprovação

8

Entra em análise manual, seguido de reprovação

9

Entra em análise, seguido de qualquer status final

Exemplo: Um shareholder com CPF 42345678900 (primeiro dígito 4) terá o KYC aprovado automaticamente. Já um CPF 81234567800 (primeiro dígito 8) entrará em análise manual e será reprovado em seguida.

POST /v2/accounts/business

Cria uma nova conta bancária PJ com suporte a KYC e biometria facial. O processo de biometria é iniciado automaticamente — cada entidade recebe uma sessão com link de biometria facial.

Headers adicionais:

Header
Obrigatório
Descrição

X-Seller-Id

Sim

ID do seller na Barte

Request:

Campos — Business

Campo
Tipo
Obrigatório
Validação

externalId

String

Não

Máximo 36 caracteres

document

String

Sim

CNPJ: exatamente 14 dígitos numéricos. Ex: 12345678000199

legalName

String

Sim

Não pode estar vazio

email

String

Sim

Email válido (RFC 5322). Ex: [email protected]

phoneNumber

String

Sim

Formato: 55 + DDD (2 dígitos) + número (8-9 dígitos). Total: 12-13 dígitos. Ex: 5511999999999

annualRevenueRange

String

Sim

Enum (ver tabela abaixo)

address

Object

Sim

Objeto de endereço (ver tabela abaixo)

shareholders

Array

Sim

Lista de sócios. Mínimo: 1

legalRelationships

Array

Não

Lista de representantes legais

Valores — annualRevenueRange

Valor
Descrição (em R$)

up_to_50k

Até 50 mil

from_50k_to_500k

De 50 mil a 500 mil

from_500k_to_5m

De 500 mil a 5 milhões

from_5m_to_50m

De 5 milhões a 50 milhões

above_50m

Acima de 50 milhões

Campos — Address

Campo
Tipo
Obrigatório
Validação

street

String

Sim

Apenas letras e espaços (sem números). Ex: Avenida Paulista

number

String

Sim

Número do endereço. Pode conter letras. Ex: 1000, 123A

complement

String

Não

Complemento. Ex: Sala 101, Bloco B

neighborhood

String

Sim

Bairro. Não pode estar vazio

postalCode

String

Sim

CEP: exatamente 8 dígitos numéricos, sem hífen. Ex: 01310100

city

String

Sim

Cidade. Não pode estar vazio

state

String

Sim

UF: 2 letras maiúsculas. Ex: SP, RJ, MG

country

String

Não

Código do país (ISO 3166-1 alpha-3). Default: BRA

Campos — Shareholder

Campo
Tipo
Obrigatório
Validação

document

String

Sim

CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números

type

String

Sim

Enum: PARTNER, PROXYHOLDER, LEGAL_REPRESENTATIVE, OTHER

firstName

String

Não

Primeiro nome (pessoa física)

lastName

String

Não

Sobrenome (pessoa física)

birthDate

String

Não

Data ISO 8601: YYYY-MM-DD. Ex: 1990-05-20

legalName

String

Não

Razão social (pessoa jurídica)

email

String

Não

Email válido (RFC 5322), se informado

phoneNumber

String

Não

Formato: 55 + DDD + número. Total: 12-13 dígitos, se informado

monthlyRevenueRange

String

Não

Enum (ver tabela abaixo)

annualRevenueRange

String

Não

Enum: mesmos valores do campo business

address

Object

Sim

Objeto de endereço (mesma estrutura acima)

Valores — monthlyRevenueRange

Valor
Descrição

0_to_1_sm

Até 1 salário mínimo

1_to_2_sm

De 1 a 2 salários mínimos

2_to_3_sm

De 2 a 3 salários mínimos

3_to_5_sm

De 3 a 5 salários mínimos

5_to_7_sm

De 5 a 7 salários mínimos

7_to_10_sm

De 7 a 10 salários mínimos

10_to_15_sm

De 10 a 15 salários mínimos

15_to_20_sm

De 15 a 20 salários mínimos

over_20_sm

Acima de 20 salários mínimos

Campos — LegalRelationship

Campo
Tipo
Obrigatório
Validação

relationshipType

String

Sim

Enum: LEGAL_REPRESENTATIVE, ATTORNEY_IN_FACT, REPRESENTATIVE_FOREIGN, TUTOR, EMANCIPATED_MINOR

person

Object

Sim

Dados da pessoa (ver tabela abaixo)

Campos — LegalRelationship Person

Campo
Tipo
Obrigatório
Validação

document

String

Sim

CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números

fullName

String

Sim

Nome completo ou razão social

email

String

Sim

Email válido (RFC 5322)

phoneNumber

String

Sim

Formato: 55 + DDD + número. Total: 12-13 dígitos

monthlyRevenueRange

String

Sim

Enum: mesmos valores do campo shareholder

occupation

String

Não

Ocupação da pessoa (ver tabela abaixo)

address

Object

Sim

Objeto de endereço (mesma estrutura acima)

Nota: monthlyRevenueRange é obrigatório para LegalRelationship Person e opcional para Shareholder. Representantes legais têm contrato mais restrito por exigência regulatória de identificação de renda.

Valores — occupation

Valor

Administrador de Redes

Advogado

Agricultor

Analista Administrativo

Analista de Dados

Analista de Marketing

Analista de Sistemas / TI

Analista Financeiro

Aprendiz

Aposentado

Arquiteto

Artista

Assistente Administrativo

Atendente

Atleta Profissional

Auditor

Autônomo

Auxiliar Administrativo

Auxiliar de Cozinha

Auxiliar de Logística

Auxiliar de Serviços Gerais

Bancário

Barbeiro

Bombeiro

Cabeleireiro

Camareiro(a)

Cientista de Dados

Coletor de Resíduos

Confeiteiro

Consultor

Consultor Financeiro

Contador

Coordenador Pedagógico

Corretor de Imóveis

Corretor de Seguros

Cozinheiro

Cuidador de Pessoas

Dentista

Desempregado

Designer Gráfico

Desenvolvedor de Software

Digitador

Diretor de Área

Diretor Executivo (CEO / CFO / COO)

Do lar

Economista

Eletricista

Empreendedor / Empresário

Empresário (genérico)

Encanador

Enfermeiro

Engenheiro

Engenheiro de Software

Escriturário

Estagiário

Esteticista

Estoquista

Estudante

Faxineiro / Limpeza

Farmacêutico

Fisioterapeuta

Garçom

Gerente Administrativo

Gerente Comercial

Gerente de Loja

Gerente de Operações

Gerente Financeiro

Gerente Geral

Influencer / Criador de Conteúdo

Instrutor / Tutor

Investidor Profissional

Jornalista

Manicure / Pedicure

Mecânico

Médico

Microempreendedor Individual (MEI)

Motoboy / Entregador

Motorista (carro / aplicativo)

Motorista de Caminhão

Músico

Nutricionista

Operador de Criptoativos

Operador de Empilhadeira

Operador de Máquinas

Outro / Não informado

Padeiro

Pecuarista

Pedreiro

Pensionista

Pescador

Policial

Porteiro / Vigia

Prestador de Serviços

Produtor Cultural

Professor (Educação Básica)

Professor do Ensino Médio

Professor Universitário

Psicólogo

Publicitário

Recepcionista

Recepcionista de Hotel

Representante Autônomo

Representante Comercial

Secretário(a)

Servente de Obras

Servidor Público

Soldador

Suporte Técnico de TI

Técnico em Edificações

Técnico em Eletrônica

Técnico em Enfermagem

Técnico em Mecânica

Técnico em Segurança do Trabalho

Trader / Day Trader

Trabalhador Doméstico

Trabalhador Rural

Vendedor

Vigia / Segurança Privado

Vigilante

Zelador

Response — 202 Accepted:

Campos — Response

Campo
Tipo
Descrição

id

UUID

Identificador único da conta na Barte

status

String

Status atual da conta (ver tabela Status da Conta)

kycDetails

Object|null

Detalhes do resultado do KYC. null enquanto o processo está em andamento

activatedAt

String|null

Timestamp UTC de ativação da conta. null até a conta ser ativada

createdAt

String

Timestamp UTC de criação da conta (ISO 8601)

updatedAt

String

Timestamp UTC da última atualização (ISO 8601)

Response — 400 Bad Request (validação):

Response — 409 Conflict (CNPJ duplicado):

Status Codes:

Status
Descrição

202 Accepted

Conta criada, KYC e biometria iniciados

400 Bad Request

Dados inválidos ou campos obrigatórios ausentes

401 Unauthorized

Token inválido ou expirado

403 Forbidden

Certificado mTLS inválido

409 Conflict

CNPJ ou externalId já cadastrado

Para consultar e gerenciar as sessões biométricas geradas, consulte Sessões Biométricas.

PUT /v2/accounts/business/{businessId}

Atualiza os dados de uma conta. Dispara novo ciclo de KYC e biometria.

Não permitido quando status é PENDING. Aguarde o resultado do KYC atual.

Path Parameters:

Parâmetro
Tipo
Descrição

businessId

UUID

ID da conta (UUID v4)

Request:

Nota: O document (CNPJ) é imutável e não deve ser enviado no body. O contrato de campos segue o mesmo do POST.

Response — 200 OK:

Retorna o objeto completo da conta com status: "PENDING".

Status Codes:

Status
Descrição

200 OK

Dados atualizados, novo KYC e biometria iniciados

400 Bad Request

Dados inválidos

401 Unauthorized

Token inválido

403 Forbidden

Conta não pertence ao parceiro

404 Not Found

Conta não encontrada

409 Conflict

KYC em andamento, aguarde resultado

Para consultar e gerenciar as sessões biométricas geradas após a atualização, consulte Sessões Biométricas.

Webhooks

O banking service envia notificações de status de conta via webhook. Esta funcionalidade está em desenvolvimento.

Códigos de Erro

Código
Endpoint
Descrição

BNK-0048

POST /v2/accounts/business

CNPJ ou externalId já cadastrado

BNK-0501

POST /v2/accounts/business

Parâmetros de request inválidos (ex: formato de campo incorreto)

PreviousAbertura de Contas (v2)NextSessões Biométricas

Last updated

Was this helpful?