Business Accounts

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

---

POST /v1/accounts/business

Cria uma nova conta bancária PJ. O processo de KYC é 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": "[email protected]",
    "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": "[email protected]",
        "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: [email protected]
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": "[email protected]",
  "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": "[email protected]",
      "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 (conta de outra instituição):

{
  "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	Conta pertence a outra instituição
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": "[email protected]",
  "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": "[email protected]",
      "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": "[email protected]",
    "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.

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": "[email protected]",
  "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"
  }
}

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