APIs: Exemplo mínimo para uma venda
Nesta página mostraremos, com exemplos, o fluxo mínimo para uso até a realização de uma venda.
Obtendo a chave de integração
Não é necessário realizar sempre um login!
Caso deseje, o usuário pode realizar logins na plataforma para recuperar sua chave de integração. Contudo, este método está sujeito à expiração de sua senha de tempos em tempos.
Caso o usuário queira ter uma chave de integração para uso sem se preocupar com expirações de senha, recomendamos a criação de uma chave sem expiração, como informado em APIs/Chave de integração
Caso o usuário não tenha ainda uma chave fixa e queira realizar o teste de exemplo mínimo, o primeiro passo é realizar um login. Faremos um login no ambiente de sandbox, então teremos a chamada com as informações abaixo:
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaSuaAutomacao/1.0 |
{
"cpfCnpj": "{{cpfCnpj}}",
"senha": "{{senha}}"
}
Exemplo de chamada de Login/Login
Será enviado um POST para a API que responderá algo semelhante ao que se encontra abaixo:
{
"data": "12/11/2024 12:00:11.2571",
"pessoa": {
"key": "7402n3984cr2po9d8eyurp1q9xyumq8ync4ytqri3tyo93q",
"id": 12579,
"pessoaJuridica": false,
"nomeRazaoSocial": "Pessoa do exemplo",
"sobrenomeNomeFantasia": "Nome do Exemplo",
"email": "[email protected]",
"fotoThumbnail": "https://sandbox.controlpay.com.br/fotos/foto.png",
"pessoaStatus": {
"id": 2,
"nome": "Vendedor"
}
},
"operador": null
}
Desta resposta, o que nos importa é a chave de integração "key". Daqui em diante, usaremos o valor fictício "7402n3984cr2po9d8eyurp1q9xyumq8ync4ytqri3tyo93q" como nossa chave para as chamadas de API. Este valor deve ser enviado na URL das chamadas, no parâmetro "key".
Realizando uma venda
Agora realizaremos uma venda usando a chave que obtivemos na chamada anterior (ou a chave cadastrada pelo usuário).
Troque acima a chave de integração pela sua chave.
No endpoint acima, trocando a chave, realizaremos uma venda. Para isso, lembre-se que é necessário ter um PayGo Windows instalado na máquina no ambiente de desenvolvimento. Para mais informações sobre isto, veja instalação do PayGo Windows em sandbox.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
No corpo da API, preencheremos:
-
a forma de pagamento = 21 (TEF Crédito);
-
o ID do terminal = 1234 (preencha com um de seus terminais);
-
uma observação = "Venda teste";
-
iniciar automaticamente = true (indicando que a venda deve começar automaticamente);
-
parcelamento admin. = true (indicando que, caso a venda fosse parcelada, seria parcelamento administrativo);
-
quantidade de parcelas = 1;
-
valor total vendido = 1 real.
{
"formaPagamentoId": 21,
"pedidoId": null,
"terminalId": "1234",
"observacao": "Venda teste",
"aguardarTefIniciarTransacao": true,
"parcelamentoAdmin": true,
"quantidadeParcelas": 1,
"valorTotalVendido": "1,00"
}
Exemplo de chamada de venda
Será enviado um POST para a API que responderá algo semelhante ao que se encontra abaixo:
{
"data": "12/11/2024 12:21:16.3613",
"intencaoVenda": {
"id": 2015371,
"referencia": null,
"token": "822446",
"data": "12/11/2024 12:21:16.3613",
"hora": "12:21:16",
"quantidade": 0,
"valorOriginal": 1,
"valorOriginalFormat": "1,00",
"valorAcrescimo": 0,
"valorAcrescimoFormat": "0,00",
"valorDesconto": 0,
"valorDescontoFormat": "0,00",
"valorFinal": 1,
"valorFinalFormat": "1,00",
"gate2allToken": null,
"quantidadeParcelas": 1,
"urlPagamento": null,
"formaPagamento": {
"id": 21,
"nome": "TEF",
"modalidade": "Crédito",
"fluxoPagamento": {
"id": 21,
"nome": "TEF"
}
},
"terminal": {
"id": 1234,
"nome": "TerminalTeste"
},
"pagamentosExternos": [
{
"id": 2025992,
"tipo": 5,
"idPagamento": "",
"origem": 5,
"tipoParcelamento": 1,
"pagamentoExternoStatus": {
"id": 10,
"nome": "Em Operação"
}
}
],
"intencaoVendaStatus": {
"id": 6,
"nome": "Em Pagamento"
},
"cliente": null,
"produtos": [],
"pedido": null
}
}
Com o envio desta chamada, o PayGo Windows irá subir uma nova janela, iniciando uma transação:
Tela de processamento de transação
Com essa tela, siga os passos que aparecerão na tela para completar a transação. Para os próximos passos, guarde as informações "intencaoVenda" -> "id" ("2015371") e "pagamentoExterno" -> "id" ("2025992").
Consulta de uma venda
Agora que realizamos uma venda, consultaremos ela no sistema para verificar o seu status. Para isso, é possível a utilizar duas APIs:
- IntencaoVenda/GetById;
- IntencaoVenda/GetByFiltros.
Por motivos didáticos, faremos ambas as consultas.
Pesquisa por ID
A pesquisa por ID de uma intenção de venda é uma chamada simples sem corpo de requisição através da URL abaixo:
Troque acima a chave de integração pela sua chave e a o ID da intenção de venda pelo ID gerado pela sua chamada de venda.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
Exemplo de pesquisa de intenção de venda por ID
Com o envio do POST acima, a API responderá com algo semelhante ao que se encontra abaixo:
{
"data": "12/11/2042 13:38:03.3209",
"intencaoVenda": {
"id": 2015371,
"token": "822446",
"data": "12/11/2024 12:21:16.3613",
"hora": "12:21:16",
"dataAtualizacao": "12/11/2024 12:23",
"quantidade": 0,
"valorOriginal": 1,
"valorOriginalFormat": "1,00",
"valorAcrescimo": 0,
"valorAcrescimoFormat": "0,00",
"valorDesconto": 0,
"valorDescontoFormat": "0,00",
"valorFinal": 1,
"valorFinalFormat": "1,00",
"gate2allToken": null,
"latitude": null,
"longitude": null,
"quantidadeParcelas": 1,
"urlPagamento": null,
"formaPagamento": {
"id": 21,
"nome": "TEF",
"modalidade": "Crédito",
"fluxoPagamento": {
"id": 21,
"nome": "TEF"
}
},
"intencaoVendaStatus": {
"id": 10,
"nome": "Creditado"
},
"pedido": null,
"vendedor": {
"id": 12579,
"nomeRazaoSocial": "Pessoa do exemplo",
"sobrenomeNomeFantasia": "Nome do Exemplo",
"fotoThumbnail": ""
},
"cliente": null,
"produtos": [],
"pagamentosExternos": [
{
"id": 2025992,
"tipo": 5,
"idPagamento": "",
"dataAdquirente": "12/11/2024 12:23",
"dataAtualizacao": null,
"origem": 15,
"autorizacao": "153624",
"pagamentoExternoStatus": {
"id": 15,
"nome": "Finalizado"
},
"nomeTitularCartao": null
}
],
"operador": null
}
}
Pesquisa por filtros
A pesquisa por filtros pode ser usada quando não se tiver um ID ou certeza absoluta das informações da intenção de venda, servindo mais como uma pesquisa geral do que como uma pesquisa direta.
Troque acima a chave de integração pela sua chave.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
Essa pesquisa é um POST que pode ter diversos filtros. Abaixo temos os possíveis parâmetros que podem ser usados nessa pesquisa:
| Parâmetro | Explicação / Exemplo |
|---|---|
| pessoaId | ID da Pessoa que realizou a venda / Exemplo: 12579 |
| intencaoVendaId | ID da intenção de venda / Exemplo: 2015371 |
| formaPagamentoId | ID da forma de pagamento usada / Exemplo: 21 |
| terminalId | ID do terminal usado na venda / Exemplo: 1234 |
| clienteId | ID de um cliente ao qual foi realizada a venda / Exemplo: 7569 |
| operadorId | ID do operador da pessoa que realizou a venda / Exemplo: 9874 |
| status | Status da intenção de venda / Exemplo: 10 |
| dataInicio | Data de início do filtro para retorno das vendas / Exemplo: 10/05/2024 |
| dataFim | Data de fim do filtro para retorno das vendas / Exemplo: 10/06/2024 |
| dataAtualizacaoInicio | Data de atualização de início do filtro para retorno das vendas / Exemplo: 10/05/2024 |
| dataAtualizacaoFim | Data de atualização de fim do filtro para retorno das vendas / Exemplo: 10/05/2024 |
| referencia | Referência atribuída à(s) venda(s) / Exemplo: "Venda teste" |
| gate2allToken | Token gerado pelo Gateway para uma venda sem cartão presente / Exemplo: xyzw-a5df8-of69es1 |
| pagamentosRecorrente | Booleano indicando se é um pagamento recorrente. / Exemplo: false |
Com isso em mente, basta colocar quaisquer destes parâmetros no body da requisição que a API responderá com uma coleção de requisições que atendam aos filtros desejados.
{
"data": "01/06/2022 09:57:43.0904",
"intencoesVendas": [
{
"INTENÇÃO DE VENDA 1"
},
{
"INTENÇÃO DE VENDA 2"
},
...
]
}
Acima temos o layout padrão simplificado da resposta da API. No lugar onde esta "INTENÇÃO DE VENDA X", a API responderá algo semelhante ao que a API responde dentro do objeto "intencaoVenda" em uma pesquisa por ID.
Cancelamento de venda
Por último, iremos cancelar uma venda. Para isso, usaremos a API Venda/CancelarVenda, passando o valor da intenção de venda previamente coletado.
Troque acima a chave de integração pela sua chave.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
{
"intencaoVendaId":"2015371",
"terminalId":"1234",
"aguardarTefIniciarTransacao":true,
"senhaTecnica":"111111"
}
No body da requisição acima, lembre-se de trocar o ID da intenção de venda pelo ID recuperado, o ID do terminal pelo ID do terminal usado e a senha técnica pela senha técnica do usuário (a senha padrão é "314159").
Exemplo de cancelamento de venda
Após enviar um POST semelhante ao acima, a API responderá com semelhantemente ao que se encontra abaixo:
{
"data": "12/11/2024 12:21:16.3613",
"intencaoVenda": {
"id": 2015371,
"referencia": null,
"token": "822446",
"data": "12/11/2024 12:21:16.3613",
"hora": "12:21:16",
"quantidade": 0,
"valorOriginal": 1,
"valorOriginalFormat": "1,00",
"valorAcrescimo": 0,
"valorAcrescimoFormat": "0,00",
"valorDesconto": 0,
"valorDescontoFormat": "0,00",
"valorFinal": 1,
"valorFinalFormat": "1,00",
"gate2allToken": null,
"quantidadeParcelas": 1,
"urlPagamento": null,
"formaPagamento": {
"id": 21,
"nome": "TEF",
"modalidade": "Crédito",
"fluxoPagamento": {
"id": 21,
"nome": "TEF"
}
},
"intencaoVendaStatus": {
"id": 6,
"nome": "Em Cancelamento"
},
"cliente": null,
"produtos": [],
"pedido": null
}
}
Em seguida, uma tela do PayGo Windows semelhante à tela que apareceu durante a venda se apresentará, iniciando o cancelamento da venda.
Updated 9 days ago