Atualizado em: 23 de Abril de 2026
Guia rápido para programadores que desejam usar este plugin como base em seus projetos.
Aviso importante
Este plugin pode mudar funcionalidades sem aviso prévio para acompanhar atualizações do WooCommerce.
Toda customização é de responsabilidade do desenvolvedor. Não edite os arquivos originais do plugin. Faça suas alterações em código externo:
Requisitos confirmados no plugin:
Dependências embarcadas no plugin:
O plugin carrega um bootstrap de PDF e registra tipos de documento no init. O fluxo geral confirmado é este:
Pontos públicos confirmados para integração:
Limites entre público e interno:
Observação importante: o plugin aceita registro programático de novos tipos de documento, mas a interface visual do pedido continua fixa nos quatro documentos nativos. Um documento customizado pode ser renderizado por código, mas não aparece automaticamente no metabox nem na coluna de ações.
wootatitas_ppdf_bootstrap
Tipo: Action
Quando é executado: Durante plugins_loaded, prioridade 5, após o carregamento base do plugin.
Parâmetros: Nenhum
Retorno: Não se aplica
Exemplo de uso:
add_action(‘wootatitas_ppdf_bootstrap’, function () {
if (!function_exists(‘ppdf_document_exists’)) {
return;
}
if (ppdf_document_exists(‘shipping-label’)) {
// Seu código de integração aqui.
}
});
ppdf_locate_template
Tipo: Filter
Quando é executado: Quando o plugin resolve o arquivo PHP de template que será usado para um documento PDF.
Parâmetros:
$path (string) — caminho atual do template
$type (string) — tipo do documento
$template_slug (string) — slug do template
$doc (array|null) — configuração registrada do documento
Retorno: string — novo caminho do template
Exemplo de uso:
add_filter(‘ppdf_locate_template’, function ($path, $type, $template_slug, $doc) {
if ($type !== ‘shipping-label’ || $template_slug !== ‘template-a4’) {
return $path;
}
$custom = get_stylesheet_directory() . ‘/ppdf/shipping-label-a4.php’;
return file_exists($custom) ? $custom : $path;
}, 10, 4);
ppdf_dc_ncm_meta_keys
Tipo: Filter
Quando é executado: Quando o plugin busca o NCM de um item para a declaração de conteúdo.
Parâmetros: $meta_keys (array) — lista de meta keys candidatas para busca do NCM
Retorno: array — lista final de meta keys
Exemplo de uso:
add_filter(‘ppdf_dc_ncm_meta_keys’, function ($meta_keys) {
array_unshift($meta_keys, ‘_meu_ncm_personalizado’);
return $meta_keys;
});
ppdf_dc_format_ncm
Tipo: Filter
Quando é executado: Depois que o NCM é encontrado e normalizado para apenas dígitos.
Parâmetros: $ncm (string) — NCM encontrado
Retorno: string — NCM final
Exemplo de uso:
add_filter(‘ppdf_dc_format_ncm’, function ($ncm) {
if (strlen($ncm) === 8) {
return substr($ncm, 0, 4) . ‘.’ . substr($ncm, 4, 2) . ‘.’ . substr($ncm, 6, 2);
}
return $ncm;
});
ppdf_receipt_number_formatted
Tipo: Filter
Quando é executado: Quando o plugin monta o número formatado do comprovante.
Parâmetros:
$formatted (string) — número final formatado
$seq (int) — valor bruto usado como base
$prefix (string) — prefixo configurado
$suffix (string) — sufixo configurado
$padding (int|null) — padding aplicado, quando existir
Retorno: string — número final do comprovante
Exemplo de uso:
add_filter(‘ppdf_receipt_number_formatted’, function ($formatted, $seq, $prefix, $suffix, $padding) {
return ‘REC-‘ . $formatted;
}, 10, 5);
ppdf_register_document
Finalidade: Registrar um novo tipo de documento no registro interno do plugin.
Como usar: Passe um identificador e um array com label, template padrão, capability e templates disponíveis.
Parâmetros:
$type (string) — identificador do documento
$args (array) — configuração do documento
Retorno: Não retorna valor útil
Exemplo de uso:
add_action(‘wootatitas_ppdf_bootstrap’, function () {
if (!function_exists(‘ppdf_register_document’)) {
return;
}
ppdf_register_document(‘meu-documento’, [
‘label’ => ‘Meu Documento’,
‘default_template’ => ‘template-default’,
‘capability’ => ‘manage_woocommerce’,
‘templates’ => [
‘template-default’ => get_stylesheet_directory() . ‘/ppdf/meu-documento.php’,
],
]);
});
ppdf_get_document
Finalidade: Ler a configuração registrada de um tipo de documento.
Como usar: Passe o identificador do documento.
Parâmetros: $type (string) — identificador do documento
Retorno: array|null
Exemplo de uso:
$doc = function_exists(‘ppdf_get_document’)
? ppdf_get_document(‘shipping-label’)
: null;
ppdf_all_documents
Finalidade: Retornar todos os tipos de documento registrados.
Como usar: Útil para inspecionar o registro e montar lógicas administrativas próprias.
Parâmetros: Nenhum
Retorno: array
Exemplo de uso:
if (function_exists(‘ppdf_all_documents’)) {
$docs = ppdf_all_documents();
}
ppdf_document_exists
Finalidade: Verificar se um tipo de documento está registrado.
Como usar: Passe o identificador do documento.
Parâmetros: $type (string) — identificador do documento
Retorno: bool
Exemplo de uso:
if (function_exists(‘ppdf_document_exists’) && ppdf_document_exists(‘packing-slip’)) {
// Documento registrado.
}
ppdf_locate_template
Finalidade: Resolver o caminho final do template de um documento, já considerando o filtro ppdf_locate_template.
Como usar: Passe o tipo do documento e o slug do template.
Parâmetros:
$type (string) — tipo do documento
$template_slug (string) — slug do template
Retorno: string
Exemplo de uso:
if (function_exists(‘ppdf_locate_template’)) {
$path = ppdf_locate_template(‘shipping-label’, ‘template-a6’);
}
ppdf_render_document
Finalidade: Renderizar um PDF binário para um único pedido.
Como usar: Passe o tipo do documento, o ID do pedido, o template e as opções de renderização.
Parâmetros:
$type (string) — tipo do documento
$order_id (int) — ID do pedido
$template_slug (string) — slug do template
$opts (array) — opções como paper, orientation, dpi e filename
Retorno: array no formato [ $filename, $pdf_binario ]
Exemplo de uso:
if (function_exists(‘ppdf_render_document’)) {
list($filename, $pdf) = ppdf_render_document(
‘shipping-label’,
123,
‘label-100×150’,
[
‘paper’ => [100, 150],
‘orientation’ => ‘portrait’,
‘dpi’ => 96,
‘filename’ => ‘etiqueta-pedido-123.pdf’,
]
);
}
ppdf_render_document_multi
Finalidade: Renderizar um único PDF contendo vários pedidos, cada um em sua própria página.
Como usar: Passe o tipo do documento e uma lista de IDs de pedido.
Parâmetros:
$type (string) — tipo do documento
$order_ids (array) — lista de IDs
$template_slug (string) — slug do template
$opts (array) — opções de renderização
Retorno: array no formato [ $filename, $pdf_binario ]
Exemplo de uso:
if (function_exists(‘ppdf_render_document_multi’)) {
list($filename, $pdf) = ppdf_render_document_multi(
‘packing-slip’,
[101, 102, 103],
‘template-compact’,
[
‘paper’ => ‘A4’,
‘orientation’ => ‘portrait’,
‘filename’ => ‘lote-separacao.pdf’,
]
);
}
ppdf_receipt_format_number
Finalidade: Formatar o número do comprovante com base nas opções atuais do plugin.
Como usar: Passe o número bruto.
Parâmetros: $seq (int) — número base
Retorno: string
Exemplo de uso:
if (function_exists(‘ppdf_receipt_format_number’)) {
$numero = ppdf_receipt_format_number(42);
}
ppdf_receipt_get_saved_number
Finalidade: Ler o número do comprovante já salvo no pedido.
Como usar: Passe o ID do pedido.
Parâmetros: $order_id (int) — ID do pedido
Retorno: string
Exemplo de uso:
if (function_exists(‘ppdf_receipt_get_saved_number’)) {
$numero = ppdf_receipt_get_saved_number($order_id);
}
ppdf_receipt_get_or_assign_number
Finalidade: Retornar o número bruto do comprovante, atribuindo um se ainda não existir.
Como usar: Use com cuidado, porque essa função pode efetivamente gravar a numeração no pedido.
Parâmetros: $order_id (int) — ID do pedido
Retorno: int
Exemplo de uso:
if (function_exists(‘ppdf_receipt_get_or_assign_number’)) {
$raw = ppdf_receipt_get_or_assign_number($order_id);
}
ppdf_dc_get_item_ncm
Finalidade: Buscar o NCM de um item do pedido, incluindo fallback de variação para produto pai.
Como usar: Passe um objeto WC_Order_Item_Product.
Parâmetros: $item (WC_Order_Item_Product) — item do pedido
Retorno: string
Exemplo de uso:
$order = wc_get_order($order_id);
if ($order && function_exists(‘ppdf_dc_get_item_ncm’)) {
foreach ($order->get_items(‘line_item’) as $item) {
$ncm = ppdf_dc_get_item_ncm($item);
}
}
admin-ajax.php?action=ppdf_preview
Tipo: AJAX
Finalidade: Pré-visualizar inline um PDF de pedido no painel.
Método: GET
Parâmetros aceito:
Resposta esperada:
Autenticação necessária:
Exemplo de requisição:
$preview_url = add_query_arg([
‘action’ => ‘ppdf_preview’,
‘doc’ => ‘shipping-label’,
‘order_id’ => 123,
‘template’ => ‘label-100×150’,
‘_wpnonce’ => wp_create_nonce(‘ppdf_preview_123’),
], admin_url(‘admin-ajax.php’));
Exemplo de resposta:
PDF binário retornado inline no navegador.
admin-ajax.php?action=ppdf_download
Tipo: AJAX
Finalidade: Baixar um PDF de pedido como anexo.
Método: GET
Parâmetros aceito:
Resposta esperada:
Autenticação necessária:
Exemplo de requisição:
$download_url = add_query_arg([
‘action’ => ‘ppdf_download’,
‘doc’ => ‘packing-slip’,
‘order_id’ => 123,
‘template’ => ‘template-compact’,
‘_wpnonce’ => wp_create_nonce(‘ppdf_download_123’),
], admin_url(‘admin-ajax.php’));
Exemplo de resposta:
PDF binário enviado para download.
7.1. Tipos de documento nativos
| Tipo | Finalidade | Templates confirmados |
|---|---|---|
content-declaration | Declaração de conteúdo | template-com-valores, template-sem-valores |
order-receipt | Comprovante de pedido | template-default |
packing-slip | Lista de separação | template-classic, template-compact |
shipping-label | Etiqueta de envio | label-100x150, template-a6, template-a4 |
7.2. Estrutura de registro de documento
Ao registrar um documento com ppdf_register_document, o array esperado é este:
| Chave | Tipo | Descrição |
|---|---|---|
label | string | Nome administrativo do documento |
default_template | string | slug do template padrão |
capability | string | capability exigida |
templates | array | mapa slug => caminho_absoluto_do_template |
7.3. Opções públicas úteis para integração
As opções abaixo são lidas diretamente pelo plugin e influenciam a renderização:
| Option name | Uso |
|---|---|
ppdf_default_label_template | template padrão da etiqueta |
ppdf_default_dc_template | template padrão da declaração |
ppdf_packing_template | template da lista de separação |
ppdf_packing_show_prices | exibição de preços na lista de separação |
ppdf_dc_show_ncm | exibição de NCM na declaração |
ppdf_receipt_prefix | prefixo do comprovante |
ppdf_receipt_suffix | sufixo do comprovante |
ppdf_receipt_padding | padding do comprovante |
ppdf_receipt_number_source | origem da numeração do comprovante |
ppdf_label_barcode_type | tipo de código na etiqueta |
ppdf_label_barcode_payload | origem do payload do QR/código |
ppdf_label_barcode_custom_url | URL customizada com placeholders |
ppdf_tpl_name | nome do remetente |
ppdf_tpl_address | endereço do remetente |
ppdf_tpl_city | cidade do remetente |
ppdf_tpl_state | estado do remetente |
ppdf_tpl_postcode | CEP do remetente |
ppdf_tpl_document | documento do remetente |
ppdf_tpl_declaracao | texto da declaração |
ppdf_tpl_observacao | texto de observações |
ppdf_tpl_logo_id | attachment ID do logotipo |
7.4 Metadados de pedido úteis
| Meta key | Uso |
|---|---|
_ppdf_receipt_number | número formatado do comprovante |
_ppdf_receipt_number_raw | número bruto do comprovante |
_ppdf_receipt_number_src | origem da numeração |
7.5 Variáveis disponíveis em templates de documento
Nos templates carregados por ppdf_render_document e ppdf_render_document_multi, estas variáveis são confirmadas:
| Variável | Tipo | Descrição |
|---|---|---|
$order | WC_Order | pedido atual |
$order_id | int | ID do pedido |
$document_type | string | tipo do documento |
$template_name | string | slug do template |
Exemplo 1: sobrescrever um template nativo
add_filter(‘ppdf_locate_template’, function ($path, $type, $template_slug, $doc) {
if ($type !== ‘packing-slip’ || $template_slug !== ‘template-classic’) {
return $path;
}
$custom = get_stylesheet_directory() . ‘/ppdf/packing-slip-classic.php’;
return file_exists($custom) ? $custom : $path;
}, 10, 4);
Exemplo 2: registrar um documento customizado para uso programático
add_action(‘wootatitas_ppdf_bootstrap’, function () {
if (!function_exists(‘ppdf_register_document’)) {
return;
}
ppdf_register_document(‘pedido-resumido’, [
‘label’ => ‘Pedido Resumido’,
‘default_template’ => ‘template-default’,
‘capability’ => ‘manage_woocommerce’,
‘templates’ => [
‘template-default’ => __DIR__ . ‘/templates/pedido-resumido.php’,
],
]);
});
Exemplo 3: gerar PDF por código
$order_id = 123;
if (function_exists(‘ppdf_render_document’)) {
list($filename, $pdf_binario) = ppdf_render_document(
‘order-receipt’,
$order_id,
‘template-default’,
[
‘paper’ => ‘A4’,
‘orientation’ => ‘portrait’,
‘dpi’ => 96,
‘filename’ => ‘comprovante-personalizado.pdf’,
]
);
// Exemplo: salvar em arquivo temporário
file_put_contents(WP_CONTENT_DIR . ‘/uploads/’ . $filename, $pdf_binario);
}
Exemplo 4: gerar lote de listas de separação
$order_ids = [1201, 1202, 1203];
if (function_exists(‘ppdf_render_document_multi’)) {
list($filename, $pdf_binario) = ppdf_render_document_multi(
‘packing-slip’,
$order_ids,
‘template-compact’,
[
‘paper’ => ‘A4’,
‘orientation’ => ‘portrait’,
‘filename’ => ‘separacao-lote.pdf’,
]
);
}
Exemplo 5: ajustar busca de NCM
add_filter(‘ppdf_dc_ncm_meta_keys’, function ($keys) {
return [
‘_meu_plugin_ncm’,
‘_ncm’,
‘_ncm_code’,
‘ncm’,
‘_wpm_ncm’,
];
});
Exemplo 6: criar link administrativo de download
function meu_link_ppdf_download($order_id) {
return add_query_arg([
‘action’ => ‘ppdf_download’,
‘doc’ => ‘shipping-label’,
‘order_id’ => $order_id,
‘template’ => ‘label-100×150’,
‘_wpnonce’ => wp_create_nonce(‘ppdf_download_’ . $order_id),
], admin_url(‘admin-ajax.php’));
}
O plugin permite integrar geração de PDFs, sobrescrever templates nativos, registrar documentos adicionais para renderização programática e ler metadados relacionados à numeração do comprovante.
Até o momento, não foram identificados no código:
Os documentos nativos mostrados na interface do pedido são fixos:
Mesmo que um novo documento seja registrado por código, ele não entra automaticamente no metabox do pedido nem na coluna de ações do WooCommerce.
A geração e a pré-visualização via AJAX são administrativas e exigem manage_woocommerce e nonce válido. Portanto, não são uma API pública de frontend.
O plugin oferece integração principalmente por funções PHP públicas, filtro de template, alguns hooks específicos e AJAX administrativo autenticado.
O nível de extensibilidade é bom para customização de documentos, criação de templates próprios e geração programática de PDFs, mas a interface visual do pedido continua limitada aos documentos nativos.
Os principais cuidados são: carregar a integração no momento certo, usar apenas pontos públicos confirmados, tratar com cuidado a numeração do comprovante e evitar qualquer dependência de partes protegidas ou internas.
Gostou do que viu? Compre o nosso plugin:
Comercializamos plugins na esperança de que seja útil, porém, é importante observar que ele é fornecido SEM NENHUMA GARANTIA inclusive sem a garantia implícita de ADEQUAÇÃO A UM DETERMINADO FIM.
Estamos sempre prontos para aprimorar nosso plugin e personalizá-lo de acordo com suas necessidades específicas. Não hesite em nos contatar a qualquer momento, estamos aqui para ajudá-lo.
Seus dados estão protegidos conosco.
Leia nossa Proteção de Dados.
© 2026 | Feito com ♥
39.840.429/0001-22
