> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autorizou.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Venda no Terminal

> Inicia uma venda presencial na maquininha a partir da sua aplicação e devolve o resultado

Inicia uma venda **presencial** na maquininha a partir da sua aplicação (um caixa, uma comanda, um
sistema de vendas). Você informa o **terminal** e o **valor**; a Autorizou dispara a cobrança no
aparelho, o portador paga, e a **mesma chamada** devolve o resultado.

A venda nasce escopada ao lojista da sua chave de API — você **não** envia `merchant_id`. A divisão
(split) para o recebedor dono do terminal é aplicada automaticamente; você não informa recebedor.

<Info>
  Chamada **síncrona**: a sua aplicação aguarda enquanto o portador paga no aparelho. O desfecho
  (`approved`, `declined` ou `unknown`) volta no corpo da resposta. Para o guia de integração ponta a
  ponta, veja [Aceitar pagamento na maquininha](/casos-uso/pos-maquininha).
</Info>

## Cabeçalhos

<ParamField header="Idempotency-Key" type="string" required>
  Chave de idempotência da venda. Reenviar a **mesma** chave **não** dispara uma segunda cobrança no
  aparelho — devolve a venda já em andamento (ou seu resultado final). É o que torna seguro repetir a
  chamada após timeout ou queda de rede. Use um valor único por venda (ex.: o ID da venda no seu
  sistema).
</ParamField>

## Parâmetros

<ParamField body="terminal_code" type="string" required>
  Código do terminal onde a venda será cobrada. É o identificador do aparelho no seu inventário.
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor da venda em **centavos** (ex.: `5200` = R\$ 52,00).
</ParamField>

<ParamField body="payment_method" type="string" required>
  Método presencial: `credit_card` ou `debit_card`.
</ParamField>

<ParamField body="installments" type="integer">
  Número de parcelas no crédito (1 a 12). Padrão `1`. Ignorado para `debit_card`.
</ParamField>

<ParamField body="external_reference" type="string">
  A sua referência própria da venda (ex.: número do pedido/comanda). Volta em todos os eventos e na
  consulta, para você conciliar sem guardar o `uuid` da Autorizou.
</ParamField>

```bash cURL theme={null}
curl -X POST "https://pay.autorizou.dev/api/v1/pos/sales" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Idempotency-Key: venda-8842" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_code": "POI0X9Q2T7K",
    "amount": 5200,
    "payment_method": "credit_card",
    "installments": 3,
    "external_reference": "PEDIDO-8842"
  }'
```

## Resposta

O corpo traz a venda no estado final da tentativa. **Trate o campo `state` sempre** — ele é a fonte da
verdade do desfecho.

```json theme={null}
{
  "uuid": "7c9e3b21-4a8d-4f16-9b2c-1d3e5f7a9c04",
  "state": "approved",
  "amount": 5200,
  "currency": "BRL",
  "payment_method": "credit_card",
  "installments": 3,
  "external_reference": "PEDIDO-8842",
  "terminal": {
    "code": "POI0X9Q2T7K",
    "serial_number": "S123456",
    "model": "AMS1"
  },
  "payment": {
    "uuid": "AUTOCC01KW2P8M4Q7K3M9QP",
    "status": "authorized"
  },
  "created_at": "2026-07-05 14:22:10"
}
```

<ResponseField name="uuid" type="string">
  Identificador único da venda na Autorizou. Use-o para consultar o estado em
  [`GET /pos/sales/{identifier}`](/api-reference/pos/get-pos-sale).
</ResponseField>

<ResponseField name="state" type="string">
  Desfecho da venda: `approved`, `declined`, `unknown` ou `aborted`. Veja a tabela abaixo.
</ResponseField>

<ResponseField name="amount" type="integer">
  Valor cobrado, em centavos.
</ResponseField>

<ResponseField name="currency" type="string">
  Moeda da venda (ex.: `BRL`).
</ResponseField>

<ResponseField name="payment_method" type="string">
  `credit_card` ou `debit_card`.
</ResponseField>

<ResponseField name="installments" type="integer">
  Parcelas aplicadas.
</ResponseField>

<ResponseField name="external_reference" type="string">
  A referência que você enviou.
</ResponseField>

<ResponseField name="terminal" type="object">
  O terminal onde a venda foi cobrada: `code`, `serial_number` e `model`.
</ResponseField>

<ResponseField name="payment" type="object">
  A cobrança gerada quando a venda é aprovada: `uuid` e `status`. Ausente quando `state` não é
  `approved`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data/hora de criação da venda.
</ResponseField>

## Estados da venda

| `state`    | O que significa                                                          | O que a sua aplicação faz                                                                                                         |
| ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `approved` | Pagamento aprovado no aparelho                                           | Concluir a venda. O webhook [`payment.authorized`](/api-reference/pos/pos-webhook) chega em seguida com o bloco `pos`             |
| `declined` | Pagamento recusado pelo portador/emissor                                 | Oferecer nova tentativa (nova chamada, **nova** `Idempotency-Key`)                                                                |
| `aborted`  | Cancelada antes de pagar (operador/portador desistiu no aparelho)        | Encerrar sem cobrança                                                                                                             |
| `unknown`  | **Ainda não sabemos o resultado** — timeout ou queda no meio da cobrança | **Consultar** [`GET /pos/sales/{identifier}`](/api-reference/pos/get-pos-sale) até resolver. **Nunca** reenviar a venda cegamente |

<Warning>
  **A regra de ouro:** `unknown` **não é falha** — é "ainda não sei". Reenviar a venda nesse estado
  pode cobrar o cliente duas vezes. Se precisar repetir a chamada por segurança de rede, use a
  **mesma** `Idempotency-Key`: você recebe a venda em andamento, não uma segunda cobrança.
</Warning>

## Erros

`declined`, `aborted` e `unknown` são **desfechos de negócio** e voltam com HTTP `200` — não são erros
de API. Os erros abaixo são de validação/requisição:

| HTTP  | Quando                                                                                                   |
| ----- | -------------------------------------------------------------------------------------------------------- |
| `401` | Chave de API ausente ou inválida                                                                         |
| `404` | `terminal_code` não existe ou não pertence ao seu lojista                                                |
| `422` | Corpo inválido (valor abaixo do mínimo, `payment_method` desconhecido, `installments` fora do intervalo) |