Pedidos

🚧
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 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)
quantidadeMaximaParcelas	Int	2	Não	Define a quantidade máxima de parcelas que o comprador poderá selecionar (min. 2 - máx. 12)
adquirentePadrao	String	-	Não	Adquirente que processará a transação. REDE, CIELO, GETNET, STONE, SAFRA, GLOBAL, BIN
tipoFinanciamento	Int	1	Não	Tipo de Financiamento 1 = Rotativo/à vista 2 = Parcelado Emissor 4 = Parcelado Lojista 8 = Pré datado
quantidadeFixaParcelas	Int	2	Não	Define a quantidade de parcelas. Se for enviado, a instrução da "QuantidadeMaxima Parcelas" não será acatada.

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 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' \
--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' \

Pedidos

🚧
Antes de usar as APIs...

Sobre Pedidos

POST Pedido/Insert

📘
{{Url}}/Pedido/Insert/?key={{Key}}

Venda/Vender com Pedidos

GET Pedido/GetById

📘
{{Url}}/Pedido/GetById?key={{Key}}&pedidoId={{PedidoId}}

POST Pedido/GetByFiltros

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

GET Pedido/Cancelar

📘
{{Url}}/Pedido/Cancelar?key={{Key}}&pedidoId={{PedidoId}}

🚧Antes de usar as APIs...

Sobre Pedidos

POST Pedido/Insert

📘{{Url}}/Pedido/Insert/?key={{Key}}

Venda/Vender com Pedidos

GET Pedido/GetById

📘{{Url}}/Pedido/GetById?key={{Key}}&pedidoId={{PedidoId}}

POST Pedido/GetByFiltros

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

GET Pedido/Cancelar

📘{{Url}}/Pedido/Cancelar?key={{Key}}&pedidoId={{PedidoId}}

🚧
Antes de usar as APIs...

📘
{{Url}}/Pedido/Insert/?key={{Key}}

📘
{{Url}}/Pedido/GetById?key={{Key}}&pedidoId={{PedidoId}}

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

📘
{{Url}}/Pedido/Cancelar?key={{Key}}&pedidoId={{PedidoId}}