Pedidos

APIs relacionadas à geração de Pedidos na plataforma, que podem ser pagos posteriormente.

🚧

Esta documentação está desatualizada.

Para informações sempre atualizadas, acesse https://paygodev.readme.io/docs.

🚧

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:

StatusDescrição (como retornado pela API)
5Aberto
6AguardandoPagamento
10Pago
15Cancelado

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.

PropriedadeTipoTamanhoObrigatórioDescrição
formaPagamento.idInt2NãoDefine o método de pagamento
21 = TEF Crédito
22 = TEF Débito
23 = TEF Voucher
24 = TEF Outros (Nada
é enviado e o operador
do caixa informará de
acordo com as opções
que o adquirente
disponibilizar)
51 = Cartão de crédito
digitado (URL do
gateways de
pagamento é
devolvdido para
redirecionar o usuário)
quantidadeMaximaParcelasInt2NãoDefine a quantidade
máxima de parcelas
que o comprador
poderá selecionar
(min. 2 - máx. 12)
adquirentePadraoString-NãoAdquirente que
processará a transação.
REDE, CIELO, GETNET,
STONE, SAFRA,
GLOBAL, BIN
tipoFinanciamentoInt1NãoTipo de Financiamento
1 = Rotativo/à vista
2 = Parcelado Emissor
4 = Parcelado Lojista
8 = Pré datado
quantidadeFixaParcelasInt2NãoDefine a quantidade de
parcelas. Se for enviado,
a instrução da
"QuantidadeMaxima
Parcelas" não será acatada.
HEADERS
Content-Typeapplication/json
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' \
--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 protected]"
        },
        "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' \
--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-Typeapplication/json
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'

POST Pedido/GetByFiltros

📘

{{Url}}/Pedido/GetByFiltros?key={{Key}}

Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.

HEADERS
Content-Typeapplication/json
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' \
--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-Typeapplication/json
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'