Pedidos
APIs relacionadas à geração de Pedidos na plataforma, que podem ser pagos posteriormente.
Antes de usar as APIs...
Certifique-se de ter verificado as secções de APIs e Chave de Integração, além de ter lido as nossas Informações preliminares.
Sobre Pedidos
Pedidos são conjuntos de Produtos (ou uma soma de valor) a ser pago posteriormente. Pode-se pensar em Pedidos como um análogo ao "carrinho de compras" em um site de vendas online. Pedidos são comumente usados quando se deseja salvar os dados para uma venda que será realizada posteriormente, em algum momento do futuro.
Um exemplo de uso de Pedidos seria a situação a seguir:
"Um lojista deseja salvar uma venda de R$10,00 que poderá ser paga no crédito ou no débito para mais tarde, já que o cliente (por qualquer motivo) só irá pagar mais tarde. O lojista então gera um Pedido com um produto genérico que solicita valor de 10 reais e com as formas de pagamento 'crédito' e 'débito'.
Após várias horas, o cliente chega e deseja pagar a compra. O lojista então realiza uma venda com o Pedido gerado (passando o ID do Pedido na venda), gerando uma intenção de venda com as informações do Pedido. A intenção de venda é paga (finalizando o Pedido) e a transação é concluída."
Características do Pedido:
-
Pedidos são uma entidade acima de transações. Um mesmo pedido pode conter N intenções de vendas (ou até nenhuma).
-
Um pedido só é concluído após seu conjunto de transações com status "Pago" somarem o valor total do pedido.
-
Utilizar Pedido é o ideal para pagamentos remotos ou delivery. Uma vez cadastrado o Pedido, é possível realizar diversas tentativas de pagamento até sua conclusão. Diferente da intenção de venda, que uma vez negada, por exemplo, ela é finalizada.
Pedidos possuem status e esses status são informados de acordo com a tabela abaixo:
| Status | Descrição (como retornado pela API) |
|---|---|
| 5 | Aberto |
| 6 | AguardandoPagamento |
| 10 | Pago |
| 15 | Cancelado |
POST Pedido/Insert
{{Url}}/Pedido/Insert/?key={{Key}}Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
API para cadastrar Pedidos no ControlPay.
É possível estabelecer a forma de pagamento do pedido. Por exemplo, é possível configurar um pedido para somente aceitar ser pago com cartão de crédito em duas parcelas no tipo de financiamento parcelado lojista e será processado por uma determinada adquirente. Este fluxo evita erros de digitação e agiliza o processo durante o recebimento, pois dispensará digitação de alguns dados.
Um pedido pode ser gerado com uma ou mais formas de pagamento, que, na hora do pagamento, estarão disponíveis para o cliente. Exemplo: se um pedido for gerado com crédito e débito, na hora do pagamento, o cliente poderá escolher pagar gerando uma intenção de venda com crédito ou débito.
| Propriedade | Tipo | Tamanho | Obrigatório | Descrição |
|---|---|---|---|---|
formaPagamento.id |
Int |
2 |
Não |
Define o método de pagamento |
quantidadeMaximaParcelas |
Int |
2 |
Não |
Define a quantidade |
adquirentePadrao |
String |
Não |
Adquirente que |
|
tipoFinanciamento |
Int |
1 |
Não |
Tipo de Financiamento |
quantidadeFixaParcelas |
Int |
2 |
Não |
Define a quantidade de |
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
| PARAMS | |
|---|---|
| key | {Key} |
{
"pessoaVendedorId": "12",
"referencia": "REF 010",
"valorTotalPedido": 13.00,
"urlRetorno": null,
"produtosPedido": [
{
"id": "1229",
"valor": 13.00,
"quantidade": "1"
}
],
"pedidoFormasPagamento": [
{
"formaPagamento": {
"Id": 21
},
"quantidadeMaximaParcelas": 1,
"adquirentePadrao": "REDE",
"tipoFinanciamento": 1,
"quantidadeFixaParcelas": 3
}
]
}Exemplo: Pedido/Insert
curl --location --request POST 'sandbox.controlpay.com.br/webapi/Pedido/Insert/?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw '{
"pessoaVendedorId": "11559",
"terminalFisicoId": 186,
"referencia": "REF 010",
"ValorTotalPedido": "13.00",
"urlRetorno": null,
"produtosPedido": [
{
"Id": "7169",
"Nome": "Produto genérico",
"Valor": 1.11,
"Quantidade": 1
}
],
"pedidoFormasPagamento": [
{
"FormaPagamento": {
"Id":21
},
"QuantidadeMaximaParcelas": 1,
"AdquirentePadrao": "REDE",
"TipoFinanciamento": 1,
"QuantidadeFixaParcelas": 3
}
]
}'{
"data": "19/04/2021 16:04:36.1466",
"pedido": {
"id": 2054,
"referencia": "REF 010",
"obs": null,
"data": "19/04/2021 16:04:35.9747",
"hora": "16:04:35",
"valor": 1.11,
"valorFormat": "1,11",
"valorAberto": 1.11,
"valorAbertoFormat": "1,11",
"valorOriginalPago": 0.0,
"valorOriginalPagoFormat": "0,00",
"valorOriginalEmPagamento": 0.0,
"valorOriginalEmPagamentoFormat": "0,00",
"tipo": "Interno",
"quantidade": 1,
"quantidadeTransacoes": 0,
"pedidoStatus": {
"id": 5,
"nome": "Aberto"
},
"pessoa": {
"id": 11559,
"nomeRazaoSocial": "Pessoa Genérica",
"sobrenomeNomeFantasia": "Pessoa Genérica",
"cpfCnpjFormat": "596.206.800-90",
"email": "email@email.com.br"
},
"produtos": [
{
"itemProdutoId": 401456,
"id": 7169,
"nome": "Produto genérico",
"descricao": "Produto genérico",
"nomeExibe": "Produto ge",
"quantidade": 1,
"valor": 1.11,
"valorFormat": "1,11",
"fotoThumbnail": ""
}
]
}
}Venda/Vender com Pedidos
É possível realizar vendas com Pedidos. Os pedidos são gerados, com os Produtos e Formas de Pagamento desejados e ficam armazenados no sistema até que seja realizada uma venda com base neles. O pedido se manterá aberto até que seja pago (ou cancelado).
A venda deverá ser feita do mesmo modo que uma venda normal, contudo informando o ID do Pedido no body da requisição. Abaixo, temos como o body de uma requisição do pedido acima ficaria:
curl --location --request POST 'sandbox.controlpay.com.br/webapi/Pedido/Insert/?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw '{
"formaPagamentoId": 21,
"pedidoId": 2054,
"terminalId": "81",
"valorTotalVendido": "1,11",
"observacao": "observacao blablabla",
"aguardarTefIniciarTransacao": false,
"parcelamentoAdmin" :true,
"quantidadeParcelas" : 1
}'Pagamentos também podem ser realizados parcialmente, visto que o pedido só é fechado quando seu valor total é pago.
GET Pedido/GetById
{{Url}}/Pedido/GetById?key={{Key}}&pedidoId={{PedidoId}}Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
PedidoId: ID do pedido desejado.
API para consultar um Pedido específico.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
| PARAMS | |
|---|---|
| key | {Key} |
| pedidoId | {PedidoId} |
curl --location --request GET 'sandbox.controlpay.com.br/webapi/Pedido/GetById?key={{Key}}&pedidoId={{PedidoId}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \POST Pedido/GetByFiltros
{{Url}}/Pedido/GetByFiltros?key={{Key}}Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
| PARAMS | |
|---|---|
| key | {Key} |
{
"pessoaIds": "12"
}Exemplo: Pedido/GetByFiltros
curl --location --request POST 'sandbox.controlpay.com.br/webapi/Pedido/GetByFiltros?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw ' {
"pessoaIds": "12"
}
'GET Pedido/Cancelar
{{Url}}/Pedido/Cancelar?key={{Key}}&pedidoId={{PedidoId}}Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
PedidoId: ID do pedido desejado.
API para cancelar um Pedido.
| HEADERS | |
|---|---|
| Content-Type | application/json |
| User-Agent | NomeDaAutomacao/1.0 |
| PARAMS | |
|---|---|
| key | {Key} |
| pedidoId | {PedidoId} |
Exemplo: Pedido/Cancelar
curl --location --request GET 'sandbox.controlpay.com.br/webapi/Pedido/Cancelar?key={{Key}}&pedidoId=1112' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \Updated 2 months ago