API Same-Day Delivery

Integre conosco e disponibilize no seu site ou e-commerce entregas expressas no mesmo dia ou até na mesma hora.

Integrando com o motoboy.com você tera a disposição toda nossa infraestrutura de entregas e serviços de motoboy.

Disponibilizamos para nossos clientes uma API Restful com retorno no formato JSON.


Nosso objetivo é tornar a integração o mais simples possível, em apenas 2 passos você estará integrado a motoboy.com.

Dicas para aplicar a API no seu e-commerce ou estabelecimento

  • O endereço 1 ou endereço de COLETA normalmente é o seu estabelecimento, normalmente se mantem o mesmo em todas as chamadas a menos que você tenha mais de um local de coleta.
  • O endereço 2 ou endereço de ENTREGA normalmente é o endereço do seu cliente, onde o item será entregue, esse geralmente muda depedendo do cliente.
  • Você pode utilizar a chamada de orçamento da API para criar regras de atendimento especificas, a API irá lhe retornar distancia e duração e com estas informações você pode decidir se irá atender o cliente. Desta forma por exemplo você pode limitar o atendimento de cliente em no máximo 5km do seu restaurante.
  • Para delivery de restaurantes procure agendar o pedido baseado no tempo de preparo (regra própria dependendo do estabelecimento) descontando 5 minutos para a chegada do motoboy.

Testes

Disponibilizamos um usuário de testes para que você teste e entenda o funcionamento da integração, não há custos algum neste processo, recomendados sua utilização em um primeiro contato.
Ocasionamente os dados deste usuário são limpos.
Usuario teste-api@motoboy.com
Chave de API eJNQ6DPGKFr521zwshtNxntVembCJ2qu

Autenticação

Para isso é necessário que você já tenha se cadastrado conosco como empresa.

Caso ainda não tenha acesse: http://www.motoboy.com/empresa


Antes de tudo você precisa solicitar uma chave de acesso a API, isso pode ser feito na aba "API - Integração" do dashboard.

API same-day
Parametros de envio
username Email de cadastro
apiKey Sua chave de acesso. Para visualizar sua chave de acesso no dashboard ela estará visivel na aba "API - Integração"
Exemplo:

http://www.motoboy.com/apiV1/login?username=teste-api@motoboy.com&apiKey=eJNQ6DPGKFr521zwshtNxntVembCJ2qu

{"success":false,"msg":"Usuário ou chave de api invalidos."}
Retorno
success Retorna "true" quando o login for efetuado com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.

Passo 1 - Orçamento

No momento nossa API suporta apenas serviços simples de coleta e entrega.
Parametros de envio
cidade No momento suportamos as seguintes cidades:
  • sp/sao-paulo
  • sc/joinville
  • rj/rio-de-janeiro
  • mg/belo-horizonte
  • pr/curitiba
  • rs/porto-alegre
  • mt/cuiaba
  • portugal/lisboa
  • sc/florianopolis
  • df/brasilia
  • pe/recife
  • ma/sao-luis
  • go/goiania
  • es/vitoria
  • ba/salvador
  • ba/feira-de-santana
  • sp/santos
tipo_atendimento "CORPORATIVO" ou "SIMPLES".
  • "SIMPLES" : para pessoas e empresas que precisam do serviço avulso, com pagamento no ato, por um melhor preço.
  • "CORPORATIVO" : para empresas que precisam do serviço recorrente, com pagamento FATURADO(pagamento mensal por boleto) e organização por Centro de Custos.
endereco1_cep Apenas numeros, 8 digitos do CEP do local de coleta.
endereco2_cep Apenas numeros, 8 digitos do CEP do local de entrega.
Exemplo:

http://www.motoboy.com/apiV1/orcamento?cidade=sp/sao-paulo&tipo_atendimento=SIMPLES&endereco1_cep=89225570&endereco2_cep=89227070

{"success":true,"msg":"","valor":25.238,"distancia":4.619}
Retorno
success Retorna "true" quando a operação for efetuada com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.
valor Valor em reais, separador decimal "."
distancia Distancia em kilometros entre coleta e entrega com base na melhor rota, separador decimal "."
duracaoEstimadaMinutos Duração estimada em minutos, separador decimal "."
horaTermino Horário estimado de termino do serviço

Passo 2 - Confirmação

Parametros de envio
cidade No momento suportamos as seguintes cidades:
  • sp/sao-paulo
  • sc/joinville
  • rj/rio-de-janeiro
  • mg/belo-horizonte
  • pr/curitiba
  • rs/porto-alegre
  • mt/cuiaba
  • portugal/lisboa
  • sc/florianopolis
  • df/brasilia
  • pe/recife
  • ma/sao-luis
  • go/goiania
  • es/vitoria
  • ba/salvador
  • ba/feira-de-santana
  • sp/santos
tipo_atendimento "CORPORATIVO" ou "SIMPLES".
  • "SIMPLES" : para pessoas e empresas que precisam do serviço avulso, com pagamento no ato, por um melhor preço.
  • "CORPORATIVO" : para empresas que precisam do serviço recorrente, com pagamento FATURADO(pagamento mensal por boleto) e organização por Centro de Custos.
