Alterações nos Endpoints de Sellers – Sandbox

As alterações nos endpoints de Sellers da API já estão em vigor no ambiente de Sandbox.

Importante: As mudanças serão publicadas em Produção até sexta-feira, 06/03/2026.

---

Resumo das Alterações

As principais mudanças envolvem:

• Inclusão do objeto webhooks nas responses de POST, GET e PATCH

• Atualização do PATCH /v2/seller para permitir:

  • Atualização de account (já existia)

  • Criação e atualização de webhooks

• Depreciação do campo webhook (mantido temporariamente por compatibilidade)

• Novas regras de validação para o PATCH

A request do POST não sofreu alterações.

---

POST /v2/seller

Request (sem alterações)

A estrutura da requisição permanece a mesma.

POST /v2/seller HTTP/1.1
Host: api.barte.com
X-Token-Api: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*

(Body permanece inalterado conforme documentação anterior.)

Criar Vendedor

---

Alteração na Response

Response Anterior

{
  "document": "87654321000198",
  "idSeller": 28451,
  "companyName": "TECHNOLOGY SOLUTIONS BRASIL LTDA",
  "email": "[email protected]",
  "webhook": "https://api.technologysolutions.com.br/webhook",
  "x-token-api": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Nova Response

Agora a API retorna também o array webhooks:

{
  "document": "87654321000198",
  "idSeller": 28451,
  "companyName": "TECHNOLOGY SOLUTIONS BRASIL LTDA",
  "email": "[email protected]",
  "webhook": "https://api.technologysolutions.com.br/webhook",
  "webhooks": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Webhook",
      "domains": ["ORDER", "SUBSCRIPTION"],
      "active": true,
      "url": "https://api.technologysolutions.com.br/webhook"
    }
  ],
  "x-token-api": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Depreciação do campo webhook

O campo:

"webhook": "https://api.technologysolutions.com.br/webhook"

• Continua sendo retornado temporariamente no POST e no GET

• Está oficialmente depreciado

• Foi mantido para não quebrar integrações existentes

• Pode ser removido em versões futuras da API

Recomendação

Novas integrações devem utilizar exclusivamente o array webhooks.

---

Estrutura do novo campo webhooks

Campo	Tipo	Descrição
uuid	string	Identificador único do webhook
title	string	Nome do webhook
domains	array	Eventos vinculados (ORDER, SUBSCRIPTION)
active	boolean	Indica se o webhook está ativo
url	string	URL configurada para recebimento

---

GET /v2/seller

Alteração na Response

Response Anterior

Retornava apenas os dados do seller.

---

Nova Response

Agora o retorno inclui também o array webhooks.

[
  {
    "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": { ... },
    "contacts": { ... },
    "accounts": { ... }
  },
  {
    "webhooks": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Webhook",
        "domains": ["ORDER", "SUBSCRIPTION"],
        "active": true,
        "url": "https://api.technologysolutions.com.br/webhook"
      }
    ]
  }
]

Compatibilidade

Assim como no POST:

• O campo webhook continua sendo retornado

• Está depreciado

• Deve ser substituído pelo uso do array webhooks

---

PATCH /v2/seller

Alterações Importantes

Agora o endpoint permite:

• Atualizar account

• Atualizar webhook existente

• Criar novo webhook

• Enviar account e webhooks juntos

• Não é permitido enviar a request sem account e sem webhooks

---

Regras de Validação

1. account e webhooks são opcionais

Mas ao menos um dos dois deve ser enviado.

---

2. Atualização de Webhook

Para atualizar um webhook existente:

• É obrigatório enviar o campo uuid

• É obrigatório enviar pelo menos um dos campos abaixo:

  • title

  • domains

  • active

  • url

Exemplo:

{
  "idSeller": 123,
  "webhooks": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Webhook de Pedidos",
      "active": true
    }
  ]
}

---

3. Criação de Novo Webhook

Para criar um novo webhook:

• Não enviar uuid

• Enviar todos os campos obrigatórios:

{
  "idSeller": 123,
  "webhooks": [
    {
      "title": "Webhook de Assinaturas",
      "domains": ["SUBSCRIPTION"],
      "active": true,
      "url": "https://barte.com/webhook"
    }
  ]
}

---

Nova Request Completa (Account + Webhooks)

{
  "idSeller": 123,
  "webhooks": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Webhook de Pedidos",
      "domains": ["ORDER", "SUBSCRIPTION"],
      "active": true,
      "url": "https://barte.com/webhook"
    }
  ],
  "account": {
    "bank": "1",
    "issuer": "144111",
    "issuerDigit": "6",
    "number": "1425",
    "bankDigit": "5",
    "accountType": "CHECKING_ACCOUNT",
    "transferType": "PIX",
    "pixKey": "50307285030",
    "pixKeyType": "DOCUMENT"
  }
}

---

Alteração na Response

Response Anterior

{
  "idSeller": "1001",
  "account": { ... }
}

---

Nova Response

Agora retorna também os webhooks:

{
  "idSeller": "1001",
  "account": {
    "bank": "237",
    "bankDigit": "2",
    "issuer": "1234",
    "issuerDigit": "5",
    "number": "98765",
    "accountType": "CHECKING_ACCOUNT",
    "transferType": "PIX",
    "pixKey": "12345678901",
    "pixKeyType": "CPF"
  },
  "webhooks": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Webhook de Pedidos",
      "domains": ["ORDER", "SUBSCRIPTION"],
      "active": true,
      "url": "https://barte.com/webhook"
    }
  ]
}

---

Recomendações

Recomendamos que todas as integrações:

• Migrem o quanto antes para o uso exclusivo de webhooks

• Não dependam mais do campo webhook

• Validem todos os fluxos em Sandbox antes da entrada em produção

---

Cronograma

• Alterações já disponíveis em Sandbox

• Publicação em Produção até 06/03/2026