Alterações na API de Vendedores em 15/10/2025

Resumo das Alterações

Estamos atualizando os endpoints da API de Sellers v2 com novos campos obrigatórios a partir do dia 15/10/25.

POST /v2/seller

Clique no link abaixo para ver a referência completa da requisição:

Criar Vendedor

Antes	Depois
Sem objeto owner	Objeto owner obrigatório com 3 campos (name, document, birthdate)
Sem campo mccCpf	Campo mccCpf obrigatório quando document for CPF
7 campos no objeto account	8 campos no objeto account (+ transferType)
Sem campo transferType	Campo transferType obrigatório no objeto account

PATCH /v2/seller

Clique no link abaixo para ver a referência completa da requisição:

Atualizar dados bancários de um Vendedor

Antes	Depois
Sem campo transferType	Campo transferType obrigatório
7 campos no objeto account	8 campos no objeto account (+ transferType)

GET/v2/seller

Clique no link abaixo para ver a referência completa da requisição:

Buscar Vendedor

Antes	Depois
Sem campo transferType	Campo transferType no response
7 campos no objeto account	8 campos no objeto account (+ transferType)

---

Detalhamento das Alterações

1. POST /v2/seller - Criação de Sellers

Novos Campos:

• transferType (obrigatório): "PIX" ou "BANK_ACCOUNT" no objeto account

• mccCpf (condicional): Obrigatório quando document for CPF

• objeto owner (obrigatório):

  • name (string, obrigatório): Nome completo do proprietário (máx. 100 caracteres)

  • document (string, obrigatório): CPF do proprietário (11 dígitos)

  • birthdate (string, obrigatório): Data de nascimento no formato YYYY-MM-DD

Exemplo de Payload (com campos adicionais):

