Use Case - Pedido simples (PIX, Boleto e Cartão de Crédito)

Este caso de uso descreve como um vendedor cria um pedido único na API da Barte, vinculando obrigatoriamente um comprador (Buyer) e processando o pagamento via PIX, Boleto ou Cartão de Crédito, além d

---

Atores

• Vendedor (Seller): Sistema integrador que consome a API da Barte

• Barte API: Responsável por processar pedidos, pagamentos e pós-pagamento

---

Pré-condições

• O vendedor possui um Token de API válido

  • Link rápido → Obtendo o Token de API

• O comprador (Buyer) deve existir antes da criação do pedido

  • Link rápido → Criando um Comprador

---

Fluxo Principal

1. Autenticação na API

O vendedor autentica todas as requisições utilizando seu Token de API.

Header obrigatório em todas as chamadas:

X-Token-Api: YOUR_API_KEY

📌 Referência: Obtendo o Token de API

---

2. Criar um Comprador (Buyer) — Obrigatório

Todo pedido na Barte deve estar vinculado a um Buyer. O Buyer representa a pessoa física ou jurídica responsável pelo pagamento.

Ação

• O vendedor cria um Buyer informando dados de identificação, contato e endereço.

Resultado esperado

• A API retorna o campo uuid do Buyer.

📌 Importante: Esse uuid será utilizado obrigatoriamente na criação do pedido.

📌 Referência: Criando um Comprador

---

3. Criar um Pedido (Order)

Com o Buyer criado, o vendedor pode criar um pedido informando:

• Valor da transação

• Datas

• Descrição do pedido

• Método de pagamento

• Dados específicos do pagamento (ex: cartão, PIX ou boleto)

• uuidBuyer (obrigatório)

Métodos de pagamento suportados neste use case

• Cartão de Crédito

• PIX

• Boleto

📌 Referência: Métodos de Pagamento

---

Resultado esperado

• A API cria o pedido

• Uma ou mais charges são geradas

• O status inicial do pedido e da charge depende do método de pagamento:

  • Cartão: geralmente PAID ou AUTHORIZED

  • PIX/Boleto: geralmente PENDING

📌 O uuid da charge será necessário para ações de pós-pagamento.

📌 Referência: Pedido simples (PIX, Boleto e Cartão de Crédito)

---

Fluxos Pós-Pagamento

Após a criação do pedido, o vendedor pode executar ações adicionais dependendo do status da charge.

---

4.1 Estorno Total de uma Charge

Realiza o estorno completo do valor pago.

Quando usar

• Cancelamento integral da venda

• Fraude confirmada

• Erro operacional

📌 Referência: Estorno Total de um Pedido

---

4.2 Estorno Parcial de uma Charge

Realiza o estorno de parte do valor pago.

Quando usar

• Devolução parcial de produtos

• Ajustes comerciais

📌 Referência: Estorno Parcial de um Pedido

---

Pós-condições

Ao final deste caso de uso, o vendedor consegue:

• Autenticar-se na API da Barte

• Criar obrigatoriamente um Buyer

• Criar um pedido com pagamento via PIX, Boleto ou Cartão

• Consultar o status do pedido e da charge

• Realizar estorno total ou parcial de uma charge

---

Observações Importantes

• Um pedido nunca pode existir sem um Buyer

• O controle de status definitivo do pagamento deve ser feito via webhook

• Para operações idempotentes, utilize corretamente a idempotencyKey