Informações Comuns

Em diversos cenários de integração com a API do PinPDV, são requeridas informações específicas e/ou procedimentos operacionais. A seguir, são descritos os elementos mais recorrentes e essenciais ao processo de integração.

Autenticação#

Para gerar um token de longa duração para cada cliente (estabelecimentoId), acesse o portal do PinPDV em Configurações → Tokens de Acesso → Cadastrar e crie um novo token.

Esse tipo de token é recomendado para integração com aplicações instaladas no ambiente do cliente, pois possui validade estendida e reduz a necessidade de renovações frequentes. Após a geração, armazene-o de forma segura e utilize-o nas requisições realizadas pela aplicação.

Status Utilizados#

Nesta seção estão definidos os status padronizados utilizados nos processos de venda, pagamento e tipo de pagamento dentro da integração com a API do PINPDV.

Venda#

Realizada = 0,
Cancelada = 8,
Error = 9

Pagamento#

Aguardando = 0,
Processando = 1,
Concluido = 2

Tipo de Pagamento#

None = 0,
Dinheiro = 1,
Credito = 2,
Debito = 3,
Pix = 4,
ValeRefeicao = 6,
ValeAlimentacao = 7

Listar Empresas#

Nas requisições onde é necessário o envio do código de empresa, previamente deve ser feita esta consulta, ela possui os seguintes parâmetros de ordenação:

OrdenarPor = (Id, Nome, Cnpj, CadastradoEm, AtualizadoEm)
OrdenarTipo = (ASC, DESC)

curl --request GET \
  --url {URL}/empresa?OrdenarPor=Id&OrdenarTipo=DESC \
  --header 'Authorization: Bearer xyz' \

200 - OK

{
  "paginaAtual": 1,
  "itensPorPagina": 100,
  "quantidadeDePaginas": 1,
  "quantidadeTotalDeItens": 1,
  "primeiroRegistro": 1,
  "ultimoRegistro": 1,
  "paginaAnterior": false,
  "paginaProxima": false,
  "data": [
    {
      "id": 1,
      "nome": "61492096000147",
      "cnpj": "61.492.096/0001-47",
      "representante": {
        "id": 2,
        "nome": "61492096000147",
        "usuario": "61492096000147",
        "webhook": null
      }
    }
  ]
}

Listar Dispositivos#

Em algumas funções é necessário que seja informado o dispositivo em que será realizada a transação, previamente deve ser realizada uma consulta para verificar quais estão disponíveis através do endpoint /pinpdv.

curl --request GET \
  --url '{URL}/pinpdv' \
  --header 'Authorization: Bearer xyz' \

200 - OK

{
	"paginaAtual": 1,
	"itensPorPagina": 100,
	"quantidadeDePaginas": 1,
	"quantidadeTotalDeItens": 2,
	"primeiroRegistro": 1,
	"ultimoRegistro": 2,
	"paginaAnterior": false,
	"paginaProxima": false,
	"data": [
		{
			"id": 1,
			"codigo": "526989",
			"nome": "CAIXA 01",
			"isAtivo": true,
			"heartbeat": "2024-10-04T15:49:28.894765"
		},
		{
			"id": 2,
			"codigo": "687836",
			"nome": "CAIXA 02",
			"isAtivo": true,
			"heartbeat": "2024-10-01T15:04:15.204673"
		}
	]
}

Impressão de Documentos#

Ao término dos processos que oferecem suporte à impressão de documentos fiscais ou não fiscais, o sistema, caso a impressão seja executada, deverá aplicar uma das abordagens de finalização descritas a seguir.

• URL de Webhook

É a melhor experiência de integração; no final de cada processo que permite impressão de documento é realizada chamada para URL de webhook informando que houve uma venda.

