Pré-venda ⭐

Seu sistema cria e acumula múltiplas pré-vendas abertas ao mesmo tempo. Cada operador visualiza a lista no Smart POS e finaliza a que é sua — ideal para delivery, postos de combustível, mesas de restaurante e atendimento em campo.

Diferente do TEF Mobile (que processa um pagamento por vez), a Pré-venda permite que várias solicitações coexistam simultaneamente. Além do valor, você pode enviar a lista de produtos com código, quantidade e descrição — útil para exibição no Smart POS e para integração com documentos fiscais.

Endpoints#

Validando no portal antes de integrar#

No Portal do Cliente, você pode criar pré-vendas manualmente e ver o comportamento completo no Smart POS antes de integrar.

Criando uma pré-venda#

O bloco Produtos é opcional: você pode criar a pré-venda apenas com valor e descrição, ou incluir a lista de itens para exibição no Smart POS.

Sem produtos:

curl --request POST \
  --url 'https://api.pinpdv.com.br/pre-venda' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "Identificador": "mesa-01",
    "Valor": 34.83,
    "Descricao": "Mesa 01"
  }'

Com produtos:

curl --request POST \
  --url 'https://api.pinpdv.com.br/pre-venda' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "Identificador": "mesa-01",
    "Valor": 34.83,
    "Descricao": "Mesa 01",
    "Parcelas": 1,
    "TipoPagamento": 3,
    "PinPdvId": 1,
    "Produtos": [
      {
        "Identificador": "coca-01",
        "Quantidade": 2
      }
    ]
  }'

200 - OK

{
  "id": 8240,
  "identificador": "mesa-01",
  "descricao": "Mesa 01",
  "valor": 34.83,
  "parcelas": 1,
  "tipoPagamento": 3,
  "pagamentoTipo": { "key": 3, "value": "Debito" },
  "status": { "key": 0, "value": "Aguardando" },
  "situacao": { "key": 0, "value": "Aguardando" },
  "grupos": [ { "identificador": "grupo-padrao", "nome": "Padrão" } ],
  "produtos": null,
  "vendas": []
}

A pré-venda criada aparecerá automaticamente na lista do Smart POS para o operador finalizar.

Acompanhando o status#

Depois de criar a pré-venda, você precisa saber quando o operador a finaliza no Smart POS — e se o pagamento foi aprovado ou negado. Há duas formas de receber esse retorno; escolha a que melhor se encaixa no seu sistema:

Webhook (o PINPDV avisa você)#

Cadastre uma URL de webhook no Portal do Cliente PINPDV. A partir daí, o PINPDV chama sua URL via POST automaticamente a cada mudança na venda — criação, atualização de status e conclusão — enviando o mesmo conteúdo da consulta de status. É o caminho mais eficiente: dispensa polling e respeita o rate limit naturalmente.

O payload, a ativação da URL e o uso da resposta estão detalhados em Webhook.

Polling (o seu sistema pergunta)#

Se não houver webhook cadastrado, consulte periodicamente o status usando o Identificador definido na criação. Respeite o rate limit de 1 requisição por segundo.

curl --request GET \
  --url 'https://api.pinpdv.com.br/pre-venda/{Identificador}' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

Como interpretar a resposta#

A estrutura segue três níveis hierárquicos — leia de fora para dentro:

Aguardando pagamento (pré-venda criada, ainda não finalizada por nenhum operador):

200 - OK

{
  "id": 347260,
  "identificador": "P1-0407014603",
  "descricao": "Homolog P1 GN credito",
  "valor": 1.20,
  "status": {
    "key": 0,
    "value": "Aguardando"
  },
  "vendas": []
}

Pagamento aprovado:

200 - OK

{
  "id": 347260,
  "identificador": "P1-0407014603",
  "descricao": "Homolog P1 GN credito",
  "valor": 1.20,
  "status": {
    "key": 2,
    "value": "Concluido"
  },
  "vendas": [
    {
      "identificador": "ea77eb6b0b514b97b6ab76208b428a9b",
      "valor": 1.20,
      "status": { "key": 0, "value": "Realizada" },
      "transacoes": [
        {
          "valor": 1.20,
          "parcelas": 1,
          "status": { "key": 0, "value": "Aprovada" },
          "tipoPagamento": 2,
          "dados": {
            "dataHora": "2026-07-04T01:46:38.560",
            "nsu": "000000368",
            "autorizacao": "164550",
            "bandeira": "MASTERCARD",
            "adquirente": "Getnet"
          }
        }
      ],
      "pinPdv": { "codigo": "283190", "nome": "Getnet 283190" }
    }
  ]
}

Sem pagamento aprovado (operador cancelou a pré-venda no Smart POS antes de concluir o pagamento):

200 - OK

{
  "id": 347262,
  "identificador": "P7-0407014720",
  "descricao": "Homolog P7 GN cancelar",
  "valor": 1.27,
  "status": {
    "key": 2,
    "value": "Concluido"
  },
  "vendas": [
    {
      "identificador": "b52373d57dd14d4b9257fd1db0274e95",
      "valor": 1.27,
      "status": { "key": 8, "value": "Cancelada" },
      "transacoes": [
        {
          "valor": 1.27,
          "parcelas": 1,
          "status": { "key": 78, "value": "CanceladaOperador" },
          "tipoPagamento": 2,
          "dados": {
            "dataHora": "2026-07-04T01:47:29.296",
            "nsu": null,
            "autorizacao": null,
            "bandeira": null,
            "adquirente": null
          }
        }
      ],
      "pinPdv": { "codigo": "283190", "nome": "Getnet 283190" }
    }
  ]
}

Assim como no TEF Mobile, o nível 2 (vendas[0].status.value) já denuncia a ausência de pagamento — "Cancelada" em vez de "Realizada" — mesmo com a requisição (status.value = "Concluido") tendo terminado seu processamento.

Interrompendo uma pré-venda#

Enquanto o operador não tiver iniciado a transação no Smart POS, você pode cancelar a solicitação pelo sistema:

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/pre-venda/{Identificador}' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Interrupção forçada#

Se precisar cancelar uma pré-venda que já está em processamento no Smart POS:

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/pre-venda/{Identificador}?forca=true' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Cancelamento de venda já paga#

Envie sua impressão#

O fluxo de impressão é idêntico ao dos demais módulos — via webhook (recomendado) ou envio direto pela API após confirmar a conclusão via consulta de status.

Consulte Impressão para o detalhamento completo do webhook, do endpoint PUT /venda/{vendaIdentificador}/comprovante e da impressão de QR Code.