Conectar o Uber Direct: cotar, despachar e rastrear entregas locais
Copie Client ID e Client Secret do seu app em direct.uber.com → Developer → API credentials, copie o Customer ID separado da página Developer, preencha o endereço de coleta como uma string JSON no Integration, teste a troca de token e comece a pedir entregas do Uber Direct.
O conector do Uber Direct pede entregas locais do Uber Direct a partir deste sistema: obtém uma cotação de entrega, cria uma entrega a partir dessa cotação, consulta o status e pode cancelar uma entrega. É apenas uma conexão de entrega de última milha: não traz pedidos do marketplace do Uber Eats para este sistema nem sincroniza menus ou catálogos de loja. Cotações e entregas correm com sua própria conta de cliente do Uber Direct e seu endereço de coleta.
Pré-requisitos#
- Uma conta do Uber Direct e acesso a direct.uber.com → Developer, onde estão seu app e suas credenciais de API.
- Você consegue abrir seu app em direct.uber.com → Developer → seu app → API credentials, onde o Client ID e o Client Secret são exibidos. O Client Secret é exibido só uma vez, então planeje copiá-lo para a conexão na hora e guardá-lo em local seguro.
- Você também tem o Customer ID separado, de direct.uber.com → Developer → Customer ID. É um valor diferente do Client ID: a conexão usa os dois, para coisas diferentes.
- Você conhece o endereço de coleta da sua loja ou armazém por partes (rua, cidade, estado, CEP e país), porque a conexão o recebe como uma única string JSON, não como campos separados.
Obter credenciais#
- Vá a direct.uber.com → Developer → seu app → API credentials.
- Copie o Client ID exibido nessa página de API credentials.
- Copie o Client Secret exibido na mesma página de API credentials. Ele é exibido só uma vez: copie agora, completo, e guarde em local seguro. A conexão troca esse par, Client ID mais Client Secret, por um token de acesso, com o escopo eats.deliveries.
- Separadamente, vá a direct.uber.com → Developer → Customer ID e copie o Customer ID. Não o confunda com o Client ID da página do app: o Customer ID nomeia sua conta de cliente do Uber Direct, e as solicitações de entrega são feitas sob ela; o próprio caminho da API o carrega: /v1/customers/{customer_id}/deliveries.
Preencher no Integration#
- Abra Integration → Marketplace → Uber Direct → Nova conexão.
- client_id, obrigatório, Client ID: cole o Client ID de direct.uber.com → Developer → seu app → API credentials.
- client_secret, obrigatório, Client Secret: cole completo o Client Secret da mesma página de API credentials. É um campo do tipo senha e é guardado como segredo. Lembre que ele foi exibido só uma vez: trabalhe a partir da cópia que você salvou, não de memória.
- customer_id, obrigatório, Customer ID: cole o Customer ID de direct.uber.com → Developer → Customer ID. Não é o Client ID: as entregas são pedidas sob esta conta de cliente.
- pickup_address, obrigatório, endereço de coleta (JSON): preencha o endereço de coleta como UMA string JSON, exatamente neste formato: {"street_address":["20 W 34th St"],"city":"New York","state":"NY","zip_code":"10001","country":"US"}, com os valores da sua própria loja ou armazém no lugar dos valores do exemplo. Note que street_address é um array entre colchetes e que todas as aspas devem ser aspas retas em inglês. Este endereço é obrigatório para pedir entregas; o teste de conexão não precisa dele.
- pickup_name, opcional, nome de coleta: o nome exibido para a coleta, por exemplo Merchant ou o nome da sua loja. pickup_phone_number, opcional, telefone de coleta: um número que alcança o ponto de coleta, por exemplo +15551234567.
Testar a conexão#
Clique em Testar a conexão. Este teste é a própria troca de token: a conexão envia seu client_id e seu client_secret ao serviço de acesso da Uber (tipo de concessão client_credentials, escopo eats.deliveries) e receber um token de acesso conta como aprovação. Trocar um token não tem efeitos colaterais: não cria nenhuma entrega nem muda nada, e por isso pode servir como teste. Se a resposta voltar sem um token de acesso, o teste falha com um resultado BAD_JSON: a troca não devolveu o que a conexão precisa, o que quase sempre significa que o Client ID ou o Client Secret não corresponde. O teste não usa seu pickup_address nem verifica se seu customer_id pode realmente pedir entregas, então um teste aprovado com um endereço errado ou um Customer ID errado é possível, e esses erros só aparecem depois, na cotação ou na criação da entrega. Se você executar o teste antes de salvar credenciais, o resultado é apenas uma verificação simulada: salve as credenciais reais e teste de novo para um resultado real.
Mapping / escolher modelo#
O Uber Direct não precisa de mapping de pedidos: trabalha com entregas, não com pedidos. O que você confirma aqui é o fluxo de entrega que cada solicitação segue: primeiro vem uma cotação, e depois uma entrega é criada a partir dessa cotação; criar uma entrega sempre carrega a cotação de onde ela saiu, então não há criação direta sem cotação. A coleta vem do JSON de pickup_address da conexão, e cada solicitação toma seu endereço de destino, contato e itens do envio deste sistema. Antes de ativar, execute uma cotação real e uma entrega de teste para seu próprio endereço, e compare o preço cotado, o endereço de coleta como interpretado do JSON e os dados de destino com o envio.
Ativar#
Após ativar, os envios deste sistema podem pedir entregas do Uber Direct: a conexão troca um token quando preciso, cota a entrega sob seu Customer ID, cria a entrega a partir da cotação aceita, mantém o status da entrega no envio e pode cancelar uma entrega que ainda não foi coletada. Acompanhe as primeiras entregas reais em Runs / Logs antes de deixar a conexão sem supervisão, sobretudo a primeira cotação, porque o teste não verifica o endereço de coleta nem o Customer ID.
O que esta conexão não faz: não traz pedidos do marketplace do Uber Eats para este sistema, não sincroniza menus nem catálogos de loja e não acerta pagamentos de entregadores nem o faturamento da Uber por você. Ela só cota, cria, rastreia e cancela entregas do Uber Direct para os envios que você passar por ela.
Perguntas frequentes#
O teste falha e nenhum token de acesso volta: BAD_JSON
A troca de token não devolveu um token de acesso, então a conexão não teve nada com que trabalhar e informou BAD_JSON. A causa habitual é que o Client ID ou o Client Secret não corresponde: um foi copiado errado, o segredo foi cortado ou foram usadas credenciais de outro app.
Volte a direct.uber.com → Developer → seu app → API credentials e copie de novo o par dessa mesma página: Client ID em client_id e Client Secret, completo e do mesmo app, em client_secret. Depois teste de novo.
O teste passa, mas as cotações ou entregas falham logo em seguida
O teste só demonstra a troca de token com client_id e client_secret. Ele não usa seu pickup_address nem verifica seu customer_id, então um Customer ID errado ou um endereço de coleta defeituoso passa no teste e só falha quando uma cotação ou entrega real tenta rodar sob aquela conta de cliente, a partir daquele endereço de coleta.
Confira os dois valores que o teste não cobre: customer_id contra direct.uber.com → Developer → Customer ID, e pickup_address contra o formato JSON da etapa de preencher, caractere por caractere. Corrija o que estiver errado, salve e cote de novo.
Coloquei o Customer ID onde vai o Client ID, ou o contrário
Os dois ID se parecem, mas fazem trabalhos diferentes e vêm de páginas diferentes. O Client ID pertence ao seu app e é usado, com o Client Secret, para trocar um token. O Customer ID nomeia sua conta de cliente do Uber Direct e vai no próprio caminho da entrega: /v1/customers/{customer_id}/deliveries. Trocados, a troca de token ou a solicitação de entrega falha mesmo com os dois campos preenchidos.
Devolva cada ID ao seu próprio campo, da sua própria página: Client ID de direct.uber.com → Developer → seu app → API credentials, em client_id, e Customer ID de direct.uber.com → Developer → Customer ID, em customer_id. Salve e teste de novo.
As entregas falham por causa do endereço de coleta, embora o teste tenha passado
É o comportamento esperado com um endereço defeituoso: o teste de conexão nunca olha o pickup_address, então não consegue detectar um problema de endereço. O endereço só é usado quando uma entrega é pedida de verdade, e é aí que uma string JSON malformada (street_address digitado como texto simples em vez de um array, ou aspas curvas coladas de um documento) para a solicitação.
Reescreva o pickup_address à mão no formato exato da etapa de preencher: {"street_address":["20 W 34th St"],"city":"New York","state":"NY","zip_code":"10001","country":"US"}, com seus próprios valores: street_address como um array entre colchetes, aspas retas em inglês em todo o texto e nenhum texto extra antes ou depois do JSON. Salve e peça a entrega de novo.
Perdi o Client Secret: ele não é mais exibido
É assim que a página de API credentials funciona: o Client Secret é exibido só uma vez, no momento em que é criado. Passado esse momento, a página não mostra mais o valor, então um segredo que você não salvou não pode ser lido de novo na página.
Crie um Client Secret novo para o mesmo app em direct.uber.com → Developer → seu app → API credentials, copie-o de imediato desta vez, cole-o em client_secret na conexão e guarde uma cópia em local seguro. Depois teste de novo: a conexão trocará um token com o segredo novo.
Criar uma entrega pede primeiro uma cotação
É o fluxo normal do Uber Direct, não um erro nos seus valores: uma entrega sempre é criada a partir de uma cotação. A cotação fixa primeiro os detalhes e o preço da entrega, e a etapa de criação carrega aquela cotação consigo: não há um caminho separado de criação direta que pule a cotação.
Siga o fluxo em ordem: peça primeiro uma cotação para o envio, confira o preço e os detalhes cotados, aceite-a e depois crie a entrega a partir daquela cotação. Se uma cotação já venceu, peça uma cotação nova e crie a partir da nova em vez de reutilizar a antiga.