forma_pagamento "DINHEIRO" ou "FATURADO".
  • DINHEIRO: pagamento efetuado no momento do serviço.
  • FATURADO: pagamento via boleto, contabilização mensal, não é feita cobrança no momento do serviço.
momento_cobranca Informe este campo apenas quando "forma_pagamento" for igual a "DINHEIRO". Informe "COLETA" quando o pagamento deve ser efetuado no momento da coleta, e "ENTREGA" quando o motoboy deverá cobrar na entrega.
endereco1_cep Apenas numeros, 8 digitos do CEP do local de coleta.
endereco1_rua Rua do endereço de coleta.
endereco1_numero Rua do endereço de coleta.
endereco1_complemento Irformações adicionais sobre o endereço de coleta. Ex: Aptartamento 301, Nome da loja...
endereco1_nome Nome do responsável no endereço de coleta.
endereco1_telefone Telefone do responsável no endereço do endereço de coleta.
endereco1_comentario Instruções para o motoboy no endereço de coleta. Ex: Coletar pacote #204 do cliente João.
endereco2_cep Apenas numeros, 8 digitos do CEP do local de entrega.
endereco2_rua Rua do endereço de entrega.
endereco2_numero Rua do endereço de entrega.
endereco2_complemento Irformações adicionais sobre o endereço de entrega. Ex: Aptartamento 301, Nome da loja...
endereco2_nome Nome do responsável no endereço de entrega.
endereco2_telefone Telefone do responsável no endereço do endereço de entrega.
endereco2_comentario Instruções para o motoboy no endereço de entrega. Ex: Efetuar entrega e coletar assinatura.
Exemplo:

http://www.motoboy.com/apiV1/confirmarPedido?cidade=sp/sao-paulo&endereco1_cep=89225570&endereco1_rua=Luiza&endereco1_numero=100&endereco2_cep=89227070&endereco2_rua=Padre&endereco2_numero=200&forma_pagamento=DINHEIRO&momento_cobranca=COLETA&tipo_atendimento=SIMPLES

{"success":true,"msg":""}
Retorno
success Retorna "true" quando a operação for efetuada com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.
entrega Sempre que "success" retornar "true" este campo virá com o ID da entrega criada para que você faça o acompanhamento.

Acompanhamento da entrega

Parametros de envio
entrega ID da entrega que você deseja acompanhar.
Exemplo:

http://www.motoboy.com/apiV1/detalhesPedido?entrega=XXX

{"success":true,"msg":"","status":{"id":2,"descricao":"Motoboy Confirmado"},"motoboy":{"nome":"João da Silva","latitude":-26.27435523,"longitude":-48.82978327}}
Retorno
success Retorna "true" quando a operação for efetuada com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.
cancelado Pedido cancelado?
status Estado atual da entrega
motoboy Dados do motoboy que está efetuando o serviço.

Listar entregas

Parametros de envio
offset Utilizado para paginação. A cada consulta será retornado uma quantidade máxima de registros definida em 'limit' (10 por exemplo). Faça a primeira consulta com offset=0, se no retorno vier hasMore=true então você deverá fazer uma nova consulta incrementando o offset com a quantidade retornada em limit. Ex: Primeira consulta com offset=0 retornou hasMore=true e limit=10, para retornar o restante dos itens você deverá fazer uma nova consulta com ofsset=10.
Exemplo:

http://www.motoboy.com/apiV1/listarPedidos?offset=0

{"success":true,"msg":"","pedidos":[{"id":1227,"data":"2016-07-07T15:18:43Z","status":{"id":1,"descricao":"Contatando Motoboy"}},{"id":1153,"data":"2016-06-09T00:12:47Z","status":{"id":4,"descricao":"Serviço Finalizado"}}],"hasMore":false,"total":2,"limit":10}
Retorno
success Retorna "true" quando a operação for efetuada com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.
pedidos Lista de todos os pedidos do usuário
hasMore Existem outros itens na lista, você deve continuar fazendo as chamadas incrementando o offset.
total Total de pedidos do usuário
limit Limite de pedidos retornados por consulta

Modificações na entrega e cancelamento

Parametros de envio
entrega ID da entrega que você deseja modificar.
tipo Tipo de modificação.
Ex: "CANCELAR" para efetuar o cancelamento da entrega.
Só é possível efetuar o cancelamento de entregas que ainda não estiverem com motoboy alocado, nos outros casos é necessário entrar em contato com a nossa equipe de atendimento.
Exemplo:

http://www.motoboy.com/apiV1/alterarPedido?entrega=XXX&tipo=CANCELAR

{"success":true,"msg":"","pedidos":[{"id":1227,"data":"2016-07-07T15:18:43Z","status":{"id":1,"descricao":"Contatando Motoboy"}},{"id":1153,"data":"2016-06-09T00:12:47Z","status":{"id":4,"descricao":"Serviço Finalizado"}}],"hasMore":false,"total":2,"limit":10}
Retorno
success Retorna "true" quando a operação for efetuada com sucesso, senão "false"
msg Sempre que "success" retornar "false" este campo virá com os detalhes disto.