{
  "document": "65800562000165",
    "companyName": "Old Order",
    "fantasyName": "Old Order Tecnologia",
    "webhook": "https://oldorder.com.br",
    "sellerUrl": "https://oldorder.com.br",
    "email": "[email protected]",
    "password": "cp202729",
    "owner": {                      // ← NOVO OBJETO OBRIGATÓRIO
        "name": "João da Silva",
        "document": "51102616010",
        "birthdate": "1990-01-01"
    },
    "address": {
        "country": "BR",
        "state": "MG",
        "city": "Belo Horizonte",
        "district": "Centro",
        "street": "Avenida Afonso Pena",
        "zipCode": "30130001",
        "number": "1500",
        "complement": "Sala 202"
    },
    "contact": {
        "name": "João Silva",
        "email": "[email protected]",
        "countryCode": "55",
        "phone": "31999887766"
    },
    "account": {
        "account": {
            "bank": "001",
            "issuer": "144111",
            "issuerDigit": "6",
            "number": "1425",
            "bankDigit": "5",
            "accountType": "CHECKING_ACCOUNT"
        },
        "transferType": "PIX",         // ← NOVO CAMPO OBRIGATÓRIO
            "pix": {
                "keyType": "CNPJ",
                "key": "65800562000165"
      }
}

Exemplos de resposta:

Sucesso (201)

{
    "document": "65800562000165",
    "companyName": "Old Order",
    "fantasyName": "Old Order Tecnologia",
    "webhook": "https://oldorder.com.br",
    "sellerUrl": "https://oldorder.com.br",
    "email": "[email protected]",
    "password": "cp202729",
    "owner": {
        "name": "João da Silva",
        "document": "51102616010",
        "birthdate": "1990-01-01"
    },
    "address": {
        "country": "BR",
        "state": "MG",
        "city": "Belo Horizonte",
        "district": "Centro",
        "street": "Avenida Afonso Pena",
        "zipCode": "30130001",
        "number": "1500",
        "complement": "Sala 202"
    },
    "contact": {
        "name": "João Silva",
        "email": "[email protected]",
        "countryCode": "55",
        "phone": "31999887766"
    },
    "account": {
        "account": {
            "bank": "001",
            "issuer": "144111",
            "issuerDigit": "6",
            "number": "1425",
            "bankDigit": "5",
            "accountType": "CHECKING_ACCOUNT"
        },
        "transferType": "PIX",
        "pix": {
            "keyType": "CNPJ",
            "key": "65800562000165"
        }
    }
}

Erro (400)

{    "error": "[400] BAR-3011 Erro de validação do payload - document é obrigatório; email deve ser um email válido; owner.document deve ser um CPF válido"}

Erros comuns

400 - Bad Request

• BAR-3011: Erro de validação do payload

  • Campos obrigatórios ausentes

  • Formatos inválidos

  • Valores fora dos limites permitidos

401 - Unauthorized

• BAR-3009: Token de autenticação ausente ou inválido

---

2. PATCH /v2/seller - Atualização de Conta Bancária

Novo Campo:

• transferType (obrigatório): PIX ou BANK_ACCOUNT

Novo Payload (com transferType):

{
  "idSeller": 123,
  "account": {
    "bank": "1",
    "issuer": "144111",
    "issuerDigit": "6",
    "number": "1425",
    "bankDigit": "5",
    "accountType": "CHECKING_ACCOUNT",
    "transferType": "PIX",        // ← NOVO CAMPO OBRIGATÓRIO
    "pixKey": "50307285030",
    "pixKeyType": "DOCUMENT"
  }
}

Resposta (inclui novo campo transferType):

{
  "idSeller": 123,
  "account": {
    "bank": "1",
    "issuer": "144111",
    "number": "1425",
    "issuerDigit": "6",
    "bankDigit": "5",
    "accountType": "CHECKING_ACCOUNT",
    "transferType": "PIX",        // ← NOVO CAMPO OBRIGATÓRIO
    "pixKey": "50307285030",
    "pixKeyType": "DOCUMENT"
  }
}

3. GET/v2/seller - Buscar vendedor

   {
      "idSeller":89,
      "document":"12345678901",
      "companyName":"Empresa Exemplo Ltda",
      "fantasyName":"Empresa Exemplo",
      "sellerUrl":"https://empresa-exemplo.com.br",
      "email":"[email protected]",
      "token": 123e4567-e89b-12d3-a456-426614174000,
      "address":{
         "city":"São Paulo",
         "state":"SP",
         "number":"123",
         "street":"Rua das Flores",
         "country":"BR",
         "zipCode":"01234567",
         "district":"Centro",
         "complement":"Sala 101"
      },
      "contacts":{
         "name":"João Silva",
         "email":"[email protected]",
         "phone":"11999887766"
      },
      "accounts":{
         "bank":1,
         "issuer":"1234",
         "number":"98765",
         "pixKey":"12345678901",
         "pixKeyType":"CPF",
         "accountType":"CHECKING_ACCOUNT",
         "issuerDigit":6,
         "transferType":"PIX"
      }
   }

---

Valores Aceitos

transferType:

• PIX: Transferência via sistema PIX

• BANK_ACCOUNT: Transferência bancária tradicional (TED/DOC)

accountType:

• CHECKING_ACCOUNT: Conta corrente

• SAVINGS_ACCOUNT: Conta poupança

pixKeyType:

• CPF: Documento de pessoa física

• CNPJ: Documento de pessoa jurídica

• EMAIL: Endereço de email

• PHONE: Número de telefone

• DOCUMENT: CPF ou CNPJ (detecção automática)

• ALLEATORY_KEY: Chave aleatória

mccCpf:

• VETERINARY_SERVICES: Serviços veterinários

• SPECIAL_TRADE_CONTRACTORS: Empreiteiros especializados

• TAXI_CABS_AND_LIMOUSINES: Táxis e limusines

• MISCELLANEOUS_GENERAL_MERCHANDISE: Mercadorias gerais diversas

• MISCELLANEOUS_FOOD_SHOPS: Lojas de alimentos diversos

• TAILORS_SEAMSTRESSES_MENDING: Alfaiates e costureiras

• MISCELLANEOUS_APPAREL_SHOPS: Lojas de vestuário diversas

• DOOR_TO_DOOR_SALES: Vendas porta a porta

• ARTIST_SUPPLY_CRAFT_SHOPS: Lojas de materiais artísticos

• BEAUTY_AND_BARBER_SHOPS: Salões de beleza e barbearias

• MISCELLANEOUS_PERSONAL_SERVICES: Serviços pessoais diversos

• TOWING_SERVICES: Serviços de reboque

• COMPUTER_MAINTENANCE_REPAIR: Manutenção e reparo de computadores

• BUSINESS_SERVICES: Serviços empresariais

• AUTOMOTIVE_SERVICE_SHOPS: Oficinas automotivas

• DOCTORS_AND_PHYSICIANS: Médicos e clínicos

• DENTISTS_AND_ORTHODONTISTS: Dentistas e ortodontistas

• MEDICAL_SERVICES_HEALTH_PRACTITIONERS: Serviços médicos e profissionais de saúde

• LEGAL_SERVICES_ATTORNEYS: Serviços jurídicos e advogados

• PROFESSIONAL_SERVICES: Serviços profissionais

---

Exemplos de Erro

Campo transferType ausente:

{
  "error": "Campo transferType é obrigatório no objeto account"
}

Campo mccCpf ausente (quando document for CPF):

{
  "error": "mccCpf é obrigatório quando document for CPF"
}

Valor inválido para transferType:

{
  "error": "transferType deve ser PIX ou BANK_ACCOUNT"
}

---

Testando em Sandbox

No processo de teste utilize as credenciais de Sandbox compartilhados pelo time Barte. Sua chave X-Token-Api é diferente da utilizada em produção.

Cenários de Teste Recomendados:

1. POST /v2/seller com novos campos transferType e mccCpf

2. PATCH /v2/seller com novo campo transferType

Exemplo de Teste POST (CPF):

POST /v2/seller
{
  "document": "12345678901",
  "companyName": "Empresa Teste",
  "fantasyName": "Fantasia Teste",
  "mccCpf": "BUSINESS_SERVICES",
  "account": {
    "bank": "1",
    "issuer": "144111",
    "issuerDigit": "6",
    "number": "1425",
    "bankDigit": "5",
    "accountType": "CHECKING_ACCOUNT",
    "transferType": "PIX",
    "pixKey": "12345678901",
    "pixKeyType": "DOCUMENT"
  },
  // ... outros campos obrigatórios
}

Exemplo de Teste POST (CNPJ):

POST /v2/seller
{
  "document": "12345678000195",
  "companyName": "Empresa Teste LTDA",
  "fantasyName": "Fantasia Teste",
  // mccCpf não é obrigatório para CNPJ
  "account": {
    "transferType": "PIX",
    // ... outros campos
  }
}

---

Agradecemos pela parceria e estamos à disposição para auxiliar em todo o processo de migração!