Alterações nos Endpoints de Sellers – Sandbox e Produção

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

---

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": "[e-mail]",
  "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": "[e-mail]",
  "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": "[e-mail]",
    "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": "[e-mail]",
      "phone": "11966701879"
    },
    "accounts": {
      "bank": 1,
      "issuer": "1234",
      "number": "98765",
      "pixKey": "12345678901",
      "pixKeyType": "CPF",
      "accountType": "CHECKING_ACCOUNT",
      "issuerDigit": 6,
      "transferType": "PIX"
    },
    "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 de migrar para produção