Esta FAQ é apresentada em Português tendo em conta que a maior parte dos clientes deste plugin são de Portugal.
Suporte
1) Como solicitar suporte técnico?
Se a razão pela qual necessita suporte técnico não está mencionada nesta página, clique no link de suporte junto à chave de licenciamento, no ecrã de definições do plugin, e preencha o ticket.
Desde a introdução da nova API REST, o suporte técnico deixou de abranger a antiga API SOAP, pelo que se ainda a está a utilizar, deve solicitar as novas credenciais à DPD e reconfigurar o plugin.
2) Onde posso submeter vulnerabilidades de segurança encontradas neste plugin?
Pode reportar erros de segurança descobertos no código deste plugin através do Patchstack Vulnerability Disclosure Program.
A equipa do Patchstack vai ajudar na verificação, emissão de CVE e tratar de nos notificar.
Licenciamento
1) Como transferir a licença de domínio?
Pedir na sua área de cliente, junto à encomenda original, a mudança de domínio
Depois de receber a nossa resposta de que a licença está libertada, deve ir à configuração do plugin no website antigo, remover a chave e gravar. Depois ir à configuração do plugin no site novo, inserir a mesma chave e gravar. Se o website foi transferido já com a chave na base de dados, deve remover a chave, gravar, inserir de novo e gravar de novo.
Funcionamento geral
1) Guia de configuração inicial (em desenvolvimento)
Instale o plugin e vá a WooCommerce > Configurações > Envio > DPD Portugal. Insira a chave de licenciamento fornecida para o activar.
Defina o modo de API para “Nova (API REST)” e insira as credenciais do webservice de guias de expedição. Se ainda não tem estes dados, ou tem apenas para a API SOAP antiga, deve solicitar as mesmas à DPD.
Opcionalmente defina as credenciais do webservice de pedido de recolhas. Só deve fazer esta configuração caso necessite de chamar a DPD para fazer recolhas cada dia que tenha encomendas para enviar. Caso tenha contratada a recolha diária, não necessita configurar estes dados.
Em “Contas de expedição” deve agora configurar os números de conta dos vários serviços que tem com a DPD. São os mesmos números de conta que usa no site ou aplicação da DPD.
Caso ainda não tenha credenciais nem contas de expedição, e estiver ainda em fase de desenvolvimento, pode usar o modo de teste. Para isso terá de passar o WP_DEBUG a true no wp-config.php e no ecrã de configurações do plugin terá uma opção para activar este modo de teste.
Agora tem duas possibilidades de definir que contas, configuradas no passo anterior, devem ser seleccionadas por omissão quando for emitir uma guia, sendo que aconselhamos a utilização de apenas uma delas:
- Contas por omissão por destino: As contas por omissão são definidas de acordo com o destino geográfico da encomenda;
- Regras por método de envio: As contas por omissão são definidas conforme o método de envio escolhido no momento da finalização da encomenda;
Deve depois preencher os dados do expedidor (a sua empresa) e da pessoa de contacto no expedidor. Podem repetir dados (por exemplo telefone fixo igual o móvel e não existirem ambos) e aconselhamos que todos os dados estejam preenchidos (excepto o fax que não tem qualquer utilidade). Os detalhes do expedidor é a morada de origem que será transmitida para a guia.
Nas opções das guias de expedição pode definir o tipo de papel (Normal para impressoras normais ou Etiqueta térmica se tem a impressora para etiquetas 10×15 fornecida pela DPD), o email para onde as guias devem ser enviadas em PDF (normalmente o email da área de logística que faz o embalamento), se o número de tracking deve ser adicionados aos emails seguintes enviados pelo WooCommerce ao cliente, e se o serviço Predict deve ser activado por omissão em todas as expedições.
Nas opções das guias de devolução, se tiver necessidade de aceitar devoluções dos clientes via DPD, de também configurar as opções das guias, sendo que neste caso é aconselhável que a guia seja em papel normal se for enviada para o email do cliente para ser ele a imprimir.
Para emitir a guia de cada encomenda, deve aceder à edição da mesma em WooCommerce > Encomendas e fazer a emissão na caixa “DPD – Guias de expedição de devolução”. Os dados de morada do cliente são obtidos da morada de envio e se houver campos que ultrapassem o limite de caracteres autorizado pela API da DPD, ficarão marcados a vermelho para correcção manual antes da emissão da guia. O peso é automaticamente obtido dos produtos da encomenda, e deve ter em atenção ao número de objectos de cada expedição, sendo o valor 1 por omissão.
2) Porque é que não posso emitir guias de várias encomendas de uma única vez (em bulk)?
Existem várias razões para isso não ser possível, mas as duas principais são:
- Performance: Não temos como garantir que o seu servidor aguenta fazer tantas chamadas HTTP ao webservice da DPD de uma única vez sem dar timeout.
- Confirmação de dados: muitas vezes o cliente da sua loja insere mais caracteres do que aqueles que são possíveis de colocar numa guia, ou coloca dados incorrectos, pelo que é importante uma confirmação visual dos dados antes da emissão da mesma.
3) É um método de envio do WooCommerce?
Não. Terá de utilizar os métodos de envio nativos do WooCommerce, ou de plugins de terceiros, para calcular os custos de envio. Este plugin permite apenas a emissão das guias de expedição no sistema da DPD Portugal. Não faz sentido ser este plugin a definir custos de envio porque cada loja tem assim a liberdade de fazer os cálculos como quiser.
4) Estou a ter problemas de conexão e não consigo emitir a guia ou marcar recolhas. O que fazer?
A DPD usa portos TCP não convencionais para alguns webservices, pelo que terá de solicitar ao seu fornecedor de alojamento web para abrir regras de saída na firewall:
- URL: webservices.chronopost.pt, TCP: 7554 (Para a API de pedidos de recolhas)
URL: cliente.chronopost.pt, TCP: 10003(Apenas para a antiga API SOAP, que já não deverá ter em funcionamento)
Utilização avançada
1) É possível emitir a guia de expedição automaticamente, em vez de utilizar o formulário no ecrã da encomenda?
Sim, mas apenas com developer hooks, nomeadamente o woo_dpd_portugal_issue_label mencionado em baixo.
2) Como é que posso obter automaticamente o Código AT para emissão da guia?
Este plugin integra automaticamente com nosso plugin de facturação WooCommerce para InvoiceXpress bem como o plugin do Moloni.
Em qualquer dos casos, a guia de transporte tem de ser emitida antes da guia DPD. No caso do Moloni, se está a emitir Facturas ou Facturas-recibo, aconselhamos a activação da opção de criar Documento de transporte.
3) É possível obter automaticamente o estado de cada objecto na DPD, em vez de ter de o fazer manualmente no ecrã da encomenda?
O plugin por si só não faz actualizações automáticas do estado dos objectos na DPD. Optámos por não implementar este mecanismo porque cada site é um site, tem estados de encomendas e comportamentos diferentes e não quisemos correr o risco de agendar tarefas de actualização de estado que pudessem eventualmente ficar a correr para sempre, para cada encomenda.
No entanto, criámos mecanismos que permitem a programadores implementar este tipo de funcionalidade, à sua responsabilidade. Os hooks são disponibilizados de acordo com a nossa política de criar plugins o mais developer friendly possível, mas recordamos que a sua utilização está fora do âmbito do suporte técnico.
Para implementar um mecanismo de consulta automática e regular do estado/seguimento dos objectos na DPD, pode ser usada, por exemplo, esta estratégia:
- Escutar o hook de emissão de guia
woo_dpd_portugal_label_issued- Agendar com o
wp_schedule_eventa consulta de estado na DPD comdo_action( 'woo_dpd_portugal_update_order_tracking_information', $order_id );tendo em atenção o intervalo que não aconselhamos ser menor que 4 horas - Escutar o hook de actualização de estado de seguimento de objectos
woo_dpd_portugal_updated_order_tracking_information- Se
$any_updated == truequer dizer que houve actualizações desde a última consulta e então podemos fazer os testes seguintes, em caso contrário não vale a pena fazer nada ou então pode-se verificar há quanto tempo se está a correr a tarefa agendada, sem obter novas actualizações, e parar o agendamento depois de alguns dias para não continuar, para sempre, a fazer consultas à DPD e talvez notificar o dono de loja que deve verificar o que se passa com estes objectos - Se
$all_final == truesignifica que todos os objectos desta encomenda estão num estado considerado final e devemos parar o agendamento de consulta de estado para não continuar, para sempre, a fazer consultas à API da DPD - Se
$all_deliverered == truesignifica que todos os objectos estão entregues e podemos, por exemplo, notificar o cliente e o dono de loja, mudar o estado da encomenda, ou qualquer outra acção que faça sentido no site em causa
- Se
- Agendar com o
O mais importante é garantir, sem falhas, que todas as tarefas agendadas para cada encomenda são canceladas passado algum tempo, seja porque já todos os objectos estão em estado final ou porque passou tempo demais sem obter novas actualizações.
Developer hooks disponíveis
Action: woo_dpd_portugal_label_issued
Corre quando é emitida uma guia de expedição, com sucesso.
Parâmetros: $order_id
Action: woo_dpd_portugal_label_issued_error
Corre quando falha a emissão de uma guia de expedição.
Parâmetros: $order_id, $error_message
Action: woo_dpd_portugal_issue_label
Esta acção pode ser corrida por developers para emitir guias de expedição programaticamente, em vez de utilizarem a metabox no ecrã de encomenda. É aconselhável a utilização do filtro woo_dpd_portugal_shipment_data para definição, por exemplo, do serviço / conta de envio a utilizar. Esta acção não verifica se a guia já foi emitida anteriormente, pelo que é prudente verificar antes de correr a mesma, por exempo consultando o order meta woo_dpd_portugal_tracking_number.
Parâmetros: $order_id
Exemplo de utilização: ver GitHub Gist
Action: woo_dpd_portugal_return_issued
Corre quando é emitida uma guia de devolução, com sucesso.
Parâmetros: $order_id
Action: woo_dpd_portugal_return_issued_error
Corre quando falha a emissão de uma guia de devolução.
Parâmetros: $order_id, $error_message
Action: woo_dpd_portugal_issue_return
Esta acção pode ser corrida por developers para emitir guias de devolução programaticamente, em vez de utilizarem a metabox no ecrã de encomenda. É aconselhável a utilização do filtro woo_dpd_portugal_return_data para definição, por exemplo, do serviço / conta de devolução a utilizar. Esta acção não verifica se a guia já foi emitida anteriormente, pelo que é prudente verificar antes de correr a mesma, por exempo consultando o order meta woo_dpd_portugal_return_tracking_number.
Parâmetros: $order_id
Exemplo de utilização: ver GitHub Gist
Action: woo_dpd_portugal_requested_pickup
Corre quando é efectuado um pedido de recolha, com sucesso.
Parâmetros: $pickup_request
Action: woo_dpd_portugal_request_pickup_error
Corre quando falha o pedido de recolha.
Parâmetros: $error
Action: woo_dpd_portugal_request_pickup
Esta acção pode ser corrida por developers para fazer pedidos de recolha nas instalações da loja programaticamente, em vez de usarem ecrã de recolhas. É aconselhável a utilização do filtro woo_dpd_portugal_request_pickup_data para controlar os dados do pedido.
Parâmetros: nenhum
Action: woo_dpd_portugal_request_return_pickup
Esta acção pode ser corrida por developers para fazer pedidos de recolha na morada do cliente programaticamente, em vez de fazerem o pedido juntamente com a emissão da guia de devolução. É aconselhável a utilização do filtro woo_dpd_portugal_request_return_pickup_data para controlar os dados do pedido.
Parâmetros: $order_id
Filter: woo_dpd_portugal_available_services
Permite manipular a lista de serviços DPD disponíveis para configuração das contas de envio e para escolha no momento da emissão das guias de remessa.
Parâmetros: $services
Exemplo de utilização: ver GitHub Gist
Filter: woo_dpd_portugal_default_shipment_service_for_order
Permite alterar o serviço por omissão para uma determinada encomenda.
Parâmetros: $default_service, $order
Exemplo de utilização: ver GitHub Gist (exemplo de criação de novo serviço com o filtro anterior e escolha por omissão com este filtro)
Filter: woo_dpd_portugal_default_return_service_for_order
Permite alterar o serviço por omissão, de uma guia de devolução, para uma determinada encomenda.
Parâmetros: $default_service, $order, $country
Filter: woo_dpd_portugal_shipment_data
Permite manipular os dados da guia de expedição antes de serem apresentados na metabox no ecrã de encomenda, ou passados para a função de emissão quando é feito de forma programática com a action woo_dpd_portugal_issue_label.
Parâmetros: $shipment_data, $order_id
Filter: woo_dpd_portugal_rest_shipping_params
Permite manipular os dados da guia de expedição antes de serem enviados para a API REST. É preferível usar o filtro woo_dpd_portugal_shipment_data em vez deste.
Parâmetros: $params, $shipment_data, $programmatically
Filter: woo_dpd_portugal_return_data
Permite manipular os dados da guia de devolução antes de serem apresentados na metabox no ecrã de encomenda, ou passados para a função de emissão quando é feito de forma programática com a action woo_dpd_portugal_issue_return.
Parâmetros: $return_data, $order_id
Filter: woo_dpd_portugal_rest_return_params
Permite manipular os dados da guia de devolução antes de serem enviados para a API REST. É preferível usar o filtro woo_dpd_portugal_return_data em vez deste.
Parâmetros: $params, $return_data, $programmatically
Filter: woo_dpd_portugal_available_for_order
Devolvendo false permite não mostrar a metabox para emissão de guias de expedição no ecrã de encomendas e prevenir a emissão das mesmas (também programaticamente). Pode ser útil para evitar que sejam emitidas guias, por exemplo, para encomendas cujo método de entrega não é via DPD Portugal.
Parâmetros: bool = true, $order_id
Filter: woo_dpd_portugal_prevent_issue_label
Devolvendo true permite evitar a emissão da guia de expedição, com base em regras definidas pelo dono da loja e com o facto do pedido de emissão ter sido feito programaticamente (com a action woo_dpd_portugal_issue_label) ou não.
Parâmetros: bool = false, $order_id, $programmatically
Filter: woo_dpd_portugal_prevent_issue_return
Devolvendo true permite evitar a emissão da guia de devolução, com base em regras definidas pelo dono da loja e com o facto do pedido de emissão ter sido feito programaticamente (com a action woo_dpd_portugal_issue_return) ou não.
Parâmetros: bool = false, $order_id, $programmatically
Filter: woo_dpd_portugal_tracking_on_emails_html
Permite manipular o HTML (ou plain text) da informação de seguimento que é adicionado aos emails enviados após a emissão da guia de expedição.
Parâmetros: $html, $tracking_numbers, $order, $sent_to_admin, $plain_text
Filter: woo_dpd_portugal_email_tracking_hook_action e woo_dpd_portugal_email_tracking_hook_priority
Permitem alterar a posição do link com informação de seguimento que é adicionado aos emails enviados após a emissão da guia de expedição. Por omissão a action é woocommerce_email_before_order_table e a priority é 10.
Action: woo_dpd_pickup_update_order_tracking_information
Esta acção pode ser corrida por developers para fazer pedidos de informação de seguimento à DPD programaticamente.
Parâmetros: $order_id
Exemplo de utilização: ver GitHub Gist
Action: woo_dpd_portugal_updated_object_tracking_information
Corre depois de ser obtida informação actualizada de seguimento de um objecto na DPD
Parâmetros: $order_id, $tracking_number, $tracking_information, $programmatically
Action: woo_dpd_portugal_updated_order_tracking_information
Corre depois de ser obtida informação actualizada de seguimento de todos os objectos de uma encomenda na DPD
Parâmetros: $order_id, $tracking_information, $all_final, $all_delivered, $any_updated, $programmatically
Exemplo de utilização: ver GitHub Gist
Filter: woo_dpd_portugal_webservice_timeout
Permite manipular o tempo disponível para cada chamada API à DPD. Por omissão é metade fo valor default_socket_timeout definido no PHP. Se necessitar de aumentar este valor porque as chamadas dão frequentemente timeout, tem outros problemas para resolver para os quais deve contactar o seu serviço de alojamento.
Parâmetros: $seconds
Existem outros hooks para uso interno que não estão documentados.