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

***

### 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](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api.md)
* O comprador (**Buyer**) **deve existir** antes da criação do pedido
  * Link rápido → [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador.md)

***

### 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](/guias/pedidos-e-cobrancas/criando-um-comprador.md)

***

#### 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](/guias/inicio/metodos-de-pagamento.md)

***

**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)](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-simples-pix-boleto-e-cartao-de-credito.md)

***

### 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: [Broken mention](broken://pages/ViMdmEsIYlAS47pmO6m5)

***

#### 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 de um Pedido](/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/estorno-parcial-de-um-pedido.md)

***

### 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/use-case-pedido-simples-pix-boleto-e-cartao-de-credito.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.