A Foody Delivery disponibiliza uma API no padrão Open Delivery que permite a sistemas terceiros a manipulação eficiente e sistemática de pedidos na plataforma.

Os endpoints disponibilizados são os da categoria LOGISTICS SERVICE, como mostrado na figura abaixo:

Importante: Esta documentação aborda algumas especificidades das regras de negócio da Foody Delivery e também a geração de sua credencial. Para obter mais informações sobre como realizar as requisições, consulte a documentação do Open Delivery (Logística).

Criando sua credencial Open Delivery

Em Menu ➡ Minha conta ➡ APIs e Hooks você deverá criar uma credencial do tipo Open Delivery clicando em Criar credencial. Para isso, basta escolher um nome e no menu de seleção Tipo, escolha Open Delivery.

Após criado a credencial Open Delivery, você será direcionado para a página onde haverão todas as credenciais criadas, nesta página você irá visualizar o seu clientId, clientSecret e a baseUrl. Para copiar suas credenciais, basta utilizar o menu kebab (Ações).

Token de acesso (access_token)

Agora com o cliendId, clientSecret e a baseUrl, você poderá obter o seu token de acesso (access_token) utilizando o endpoint de autenticação {baseUrl}/oauth/token.

Payload Response:

{    “access_token”: “WV+ui7vWzwbtj+/CV0F6sftYf3cXf…==”,    “token_type”: “bearer”,    “expires_in”: 1703271283598}

O tempo de validade do access_token é de 6 horas. Recomendamos que você utilize o access_token durante todo o seu período de validade, renovando-o apenas quando estiver próximo do seu vencimento.

Regras de negócio e requisições

Algumas requisições via Open Delivery API precisam respeitar as regras de negócio aplicadas em nosso sistema, portanto, abaixo detalharemos as requisições juntamente com seus respectivos endpoints e as ações que de fato serão executadas na Foody Delivery.

• Inform order pickup ({baseUrl}/v1/logistics/orderPicked/{orderId})
  • Este endpoint é utilizado para marcar um pedido como coletado, porém, para que de fato um pedido inserido via Open Delivery API seja marcado como coletado na Foody Delivery, este pedido deve estar no status [Aceito]. Caso seja feita esta requisição e o pedido não tenha ainda sido de fato aceito pelo entregador, será retornado http 200, mas será ignorado a ação de [Coleta] do pedido na Foody.

• Finish Delivery / Cancel delivery ({baseUrl}/v1/logistics/finishDelivery/{orderId} / {baseUrl}/v1/logistics/cancel/{orderId}
  • Em ambos os endpoints será considerado a data/hora da requisição da ação. Exemplo: Se for requisitada a finalização de um pedido, a data e hora de finalização daquele pedido será a data/hora do momento da requisição.

• Delivery Availability and Pricing ({baseUrl}/v1/logistics/availability)
  • Caso esta requisição seja para um plano Foody Delivery (Frota própria), pickupAddress será sempre o endereço da empresa registrado no sistema (Menu ➡ Minha conta ➡ Dados da empresa).
  • No caso de um plano (Empresa de Entregas), utilizaremos para efetuar o cálculo da taxa de entrega tanto o pickupAddress, quanto o deliveryAddress.
  • Para os planos (Empresa de Entregas e Central de Entregas), ao enviar o parâmetro “returnToMerchant”: true, a taxa de retorno será somada a taxa de entrega e retornado no parâmetro orderDeliveryFee.value.

Webhooks

Webhook é uma forma de integração entre dois sistemas onde um sistema notifica o outro

quando um evento acontece.

Para configurar webhook Open Delivery na Foody Delivery, basta acessar Menu ➡ Minha conta ➡ APIs e Hooks ➡ Criar gatilho. 

• IMPORTANTE: Só será possível a criação de um webhook para uma credencial do tipo Open Deliveryjá existente.
  • Webhook não tem lógica ou inteligência para tratar erros retornados pelo seu endpoint. A missão do hook é entregar o evento para o seu endpoint, então se seu endpoint foi chamado com sucesso e você recebeu o evento, você deve retornar http status como 200 pois você recebeu o evento.

• Recomendamos que seu endpoint sempre retorne http-status 200 para a chamada do hook, qualquer status diferente de 200 será considerado um erro na chamada do hook.
• AVISO: Se seu endpoint retornar consecutivamente mais de 10 erros, o webhook será automaticamente desativado, sendo necessário ativação manual através do login/senha (Foody Delivery).

Se você precisa de uma ferramenta de apoio para desenvolver sua API (URL invocada pelos hooks) localmente e ainda receber as chamadas normalmente, nós recomendamos que você use a ferramenta https://webhook.site/.

Ao fornecer a URL do seu endpoint, assegure-se de que seja um endpoint válido para receber hooks. Caso contrário, não será possível salvar as configurações do gatilho.

Nota: Um payload de teste será enviado para o endpoint especificado no campo “URL”.