Business Accounts

Aviso de descontinuação: Este endpoint (v1) será descontinuado em 30/06/2026. Parceiros devem migrar para o v2 antes dessa data.

Abertura de conta desabilitada: O POST /v1/accounts/business foi descontinuado e agora retorna 400 Bad Request (BNK-0072) sem processar a requisição. A abertura de contas deve ser feita via POST /v2/accounts/business. As demais operações v1 (consulta, atualização e ativação) seguem disponíveis até a data acima.

Ciclo de Vida

Fluxo com KYC Aprovado

Fluxo com KYC Rejeitado

Status

Status	Descrição
PENDING	KYC em processamento
KYC_APPROVED	KYC aprovado, aguardando ativação
KYC_REPROVED	KYC rejeitado, necessário corrigir dados
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 documento (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 /v1/accounts/business

Endpoint descontinuado. A abertura de conta business via v1 foi desabilitada: esta rota agora retorna 400 Bad Request com o código BNK-0072 e não processa a requisição. Utilize POST /v2/accounts/business para abrir contas.

Response — 400 Bad Request (endpoint descontinuado):

{
  "errors": [
    {
      "code": "BNK-0072",
      "title": "Banking flow error",
      "description": "Business account creation via v1 is discontinued. Use v2 instead."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-07-02T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
400 Bad Request	Endpoint descontinuado (BNK-0072) — utilize v2
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Certificado mTLS inválido ou role insuficiente

---

Contrato anterior (referência histórica — não mais aceito)

O contrato abaixo descreve o comportamento anterior à descontinuação. O objeto BusinessAccountResponse documentado aqui continua sendo o formato retornado pelas rotas de consulta (GET) e atualização (PUT).

Criava uma nova conta bancária PJ. O processo de KYC era iniciado automaticamente.

Headers adicionais:

Header	Obrigatório	Descrição
X-Seller-Id	Sim	ID do seller na Barte

Request:

curl --request POST \
  --url 'https://api-banking.barte.com/v1/accounts/business' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-Seller-Id: 12345' \
  --data '{
    "externalId": "partner-ref-001",
    "document": "12345678000199",
    "legalName": "Empresa Exemplo LTDA",
    "tradingName": "Exemplo Store",
    "email": "[e-mail]",
    "phoneNumber": "5511999999999",
    "foundingDate": "2020-01-15",
    "businessType": "LTDA",
    "mainActivity": "4712100",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "postalCode": "01310100",
      "city": "São Paulo",
      "state": "SP"
    },
    "shareholders": [
      {
        "document": "12345678900",
        "firstName": "João",
        "lastName": "Silva",
        "birthDate": "1990-05-20",
        "email": "[e-mail]",
        "phoneNumber": "5511988888888",
        "type": "PARTNER",
        "address": {
          "street": "Rua Augusta",
          "number": "500",
          "neighborhood": "Consolação",
          "postalCode": "01304000",
          "city": "São Paulo",
          "state": "SP"
        }
      }
    ]
  }'

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
tradingName	String	Não	-
email	String	Sim	Email válido (RFC 5322). Ex: [e-mail]
phoneNumber	String	Sim	Formato: 55 + DDD (2 dígitos) + número (8-9 dígitos). Total: 12-13 dígitos. Ex: 5511999999999 (celular) ou 551133334444 (fixo)
foundingDate	String	Sim	Data ISO 8601: YYYY-MM-DD. Ex: 2020-01-15
businessType	String	Sim	Enum: MEI, EI, EIRELI, LTDA, SS, SA, NON_PROFIT
mainActivity	String	Não	CNAE: 7 dígitos. Ex: 4712100
address	Object	Sim	Objeto de endereço (ver tabela abaixo)
shareholders	Array	Sim	Lista de sócios. Mínimo: 1

Campos — Address

Campo	Tipo	Obrigatório	Validação
street	String	Sim	Apenas letras e espaços (sem números). Ex: Avenida Paulista, Rua das Flores
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. Ex: 12345678900 (CPF), 12345678000199 (CNPJ)
firstName	String	Sim	Primeiro nome (pessoa física). Não pode estar vazio
lastName	String	Sim	Sobrenome (pessoa física). Não pode estar vazio
birthDate	String	Sim	Data ISO 8601: YYYY-MM-DD. Ex: 1990-05-20
legalName	String	Não	Nome completo ou razão social
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. Ex: 5511988888888
type	String	Sim	Enum: PARTNER, PROXYHOLDER, LEGAL_REPRESENTATIVE, OTHER
address	Object	Sim	Objeto de endereço (mesma estrutura acima)

Tipos de Shareholder

Tipo	Descrição
PARTNER	Sócio
PROXYHOLDER	Procurador
LEGAL_REPRESENTATIVE	Representante legal
OTHER	Outro

Response — 202 Accepted:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "[e-mail]",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "PENDING",
  "kycDetails": null,
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 101",
    "neighborhood": "Bela Vista",
    "postalCode": "01310100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA"
  },
  "shareholders": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "document": "12345678900",
      "firstName": "João",
      "lastName": "Silva",
      "legalName": null,
      "birthDate": "1990-05-20",
      "email": "[e-mail]",
      "phoneNumber": "5511988888888",
      "type": "PARTNER",
      "address": {
        "street": "Rua Augusta",
        "number": "500",
        "neighborhood": "Consolação",
        "postalCode": "01304000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA"
      }
    }
  ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T15:30:00Z",
  "activatedAt": null
}

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

