Custom Post Types e taxonomias no WordPress

Atualizado em 19/06/2026

O WordPress nasceu como blog, mas há tempos é um CMS completo. A peça que viabiliza isso são os Custom Post Types (CPTs) — tipos de conteúdo personalizados além de "post" e "página" — e as taxonomias, que classificam esse conteúdo. Com eles você modela imóveis, eventos, produtos ou portfólio com menus, URLs e campos próprios. Este guia mostra como registrar tudo no momento certo (init), o que cada argumento faz e como evitar o erro 404 que pega quase todo iniciante.

CPT e taxonomia: o que é cada um

• Custom Post Type: o conteúdo em si. Um imovel, um evento, um depoimento. Tem menu próprio no painel, listagem, edição e (opcionalmente) arquivo público.
• Taxonomia: a forma de agrupar esse conteúdo. categoria e tag são taxonomias nativas dos posts; você cria as suas (ex.: tipo_imovel, cidade) e as associa ao CPT.

Taxonomias podem ser hierárquicas (como categorias, com pai/filho) ou não hierárquicas (como tags, lista plana). A escolha define como o usuário seleciona os termos no editor.

Registrando um CPT no hook init

O registro acontece no hook init. Registrar tarde demais (ou no hook errado) faz o WordPress não reconhecer o tipo. Veja um CPT livro completo:

<?php
add_action( 'init', 'meu_registrar_cpt_livro' );

function meu_registrar_cpt_livro() {

    $labels = array(
        'name'          => 'Livros',
        'singular_name' => 'Livro',
        'add_new_item'  => 'Adicionar novo livro',
        'edit_item'     => 'Editar livro',
        'search_items'  => 'Buscar livros',
        'not_found'     => 'Nenhum livro encontrado',
    );

    $args = array(
        'labels'        => $labels,
        'public'        => true,                 // visível no front e no admin
        'has_archive'   => true,                 // habilita /livro/ (arquivo)
        'rewrite'       => array( 'slug' => 'livros' ), // URLs /livros/...
        'menu_icon'     => 'dashicons-book',     // ícone no menu do admin
        'show_in_rest'  => true,                 // editor de blocos + REST API
        'supports'      => array( 'title', 'editor', 'thumbnail', 'excerpt' ),
    );

    register_post_type( 'livro', $args );
}

Principais argumentos de register_post_type()

Registrando uma taxonomia e associando ao CPT

A taxonomia também é registrada no init. Importante: registre a taxonomia depois do CPT (ou simplesmente no mesmo hook), e informe no terceiro parâmetro a qual(is) post type(s) ela se aplica. Aqui criamos genero_livro, hierárquica, ligada ao CPT livro:

<?php
add_action( 'init', 'meu_registrar_taxonomia_genero' );

function meu_registrar_taxonomia_genero() {

    $labels = array(
        'name'          => 'Gêneros',
        'singular_name' => 'Gênero',
        'add_new_item'  => 'Adicionar novo gênero',
        'search_items'  => 'Buscar gêneros',
    );

    $args = array(
        'labels'            => $labels,
        'hierarchical'      => true,   // true = como categorias; false = como tags
        'public'            => true,
        'show_in_rest'      => true,   // necessário no editor de blocos
        'show_admin_column' => true,   // mostra a coluna na listagem do CPT
        'rewrite'           => array( 'slug' => 'genero' ),
    );

    // 3º parâmetro: o(s) post type(s) ao(s) qual(is) a taxonomia se aplica
    register_taxonomy( 'genero_livro', array( 'livro' ), $args );
}

O erro clássico: URLs do CPT dando 404

Você registra o CPT, acessa /livros/algum-livro/ e leva um 404. O conteúdo existe, mas a URL "não existe". O motivo: as regras de reescrita (rewrite rules) que mapeiam essas URLs bonitas para a consulta interna só passam a valer depois de serem gravadas. Registrar o CPT no init não regrava essas regras sozinho.

A solução depende do contexto:

• Em desenvolvimento, o jeito mais rápido: vá em Configurações → Links permanentes e clique em Salvar. Isso dispara um flush das regras.
• Em um plugin, automatize: rode flush_rewrite_rules() uma única vez, na ativação do plugin — não a cada requisição.

<?php
// Arquivo principal do plugin

// 1) O CPT é registrado normalmente no init (em toda requisição)
add_action( 'init', 'meu_registrar_cpt_livro' );

// 2) Na ATIVAÇÃO: registra o CPT e DEPOIS regrava as regras, uma vez só
register_activation_hook( __FILE__, 'meu_plugin_na_ativacao' );

function meu_plugin_na_ativacao() {
    // Importante: o CPT precisa existir antes do flush,
    // por isso chamamos o registro aqui também.
    meu_registrar_cpt_livro();
    flush_rewrite_rules();
}

// 3) Boa prática: limpar as regras também na desativação
register_deactivation_hook( __FILE__, 'flush_rewrite_rules' );

Registre cedo, não tarde demais

O init é o hook correto para CPTs e taxonomias: ele dispara após o WordPress carregar, mas antes de processar a requisição. Registrar em hooks tardios (como wp ou template_redirect) faz o tipo "não existir" para a consulta da página, gerando comportamentos inconsistentes. Se você usa uma classe, conecte o método ao init normalmente:

<?php
class Meu_CPT_Livro {

    public function __construct() {
        add_action( 'init', array( $this, 'registrar' ) );
    }

    public function registrar() {
        register_post_type( 'livro', array(
            'public'       => true,
            'has_archive'  => true,
            'show_in_rest' => true,
            'supports'     => array( 'title', 'editor', 'thumbnail' ),
            'rewrite'      => array( 'slug' => 'livros' ),
            'label'        => 'Livros',
        ) );
    }
}

new Meu_CPT_Livro();

Depois de criados, você consulta esses tipos com a WP_Query usando o argumento post_type, e filtra por termos com tax_query. O registro de CPTs e taxonomias normalmente vive em um plugin próprio, para que o conteúdo sobreviva à troca de tema.