# Campos dos Webhooks

Os webhooks são enviados sempre que ocorre uma atualização em **pedidos (ORDER)**, **assinaturas (SUBSCRIPTION)** ou **transações físicas/pos (PHYSICAL\_ORDER)**.\
Cada evento contém um conjunto de campos padronizados, que variam conforme o tipo de domínio e o status da transação.

***

### <i class="fa-shield-check">:shield-check:</i> Headers da Requisição

Cada webhook é enviado com os seguintes headers HTTP para garantir autenticidade, unicidade e segurança:

| Header                  | Tipo      | Descrição                                                                                                        |
| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| **X-Webhook-Timestamp** | `integer` | Unix epoch (segundos) no momento do envio. Permite detectar requisições antigas ou repetidas.                    |
| **X-Webhook-Nonce**     | `string`  | 32 caracteres hexadecimais (128 bits de aleatoriedade). Garante unicidade por requisição, prevenindo duplicatas. |
| **idempotency-key**     | `string`  | Chave de idempotência para garantir que requisições repetidas não causem efeitos duplicados.                     |
| **authorization**       | `string`  | Token de autenticação para validar a origem da requisição.                                                       |

> 💡 **Dica de Segurança:**\
> Recomendamos validar o timestamp para detectar requisições antigas (fora de uma janela de tolerância, ex: 5 minutos) e verificar a unicidade do nonce para evitar processamento duplicado de webhooks.

***

### <i class="fa-octagon-check">:octagon-check:</i> Campos Comuns

| Campo                 | Tipo      | Descrição                                                                                                                                                                                                                            |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **uuid**              | `string`  | Identificador único do pedido (`ORDER`), assinatura (`SUBSCRIPTION`) ou cobrança física (`PHYSICAL_ORDER`).                                                                                                                          |
| **dateTime**          | `string`  | Data e hora da ocorrência no formato ISO 8601 — `YYYY-MM-DDTHH:MM:SS`.                                                                                                                                                               |
| **status**            | `string`  | Status atual da cobrança ou assinatura. Veja Status possíveis.                                                                                                                                                                       |
| **domain**            | `string`  | <p>Tipo de evento:<br>• <code>ORDER</code> → Cobrança pontual<br>• <code>SUBSCRIPTION</code> → Assinatura recorrente<br>• <code>PHYSICAL\_ORDER</code> → Cobrança de maquininha</p>                                                  |
| **uuidBuyer**         | `string`  | Identificador único do comprador. Pode ser usado para buscar mais detalhes via API `/v2/buyers/{uuid}`.                                                                                                                              |
| **documentBuyer**     | `string`  | CPF ou CNPJ do comprador.                                                                                                                                                                                                            |
| **emailBuyer**        | `string`  | E-mail do comprador.                                                                                                                                                                                                                 |
| **address**           | `object`  | <p>Objeto com os dados de endereço do comprador:<br><code>country</code>, <code>state</code>, <code>city</code>, <code>district</code>, <code>street</code>, <code>zipCode</code>, <code>number</code>, <code>complement</code>.</p> |
| **metadata**          | `array`   | Lista de pares `{ key, value }` contendo informações adicionais enviadas durante a criação da cobrança.                                                                                                                              |
| **cnpjSeller**        | `string`  | CNPJ do vendedor responsável pela transação.                                                                                                                                                                                         |
| **idSeller**          | `integer` | Identificador interno do vendedor.                                                                                                                                                                                                   |
| **authorizationCode** | `string`  | Código de autorização da transação (quando aplicável).                                                                                                                                                                               |
| **authorizationNsu**  | `string`  | NSU (Número Sequencial Único) da transação (quando aplicável).                                                                                                                                                                       |
| **cards**             | `array`   | Lista de cartões associados à cobrança (quando disponível).                                                                                                                                                                          |
| **refunds**           | `array`   | Lista de estornos associados à cobrança.                                                                                                                                                                                             |

> 💡 **Dica:**\
> O campo `uuid` pode ser utilizado nas rotas:
>
> * `GET /v2/subscriptions/{uuid}` → Para consultar detalhes e cobranças da assinatura
> * `GET /v2/orders/{uuid}` → Para consultar detalhes e cobranças de uma cobrança pontual

***

### <i class="fa-credit-card">:credit-card:</i> Campos Exclusivos de `PHYSICAL_ORDER`

| Campo                   | Tipo      | Descrição                                       |
| ----------------------- | --------- | ----------------------------------------------- |
| **amount**              | `number`  | Valor total pago.                               |
| **installments**        | `integer` | Quantidade de parcelas escolhidas.              |
| **first4\_digits**      | `string`  | Primeiros 4 dígitos do cartão.                  |
| **last4\_digits**       | `string`  | Últimos 4 dígitos do cartão.                    |
| **holderName**          | `string`  | Nome do titular do cartão.                      |
| **brand**               | `string`  | Bandeira do cartão (ex: Visa, Elo, Mastercard). |
| **authorization\_code** | `string`  | Código de autorização da operadora.             |
| **authorization\_nsu**  | `string`  | NSU (Número Sequencial Único) da transação.     |
| **pos\_id**             | `string`  | Identificador do terminal (POS).                |
| **cnpj**                | `string`  | CNPJ da empresa portadora da maquininha.        |
| **company\_name**       | `string`  | Nome da empresa portadora da maquininha.        |
| **serial\_number**      | `string`  | Número de série do terminal POS.                |
| **payment\_type**       | `string`  | Tipo de pagamento (ex: `credit`, `debit`).      |
| **rate**                | `number`  | Taxa aplicada à transação.                      |

***

### <i class="fa-puzzle-piece">:puzzle-piece:</i> Status Possíveis

#### 🔸 Pedidos (`ORDER/PHYSICAL_ORDER`)

| Status              | Descrição                                          |
| ------------------- | -------------------------------------------------- |
| **SENT**            | Pedido criado.                                     |
| **PAID**            | Pagamento confirmado.                              |
| **PARTIALLY\_PAID** | Pagamento parcial recebido.                        |
| **LATE**            | Pagamento atrasado.                                |
| **ABANDONED**       | Pedido abandonado (ex: atraso superior a 90 dias). |
| **CANCELED**        | Pedido cancelado.                                  |
| **REFUND**          | Pedido estornado.                                  |
| **CHARGEBACK**      | Pedido com chargeback.                             |
| **PRE\_AUTHORIZED** | Pedido pré-autorizado.                             |
| **DISPUTE**         | Pedido entrou em disputa.                          |
| **DISPUTE\_ALERT**  | Alerta de disputa recebido.                        |

***

#### 🔹 Assinaturas (`SUBSCRIPTION`)

| Status        | Descrição                                               |
| ------------- | ------------------------------------------------------- |
| **PENDING**   | Assinatura criada, aguardando confirmação de pagamento. |
| **ACTIVE**    | Assinatura ativa.                                       |
| **DEFAULTER** | Assinatura inadimplente.                                |
| **INACTIVE**  | Assinatura encerrada.                                   |

***

O campo `address` está presente em todos os domínios (`ORDER`, `SUBSCRIPTION`, `PHYSICAL_ORDER`) e segue o formato abaixo:

```json
"address": {
  "country": "BR",
  "state": "SP",
  "city": "São Paulo",
  "district": "Pinheiros",
  "street": "Rua dos Pinheiros",
  "zipCode": "05422-001",
  "number": "850",
  "complement": "Sala 12"
}
```


---

# 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/webhooks/campos-dos-webhooks.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.