{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request phoneNumber - Phone must be in format 5511999999999"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 409 Conflict (CNPJ duplicado):

{
  "errors": [
    {
      "code": "BNK-0048",
      "title": "Não foi possível processar a operação",
      "description": "Business account with document 12345678000199 already exists"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 409 Conflict (externalId duplicado):

{
  "errors": [
    {
      "code": "BNK-0046",
      "title": "Banking flow error",
      "description": "Business account with externalId partner-ref-001 already exists"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
202 Accepted	Conta criada, KYC em processamento
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

---

GET /v1/accounts/business

Busca contas por filtros. Pelo menos um filtro é obrigatório.

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
externalId	String	Não*	ID de referência do parceiro
document	String	Não*	CNPJ da empresa (14 dígitos)

*Pelo menos um dos filtros é obrigatório.

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/accounts/business?externalId=partner-ref-001' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

Retorna o objeto BusinessAccountResponse (mesmo formato do POST).

Response — 400 Bad Request (filtro ausente):

{
  "errors": [
    {
      "code": "BNK-0049",
      "title": "Filter required",
      "description": "At least one filter (externalId or document) is required"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 403 Forbidden (sem acesso a conta):

{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 404 Not Found:

{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account with externalId partner-ref-001 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
200 OK	Sucesso
400 Bad Request	Nenhum filtro informado
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Sem acesso a conta
404 Not Found	Conta não encontrada

---

GET /v1/accounts/business/{businessId}

Consulta os dados de uma conta por ID.

Path Parameters:

Parâmetro	Tipo	Descrição
businessId	UUID	ID da conta (UUID v4)

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "[e-mail]",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "ACTIVE",
  "kycDetails": {
    "status": "KYC_APPROVED",
    "reviewedAt": "2026-01-30T16:00:00Z",
    "reasons": []
  },
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 101",
    "neighborhood": "Bela Vista",
    "postalCode": "01310100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA"
  },
  "shareholders": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "document": "12345678900",
      "firstName": "João",
      "lastName": "Silva",
      "legalName": null,
      "birthDate": "1990-05-20",
      "email": "[e-mail]",
      "phoneNumber": "5511988888888",
      "type": "PARTNER",
      "address": {
        "street": "Rua Augusta",
        "number": "500",
        "neighborhood": "Consolação",
        "postalCode": "01304000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA"
      }
    }
  ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T16:05:00Z",
  "activatedAt": "2026-01-30T16:05:00Z"
}

Campos — kycDetails

Campo	Tipo	Descrição
status	String	PENDING, KYC_APPROVED ou KYC_REPROVED
reviewedAt	String	Data/hora da análise (ISO 8601)
reasons	Array	Motivos da rejeição (se aplicável)

Status Codes:

Status	Descrição
200 OK	Sucesso
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Conta não pertence ao parceiro
404 Not Found	Conta não encontrada

---

PUT /v1/accounts/business/{businessId}

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

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:

curl --request PUT \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "legalName": "Empresa Exemplo LTDA",
    "tradingName": "Exemplo Store Atualizada",
    "email": "[e-mail]",
    "phoneNumber": "5511977777777",
    "foundingDate": "2020-01-15",
    "businessType": "LTDA",
    "mainActivity": "4712100",
    "address": { ... },
    "shareholders": [ ... ]
  }'

Nota: O document (CNPJ) é imutável. A conta é identificada pelo businessId na URL.

Response — 200 OK:

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

Response — 409 Conflict (KYC em andamento):

{
  "errors": [
    {
      "code": "BNK-0052",
      "title": "Banking flow error",
      "description": "Cannot update business account f47ac10b-58cc-4372-a567-0e02b2c3d479 while KYC is in progress. Wait for KYC result."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
200 OK	Dados atualizados, novo KYC iniciado
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

---

POST /v1/accounts/business/{businessId}/activate

Ativa uma conta após aprovação do KYC.

Pré-requisito: Status deve ser KYC_APPROVED e a biometria de todos os sócios concluída e aprovada. O KYC cadastral e a biometria por sócio são etapas distintas: uma conta pode estar KYC_APPROVED com a biometria ainda pendente. Nesse caso a ativação é recusada com 422 Unprocessable Entity (BNK-0073) — resolva a biometria pendente antes (veja biometric-sessions).

Path Parameters:

Parâmetro	Tipo	Descrição
businessId	UUID	ID da conta (UUID v4)

Request:

curl --request POST \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479/activate' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "[e-mail]",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "ACTIVE",
  "kycDetails": {
    "status": "KYC_APPROVED",
    "reviewedAt": "2026-01-30T16:00:00Z",
    "reasons": []
  },
  "address": { ... },
  "shareholders": [ ... ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T16:05:00Z",
  "activatedAt": "2026-01-30T16:05:00Z"
}

Response — 409 Conflict (KYC não aprovado):

{
  "errors": [
    {
      "code": "BNK-0041",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 has invalid status PENDING. Expected: KYC_APPROVED"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 409 Conflict (conta já ativa):

{
  "errors": [
    {
      "code": "BNK-0053",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 is already active"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 422 Unprocessable Entity (biometria de sócio pendente):

{
  "errors": [
    {
      "code": "BNK-0073",
      "title": "Banking flow error",
      "description": "Pending or rejected biometrics for shareholder(s): 12345678900: NAO_INICIADA. Complete the biometrics before activating the account."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

A description lista os sócios pendentes no formato documento: status. NAO_INICIADA indica que a biometria do sócio ainda não foi realizada; outros valores (REJECTED, EXPIRED, …) refletem o status da última análise. Conclua/reenvie a biometria via biometric-sessions e ative novamente.

Status Codes:

Status	Descrição
200 OK	Conta ativada com sucesso
401 Unauthorized	Token inválido
403 Forbidden	Conta não pertence ao parceiro
404 Not Found	Conta não encontrada
409 Conflict	KYC não aprovado ou conta já ativa
422 Unprocessable Entity	Biometria de um ou mais sócios pendente ou reprovada (BNK-0073)

---

GET /v1/accounts/business/{businessId}/balance

Consulta o saldo da conta business. Retorna o saldo da bag de débito.

Pré-requisito: Conta deve estar com status ACTIVE.

Path Parameters:

Parâmetro	Tipo	Descrição
businessId	UUID	ID da conta (UUID v4)

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479/balance' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

{
  "amount": 1500.00
}

Campos — Response

Campo	Tipo	Descrição
amount	BigDecimal	Saldo da bag de débito (em reais). Ex: 1500.00

Response — 403 Forbidden (sem acesso a conta):

{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Response — 404 Not Found:

{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
200 OK	Saldo retornado com sucesso
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Conta não pertence ao parceiro
404 Not Found	Conta não encontrada ou sem conta bancária associada