{
    "id": 288581,
    "identificador": "f092b6bb80004bc58a63e393ed76a2eb",
    "tipoVenda": {
        "key": 1,
        "value": "Expressa"
    },
    "valor": 20.0000,
    "isDocumento": false,
    "cadastradoEm": "2026-04-30T14:59:58.573",
    "cadastradoPor": {
        "id": 46,
        "nome": "CLIENTE HOMOLOGACAO (D) - VENDA FALSA",
        "dataHora": "2026-04-30T14:59:58.573"
    },
    "status": {
        "key": 0,
        "value": "Realizada"
    },
    "transacoes": [
        {
            "id": 256657,
            "valor": 20.0000,
            "parcelas": 1,
            "cadastradoEm": "2026-04-30T15:00:00.688",
            "atualizadoEm": "2026-04-30T15:00:08.307772",
            "cadastradoPor": {
                "id": 46,
                "nome": "CLIENTE HOMOLOGACAO (D) - VENDA FALSA",
                "dataHora": "2026-04-30T15:00:00.688"
            },
            "atualizadoPor": {
                "id": 46,
                "nome": "CLIENTE HOMOLOGACAO (D) - VENDA FALSA",
                "dataHora": "2026-04-30T15:00:08.307772"
            },
            "status": {
                "key": 0,
                "value": "Aprovada"
            },
            "tipoPagamento": 3,
            "pagamentoTipo": {
                "key": 3,
                "value": "Debito"
            },
            "dados": {
                "dataHora": "2026-04-30T15:00:00.688",
                "nsu": "000000214",
                "autorizacao": "164550",
                "bandeira": "MASTERCARD",
                "adquirente": "Getnet"
            }
        }
    ],
    "produtos": [],
    "pinPdv": {
        "id": 1225,
        "codigo": "449263",
        "nome": "Getnet 449263"
    },
    "dispositivo": {
        "id": 1225,
        "codigo": "449263",
        "nome": "Getnet 449263"
    },
    "isCancelamento": false
}

A resposta pode ser o documento a ser impresso, ou então nenhum conteúdo. Se houver resposta com conteúdo para impressão no webhook, esse conteúdo será impresso no APP PINPDV. Se não houver conteúdo, o sistema pode enviar o documento assim que estiver pronto, contudo, uma vez que o usuário saia da tela que executa a impressão não há alternativa de reimpressão.

• Configurar mensagem padrão de resposta (Em breve)

Caso o sistema não disponha de endereço de webhook, é uma boa alternativa.

A API PINPDV se encarrega de sempre devolver um comprovante padrão de resposta mediante configuração do sistema parceiro. Essa resposta padrão pode por exemplo, ser uma lista dos produtos e a forma de pagamento.

• Polling na API PINPDV

Apesar de disponível, não é recomendado, principalmente devido ao “timing” da informação. O rate-limit entre as chamadas deve ser respeitado. O sistema parceiro se encarrega de periodicamente monitorar as vendas realizadas no app PINPDV que não possuem documento gerado e providenciar o respectivo conteúdo.

Atualizando o Documento (Comprovante)#

Dependendo da escolha do sistema quanto a geração de documento, o endpoint para atualizar o conteúdo deve ser usado, considerar sempre 40 caracteres. O texto será posicionado ao centro. Não há opção de formatação. O codigo de venda é retornado na resposta da requisição anterior. Exemplo, na resposta de status da pré-venda vai constar um objeto venda e seu ID.

curl --request PUT \
  --url '{URL}/venda/{vendaIdentificador}/comprovante' \
  --header 'Authorization: Bearer xyz' \
  --header 'Content-Type: text/plain' \
  --data '         Aviso de comprovante          '
LINHA 1
                                 LINHA 2
LINHA 3'

202 - OK

Coleção do Postman#

Para facilitar a integração e a realização de testes, disponibilizamos uma coleção do Postman contendo os principais endpoints da API do PinPDV.

Com ela, é possível importar rapidamente as requisições, configurar o ambiente e executar chamadas sem necessidade de montar manualmente cada request.

Download da coleção do Postman