API do Delivety
Aqui no Delivety, nós estamos tentando manter as coisas o mais simples possível. Portanto, a API do Delivety também é.
Nessa guia, você encontrará informações de fácil compreensão sobre como utilizar a API do Delivety para começar a enviar os pedidos do seu site ou app já existente(s) para seu Web APP do Delivety.
Nós gostaríamos de ajudar você a começar a usar a API do Delivety o mais rápido possível, portanto, caso você tenha perguntas, estamos aqui para ajudar.
Introdução
A API do Delivety é um serviço web RESTful para desenvolvedores enviarem dados sobre pedidos de seu site ou APP já existente para o URL de webhook do Delivety.
URL de webhook do Delivety
Para interagir com a API do Delivety, você precisará se registrar para uma conta Delivety. Após ter criado uma conta conosco, abra a seção de Domínio no seu Painel de Administrador do Delivety, depois selecione o domínio ao qual você gostaria de integrar seu site ou APP (ou crie um novo domínio, caso você não possua um ainda). Depois, selecione "Receber pedidos do site já existente". A URL de webhook dedicada aparecerá. Agora é hora de fazer o seu site ou APP enviar os dados dos pedidos para essa URL de webhook.
Usando webhooks
Seu site ou APP precisa enviar um callback HTTPS para a URL de webhook do Delivety cada vez que um cliente fizer um pedido no seu site ou APP. Caso ele for recebido com sucesso, o Delivety responderá com 2xxHTTP e o pedido aparecerá imediatamente no Painel de Operador. Por gentileza, observe que existem exigências para que o callback HTTPS seja processado com sucesso...
Sempre Utilize HTTPS
Calls (chamadas) feitas por um HTTP simples vão falhar. Requests (solicitações) de API que não possuam todos os parâmetros mandatórios também vão falhar.
Throttling (Limitações)
Você não pode realizar mais de 10 requests por segundo através de todas as URLs de webhook da sua empresa. Se você exceder o limite de 10 requests por segundo, você receberá primeiro um erro 426. Falhar em reduzir a sua taxa de requests pode resultar em um banimento temporário
Segurança
Você é responsável pela utilização segura das URLs de webhook que fornecemos a você. Caso você comprometa uma, você pode gerar novamente uma nova para o domínio apropriado na seção de Domínio do seu Painel de Administrador do Delivety. Não esqueça que, a partir daquele momento, você precisará enviar a POST request para a nova URL de webhook que você criar.
Tipos e Formatos de Dados
Com algumas poucas exceções, números são números, e não strings. A API adere estritamente à representação mais natural dos dados inerentes, e "null" sempre retorna para propriedades opcionais cujos valores ainda não estiverem atribuídos.
Coordenadas geográficas são formatadas como [ longitude, latitude ], conforme o padrão GeoJSON.
Os "timestamps" são consumidos e produzidos no formato de data/hora "Era Unix", com precisão de milissegundos.
Números de celular sempre retornam em formato E.164; entretanto, eles podem também ser fornecidos em E.164 ou formato localizado que seja válido baseado nas configurações de país da sua empresa. Se você desejar fornecer números de outros países além do país de residência da sua empresa, você precisará usar apenas E.164. Nós recomendamos fortemente o uso de bibliotecas como libphonenumber para gerenciar a validação e formatação de números de telefone.
Como Enviar os Dados
POST Request
Envie os dados como request (solicitação) POST com um corpo que contenha os seguintes parâmetros:
Parâmetro | Descrição |
phone | Número de telefone do consumidor, são aceitos apenas símbolos numéricos. Serve como a id do consumidor. |
id | ID de Pedido de acordo com o sistema de identificação de pedidos do seu site ou APP. |
first_name | Primeiro nome do consumidor. Você pode incluir seu sobrenome aqui também (opcional). |
E-mail do cliente (opcional). | |
address | Endereço do cliente (opcional). |
comment | Anotação ou comentário do cliente (opcional). |
delivery_date | A data na qual o pedido precisa ser entregue. Esse é o parâmetro opcional. O pedido receberá a data de entrega HOJE caso o parâmetro esteja ausente. |
delivery_time | O horário no qual o pedido precisa ser entregue. Este é o parâmetro opcional. O pedido receberá o tempo de entrega ASAP (Assim Que Possível) caso o parâmetro esteja ausente. |
product | Produtos no pedido (array, veja abaixo) |
payment | Data de pagamento (array opcional, veja abaixo). O pedido receberá a condição UNPAID (sem pagamento) caso a array esteja ausente. |
promotion | Data da promoção (array opcional, veja abaixo). |
Array de Produto
A array de produto precisa conter os seguintes parâmetros:
Parâmetro | Descrição |
api_id | A Id do prato, de acordo com o sistema de identificação de pratos do seu site ou APP. Você precisa configurar as mesmas IDs de API que as IDs de produto para cada prato no seu Construtor de Menu do Delivety |
count | A quantidade de pratos de uma api_id específica |
price | O preço do prato de uma api_id específica |
Array de Pagamento
A array de pagamento precisa conter os seguintes parâmetros:
Parâmetro | Descrição |
type | O método de pagamento usado para esse pedido. O valor precisa conter: "1" se o pedido foi pago com dinheiro, ou "2" se o pedido foi pago com cartão, ou "3" se o pedido foi pago com cartão na entrega |
status | A condição do pagamento através de cartão de crédito para esse pedido. O valor precisa conter: "-1" se o pagamento foi reembolsado "0" se o pagamento foi cancelado "1" se o pagamento ainda não foi processado "2" se o pagamento foi processado com sucesso |
sum | A soma dos preços de todos os itens do pedido. Na maioria dos casos, esse é o valor total do pedido antes de deduzir quaisquer descontos e/ou taxas de processamento de pagamentos (receiver_commission). |
amount | A quantia total paga (ou a ser paga) pelo pedido. Na maioria dos casos, a quantia é igual à soma menos descontos e comissões de processadores de pagamentos (receiver_commission) |
public_key | O parâmetro opcional para pagamentos com cartão de crédito usado para identificar o número da conta para a qual processar o pagamento. Esse parâmetro é usado se você tiver mais de uma conta bancária e/ou usar diversos processadores de pagamento e preferir distingui-los no Delivety. |
receiver_commission | A comissão do processador de pagamentos, se houver alguma. |
Array de Promoção
A array de promoção precisa conter os seguintes parâmetros:
Parâmetro | Descrição |
discount | O parâmetro opcional que contém a quantidade total de descontos no pedido. |
discount_percent | O parâmetro opcional que contém a porcentagem de descontos no pedido. |
discount_code | O parâmetro opcional que contém o código de cupom alfanumérico aplicado ao pedido. |
involved_dishes | A array opcional que contém os pratos envolvidos na promoção. |
resulted_dishes | A array opcional que contém os pratos que são resultado da promoção. |
Array de Pratos Resultantes
A array resulted_dishes precisa conter os seguintes parâmetros opcionais:
Parâmetro | Descrição |
api_id | A id do prato que é resultante da promoção. Você não pode enviar esse prato na array de produto |
count | A quantidade de pratos de uma api_id específica |
modification | A modificação do preço do prato que é resultado da promoção |
POST Request
O exemplo de código PHP de um POST request mostrado abaixo ilustra o pedido, com os dois pratos pedidos (api_id = 139, api_id = 385) com um desconto de 10% e um recebido de graça, como resultado da redução de preço:
$url = 'https://delivety.com/hooks/catch/sdf34asdv1';
$incoming_order = [
"access_token" => "ACCESS_TOKEN_HERE",
"phone" => '123680000000',
"id" => 123456,
"first_name" => 'John Dowe',
"email" => '[email protected]',
"address" => '123, Sunset blvd',
"comment" => 'no sesame please',
"delvery_date" => '2021-12-31',
"delvery_time" => '18:45:00',
"products" => [
[
"api_id" => 139,
"count" => 1,
"price" => 15
],
[
"api_id" => 385,
"count" => 1,
"price" => 18
],
],
"payment" => [
"type" => 2,
"status" => 2,
"sum" => 33,
"amount" => 28.95,
"receiver_commision" => 1.05
],
"promotion" => [
"discount_percent" => 10,
"involved _dishes" => [
[
"api_id" => 139,
"count" => 1
],
[
"api_id" => 385,
"count" => 1
]
],
"resulted _dishes" => [
[
"api_id" => 598,
"count" => 1,
"modification" => -12
]
]
]
];
$data = sendRequest($url, 'post', $incoming_order);