Olá Desenvolvedor(a)!
Bem-vindo a porta de entrada para começar a centralizar a gestão de seus ‘pedidos’ em diferentes canais de vendas.
Este é um guia de primeiros passos, para aprofundamento nos endpoints específicos da API, consulte a nossa documentação técnica.
Sumário
2.1 Token de acesso (AccessToken)
2.2 Token de renovação (RefreshToken)
1. Ambientes
Atualmente a nossa API conta com dois ambientes distintos para serem utilizados, sendo eles produção e sandbox respectivamente sendo ambientes para uso em produção, como o próprio nome já diz, e um ambiente seguro para testes.
O acesso a estes ambientes se dão através das URL's abaixo:
Sandbox: https://api-sandbox.plug4foods.com.br/v1
Produção: https://api.plug4foods.com.br/v1
2. Autenticação da API
Para se autenticar na API e começar a integrar suas lojas e recebimento de pedidos nos canais de venda é necessário acessar nosso painel gerenciador para você poder ver as lojas que você possui cadastradas em nossa aplicação e gerar os tokens de acesso para ela. Sim, são dois tokens.
Para gerar os tokens para loja, acesse a opção "Lojas" no menu lateral, localize a loja desejada para integrar, e em seguida visualize suas informações (clicar sobre a linha da loja desejada ou sobre o botão com ícone de olho).
No final da página será possível ver uma seção chamada "Token da Loja", que conta com um campo e dois botões, sendo respectivamente um botão para "geração de token" (1) e outro para "copiar"(2), e o campo anteriormente vazio será preenchido com os tokens para utilizar na integração.
Assim sendo, gere os tokens clicando no botão "Gerar Tokens", em seguida copie o conteúdo no campo, seja pelo botão ou manualmente selecionando e copiando. Em seguida, note serem dois tokens:
O accessToken e o refreshToken.
{
"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
2.1 Token de acesso (AccessToken)
Este é o token que deverá ser enviado em todas as requisições para nossa API.
Você deverá passar esse token através do header "Authorization", conforme abaixo:
Authorization: Bearer <token>
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Este token tem validade de 24 horas, então será necessário renovar ele periodicamente, como sugestão a cada 23 horas. Para renovação deste token é aconselhável possuir o seu token de atualização, denominado refreshToken.
2.2 Token de renovação (RefreshToken)
Este é nosso token de atualização, você deverá armazená-lo seguramente em seu sistema/banco de dados, pois com ele você poderá criar uma rotina para atualização do seu token de acesso à API, caso contrário será necessário fazer a geração manualmente via painel do Plug4Market.
Este token é gerado sempre com um token de acesso, é único por accessToken, ou seja, a cada renovação de accessToken haverá um novo refreshToken.
A renovação do accessToken se dá através da rota POST /auth/refresh, onde no body deverá ser enviado o refreshToken.
Para esta rota não há necessidade de informar o header Authorization.
URL: POST https://api-sandbox.plug4foods.com.br/v1/auth/refresh
{
"refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
O retorno desta requisição será novamente um par de tokens, accessToken e refreshToken. Armazene o par e utilize nas suas próximas requisições e renovação.
3. Restaurante
Os restaurantes são manipulados pela Tecnospeed, estando somente na documentação interna.
3.1 Restaurantes disponíveis
- IFood
|
4. Pedidos
O JSON de retorno pode ser encontrado aqui - link do swagger
4.1 Listar pedidos
Retornando todos os pedidos
URL: GET https://api-sandbox.plug4foods.com.br/v1/orders
4.2 Consultar pedido
Retorna as informações de um pedido específico, identificando por meio do orderID. Antes de avançar com o pedido (confirmando ou cancelando) é necessário obter todos os detalhes do pedido, assim a loja pode verificar se conseguirá executar o pedido.
URL: GET https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}
4.3 Confirmar pedido
Após consultar os detalhes do pedido o usuário pode escolher confirmar o pedido.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}
4.4 Iniciar pedido
Assim que confirmado o pedido, você deve informar ao usuário que o pedido está sendo preparado.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/start
4.5 Pedido pode ser retirado
Esse rota informa ao usuário que o pedido foi preparado e está pronto para ser retirado. Esse endpoint deve ser utilizado somente para pedidos retirados no local.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/pickup
4.6 Pedido saiu para entrega
Essa rota informa ao usuário que o pedido, já foi liberado pela loja e saiu para entrega.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/dispatch
4.7 Solicitar cancelamento
Por meio dessa rota a loja pode solicitar o cancelamento de um pedido, esse cancelamento pode ser aceito ou rejeitado pelo usuário final -
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/request-cancellation
4.8 Aceitar cancelamento
Por meio dessa rota a loja pode aceitar o cancelamento de um pedido solicitado pelo usuário final.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/approve-cancellation
4.9 Negar cancelamento
A loja pode rejeitar o cancelamento de um pedido solicitado pelo usuário final.
URL: POST https://api-sandbox.plug4foods.com.br/v1/orders/{orderID}/deny-cancellation
5. Webhooks
O(s) Webhook(s) podem ser acessados por meio do menu lateral na interface.
5.1 Criar webhook
Disponibilizamos os seguintes métodos - POST, PUT e PATCH.
O campo Headers utiliza o formato JSON e deve ser preenchido com os dados necessários para envio do webhook, como por exemplo authorization.
A interface abaixo pode ser acessada pelo botão "Novo".
5.2 Listar webhook
Assim que o painel de webhooks for acessado, será listado os webhooks disponíveis, como na imagem abaixo:
5.3 Alterar webhook
Após acessar o painel de webhooks, podemos alterar as informações de um webhook já cadastrado clicando no botão editar, representado na interface pelo ícone:
5.4 Excluir webhook
Após acessar o painel de webhooks, podemos excluir um webhook já cadastrado clicando no botão excluir, representado na interface pelo ícone:
Obs: Ao excluir um webhook automaticamente o mesmo é desvinculado das lojas aos quais está vinculado.
5.5 Testar webhook
Por meio da interface "Detalhes do Webhook" que pode ser acessada clicando sobre o webhook, podemos testar se o endpoint cadastrado está recebendo a mensagem do webhook corretamente.
Feito com amor pela Comunicação
Comentários
0 comentário
Por favor, entre para comentar.