# Qual a diferença entre Pedido (Order) e Cobrança (Charge)

**Resumo rápido**

* **Order** = *pedido / intenção de venda*. Representa o contexto comercial: quem compra, o que está sendo comprado, valor total, parcelas, metadata e regras de negócio.
* **Charge** = *ação de cobrança / evento financeiro*. Representa a tentativa/registro de cobrança efetiva (autorização, captura, estorno, etc.). Uma order pode ter 1 ou várias charges associadas.

***

### Conceito detalhado

#### Order (pedido)

* É a entidade de **nível de negócio**.
* Contém informações como `uuid` do comprador (`uuidBuyer`), `value` total, `installments`, `title`, `description`, `metadata` e dados que descrevem a venda.
* A order **não é uma cobrança em si** — é o agrupador/contrato que descreve a transação a ser cobrada.
* A order controla o fluxo: regras de pagamento, parcelamento, soft descriptor, vínculo com split, entre outros.

#### Charge (cobrança)

* É a entidade de **nível financeiro** que representa uma tentativa ou registro de débito contra um meio de pagamento.
* Cada charge tem seu próprio `uuid`, `value` (pode ser parcial ou total), `expirationDate`, `status` e outros campos específicos.
* Operações financeiras (capturar, estornar, cancelar, antecipar, consultar status, reprocessar) são feitas **sobre charges**, não sobre a order.

***

### Quando uma order gera múltiplas charges

* **Parcelamento no tempo (ex.: 3x, 4x sem juros)**
  * Quando a order é parcelada em **fluxo do tempo**, são criadas **múltiplas charges**, uma por parcela.
  * Cada charge representa a cobrança daquele vencimento específico (valor da parcela, data de vencimento, status próprio).
  * Isso facilita conciliação, reprocessamento de parcelas individualmente e controle de inadimplência por parcela.
* **Captura única / Antecipação**
  * Quando a operação é feita via **antecipação** (ex.: `CREDIT_CARD_EARLY_SELLER ou CREDIT_CARD_EARLY_BUYER`), normalmente **apenas uma charge** é criada para a order (representando o valor total que será antecipado).
  * Ou seja: em cenários de antecipação, não se fragmenta em múltiplas charges por parcela — a cobrança é consolidada.

***

### Status e ciclo de vida (visão prática)

* **Order**: tipicamente possui status como `SENT, ABANDONED, PAID, CANCELED, LATE, PARTIALLY_PAID, REFUND, CHARGEBACK e PRE_AUTHORIZED.`
* **Charge**: status financeiro como `PENDING, AUTHORIZED, CAPTURED, CANCELED, REFUNDED, PARTIALLY_REFUNDED, CHARGEBACK, EXPIRED.`

***

### Onde operar cada ação (prática para devs)

* **Criação de pedido** → `POST /v2/orders` (enviar `uuidBuyer`, `value`, `installments`, `payment`, `metadata`, etc.).

{% content-ref url="<https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/pedidos-e-cobrancas/criar-pedido>" %}
[Criar Pedido](https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/pedidos-e-cobrancas/criar-pedido)
{% endcontent-ref %}

* **Consultas de status** → buscar tanto a order quanto as charges associadas; **sempre** verifique o status da charge para decisões financeiras.
* **Captura** → `POST /v2/charges/{uuid}/capture` (opera sobre a charge).

{% content-ref url="como-funciona-a-pre-captura" %}
[como-funciona-a-pre-captura](https://docs.barte.com/guias/pedidos-e-cobrancas/como-funciona-a-pre-captura)
{% endcontent-ref %}

* **Estorno / Refund** → ação sobre a charge (ou sobre transação financeira específica retornada pela charge).

{% content-ref url="<https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/estorno>" %}
[Estorno](https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/estorno)
{% endcontent-ref %}

* **Cancelamento** → pode existir endpoint de cancelamento de order e/ou de charge — o cancelamento financeiro efetivo age sobre charges.

{% content-ref url="<https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/pedidos-e-cobrancas/cobrancas/cancelar-cobranca>" %}
[Cancelar Cobrança](https://app.gitbook.com/s/hY03QzfTvLWOjOsYfPiz/pedidos-e-cobrancas/cobrancas/cancelar-cobranca)
{% endcontent-ref %}

***

### Boas práticas de implementação

1. **Guarde ambos os IDs**: mantenha `order.uuid` e `charge.uuid` no seu sistema para rastrear contexto de negócio e eventos financeiros separadamente.
2. **Conciliação**: faça reconciliação financeira por **charge** (cada charge é um evento financeiro com status e valores próprios).
3. **Webhooks**: escute eventos de charge e eventos de order quando existirem — atualize seu domínio por charge e, quando apropriado, sincronize o status da order.
4. **Retries**: use o campo `retryable` para decidir se vale a pena re-tentar a captura. Não tente capturar indefinidamente.
5. **Pré-captura**: se adotar pré-captura (`capture: false`), implemente um processo para: (a) rodar verificações antifraude; (b) capturar dentro do prazo (ex.: 6 dias); (c) cancelar e notificar quando não capturado.
6. **Metadados**: utilize `metadata` na order para ligar facilmente a order/charge ao seu ERP, pedido interno ou referência do cliente.
7. **Erros e idempotência**: ao criar orders/charges, use chaves de idempotência para evitar duplicidade em falhas de rede.

***

### Onde aplicar cada entidade na sua arquitetura

* **Order** → camada de aplicação / domínio (o “pedido” que seu negócio precisa rastrear).
* **Charge** → camada de pagamentos / financeira (monitoramento de autorizações, capturas, estornos e repasses).