Conectar a DHL Express: tarifas ao vivo, etiquetas e rastreio
Obtenha a API Key e o API Secret do seu app MyDHL API aprovado no DHL Developer Portal, cole-os junto com seu número de conta da DHL Express no Integration, teste e comece a cotar e enviar.
O conector da DHL Express obtém tarifas ao vivo, compra etiquetas e rastreia envios pela MyDHL API. Tarifas e envios são faturados na sua conta da DHL Express. É somente DHL Express: não é a DHL eCommerce, que usa outra API e outras credenciais.
Pré-requisitos#
- Uma conta da DHL Express e seu número de conta da DHL Express: está numa fatura da DHL ou no mydhl+, em My Profile.
- Acesso ao DHL Developer Portal (developer.dhl.com) com um app MyDHL API aprovado.
- Comece no sandbox se quiser praticar primeiro: preencha true no campo sandbox. O ambiente de teste tem um limite diário de chamadas.
Obter credenciais#
- Vá ao DHL Developer Portal (developer.dhl.com) → Apps → seu app MyDHL API aprovado.
- Na seção Credential, clique em Show key ao lado de API Key e copie. Essa API Key é o que você preencherá como API Username: não é o login do site mydhl+.
- Na mesma seção Credential, clique em Show key ao lado de API Secret e copie. Esse API Secret é o que você preencherá como API Password.
- Encontre seu número de conta da DHL Express numa fatura da DHL ou em mydhl+ → My Profile. Guarde-o junto com a Key e o Secret: você precisa dos três para preencher a conexão.
Preencher no Integration#
- Abra Integration → Marketplace → DHL Express → Nova conexão.
- API Username: cole a API Key da seção Credential do seu app MyDHL API. Apesar do nome do campo, aqui vai a API Key, não um nome de login do mydhl+.
- API Password: cole o API Secret da mesma seção Credential. Apesar do nome do campo, aqui vai o API Secret, não a sua senha do site mydhl+.
- DHL Express Account Number: preencha seu número de conta da DHL Express, de uma fatura da DHL ou de mydhl+ → My Profile. Tarifas e etiquetas são faturados nessa conta, então um número errado só aparece depois, na cotação ou na etiqueta.
- Use sandbox (opcional): preencha true para usar o ambiente de teste enquanto pratica; deixe em branco para produção.
Testar a conexão#
A MyDHL não tem endpoint de token, então o teste funciona de forma diferente de outras transportadoras: ele envia sua API Key e seu API Secret ao endpoint de rastreio e busca um número de envio que não existe. Se a DHL responder 404 — envio não encontrado — isso é uma boa notícia: significa que suas credenciais foram aceitas e que só falta aquele envio inventado. O teste aprova com esse 404. Um 401 ou 403 é a falha real: significa que as credenciais foram rejeitadas. O teste é somente leitura, não cria nenhum envio e não verifica seu número de conta: um número de conta errado pode passar no teste e só falhar depois, na cotação ou na etiqueta.
Mapping / escolher modelo#
A DHL Express não precisa de mapping de pedidos: trabalha com pacotes, não com pedidos. O que você configura aqui é o mapping de serviços da transportadora: nas configurações da conexão, relacione cada serviço da DHL Express que você realmente oferece ao nome de serviço que usa ao enviar, e deixe sem mapear os serviços que não oferece. A comparação de tarifas só cotizará os serviços mapeados, para que um pacote nunca seja cotado nem etiquetado num serviço que sua conta não envia.
Ativar#
Após ativar, a conexão fica disponível para comparar tarifas e comprar etiquetas ao enviar, com faturamento no número de conta da DHL Express da conexão. As atualizações de rastreio voltam automaticamente e são registradas no envio. Acompanhe os primeiros envios em Runs / Logs antes de deixá-lo sem supervisão, sobretudo a primeira cotação, porque o teste não verifica o número de conta.
Perguntas frequentes#
O teste menciona 404 ou envio não encontrado: falhou?
Não: para a DHL Express, esse 404 é o sinal de sucesso. O teste busca de propósito um número de envio que não existe. Receber uma resposta de não encontrado significa que a DHL aceitou sua API Key e seu API Secret e só rejeitou aquele envio inventado.
Considere o teste como aprovado e continue para o mapping e a ativação. Somente uma resposta 401 ou 403 significa que o teste realmente falhou.
O teste falha com 401 ou 403
A DHL rejeitou as credenciais. As causas habituais são que a API Key ou o API Secret foram copiados errado, que os dois foram trocados, ou que foi preenchida uma senha do site mydhl+ — ou credenciais da DHL eCommerce — em vez do API Secret da MyDHL.
Volte ao DHL Developer Portal → Apps → seu app MyDHL API aprovado → seção Credential, clique de novo em Show key e copie com cuidado: API Key em API Username e API Secret em API Password. Depois teste de novo.
O teste passa, mas as cotações ou etiquetas falham
O teste de conexão não verifica seu número de conta, então pode aprovar com um número de conta errado. O erro só aparece quando uma cotação ou etiqueta real tenta faturar naquela conta.
Confira o número de conta da DHL Express numa fatura da DHL ou em mydhl+ → My Profile, corrija-o na conexão e faça a cotação de novo.
Usei meu login do mydhl+ ou minhas credenciais da DHL eCommerce e não funciona
São três conjuntos de credenciais diferentes que não se substituem: o login do site mydhl+ é para o site, as credenciais da DHL eCommerce pertencem a outra API, e esta conexão só aceita a API Key e o API Secret de um app MyDHL API.
Use somente as credenciais da MyDHL API nesta conexão: DHL Developer Portal → Apps → seu app MyDHL API aprovado → seção Credential → Show key para a API Key e o API Secret. Guarde as credenciais da eCommerce para o conector da eCommerce.