Skip to content

unkdevv/carzTheme-api

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
README.md
README.md
 
 
admin.js
admin.js
 
 
carztheme-api.php
carztheme-api.php
 
 
jwt-handler.php
jwt-handler.php
 
 

Repository files navigation

Paradigma REST API

Plugin WordPress que cria endpoints REST API completos para gerenciar veículos (Custom Post Type cpt_cars) e suas taxonomias através de uma API REST moderna com suporte JWT.

� Índice

�📋 Descrição

Este plugin foi desenvolvido para o tema carz – Car Dealer, Shop & Repair WordPress Theme e oferece uma API REST completa para consulta (GET) e manipulação (POST/PUT/DELETE) de veículos, fabricantes, modelos, recursos e muito mais. Suporta dois tipos de autenticação: API Key (para leitura) e JWT (para escrita).

✨ Funcionalidades

🔹 API REST Completa

  • ✅ Métodos HTTP: GET, POST, PUT, DELETE
  • ✅ CRUD Completo: Criar, Ler, Atualizar e Deletar veículos e taxonomias
  • ✅ Namespace Padrão: carz-api/v1
  • ✅ Endpoint Personalizado: Defina seu próprio endpoint (ex: api/veiculos)

🔹 Recursos Principais

  • ✅ Veículos: CRUD completo de veículos com 30+ campos
  • ✅ Fabricantes (Makers): Gerenciar marcas de veículos
  • ✅ Modelos (Models): Gerenciar modelos por fabricante
  • ✅ Recursos (Features): Equipamentos e características
  • ✅ Tipos (Types): Categorias de veículos (SUV, Sedan, etc)
  • ✅ Status: Para venda, para alugar, etc
  • ✅ Labels: Etiquetas personalizadas
  • ✅ Cidades (Cities): Localização dos veículos
  • ✅ Agentes (Agents): Vendedores/contatos
  • ✅ Upload de Imagens: Enviar e gerenciar mídia

🔹 Autenticação Dupla

  • ✅ API Key: Para operações GET (leitura)

    • Via header X-API-Key
    • Via query string ?api_key=
    • Opcional ou obrigatória
    • Gerador automático de chaves seguras (64 caracteres)

  • ✅ JWT (JSON Web Token): Para operações POST/PUT/DELETE (escrita)

    • Implementação nativa sem dependências externas
    • Algoritmos suportados: HS256, HS384, HS512
    • Token no header Authorization: Bearer {token}
    • Validação de expiração automática

🔹 Recursos Adicionais

  • ✅ CORS Habilitado: Suporte para requisições cross-origin
  • ✅ Pretty Print: Formatar JSON com ?pretty
  • ✅ Status Visual: Coluna na lista de carros mostrando disponibilidade
  • ✅ Interface Amigável: Página de configurações com exemplos
  • ✅ Gerador de API Key: Gere chaves seguras com um clique

📦 Instalação

  1. Faça upload da pasta carztheme-api para /wp-content/plugins/
  2. Ative o plugin através do menu 'Plugins' no WordPress
  3. Acesse Configurações > Paradigma API para configurar
  4. Configure o JWT_SECRET no wp-config.php (veja seção de Configuração JWT)

💻 Requisitos

  • ✅ WordPress 5.0 ou superior
  • ✅ PHP 7.0 ou superior
  • ✅ TRX Addons plugin ativo
  • ✅ Custom Post Type cpt_cars configurado

⚙️ Configuração

🔐 Configuração JWT (Obrigatório para POST/PUT/DELETE)

Para usar operações de escrita (POST, PUT, DELETE), você DEVE configurar o JWT_SECRET:

  1. Abra o arquivo wp-config.php na raiz do WordPress
  2. Adicione a seguinte linha antes de /* That's all, stop editing! */:
define('JWT_SECRET', 'sua-chave-secreta-super-forte-aqui-minimo-32-caracteres');

⚠️ IMPORTANTE:

  • Use uma string aleatória e forte (mínimo 32 caracteres)
  • NUNCA compartilhe seu JWT_SECRET
  • Pode gerar uma chave forte em: Random.org

Exemplo de JWT_SECRET seguro:

define('JWT_SECRET', 'K8mN2pQ5rS9tV3wX6zA4bC7dE0fG1hJ4kL8mN2pQ5rS9tV3');

1️⃣ Endpoints Disponíveis

🔹 Veículos (Vehicles)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/vehicles Listar todos os veículos API Key (opcional)
GET /wp-json/carz-api/v1/vehicles/{id} Obter veículo específico API Key (opcional)
POST /wp-json/carz-api/v1/vehicles Criar novo veículo JWT (obrigatório)
PUT /wp-json/carz-api/v1/vehicles/{id} Atualizar veículo JWT (obrigatório)
DELETE /wp-json/carz-api/v1/vehicles/{id} Deletar veículo JWT (obrigatório)

🔹 Fabricantes (Makers)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/makers Listar todos os fabricantes API Key (opcional)
POST /wp-json/carz-api/v1/makers Criar novo fabricante JWT (obrigatório)
PUT /wp-json/carz-api/v1/makers/{id} Atualizar fabricante JWT (obrigatório)
DELETE /wp-json/carz-api/v1/makers/{id} Deletar fabricante JWT (obrigatório)

🔹 Modelos (Models)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/models Listar todos os modelos API Key (opcional)
GET /wp-json/carz-api/v1/models?maker_id={id} Filtrar por fabricante API Key (opcional)
POST /wp-json/carz-api/v1/models Criar novo modelo JWT (obrigatório)
PUT /wp-json/carz-api/v1/models/{id} Atualizar modelo JWT (obrigatório)
DELETE /wp-json/carz-api/v1/models/{id} Deletar modelo JWT (obrigatório)

🔹 Recursos (Features)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/features Listar todos os recursos API Key (opcional)
POST /wp-json/carz-api/v1/features Criar novo recurso JWT (obrigatório)
PUT /wp-json/carz-api/v1/features/{id} Atualizar recurso JWT (obrigatório)
DELETE /wp-json/carz-api/v1/features/{id} Deletar recurso JWT (obrigatório)

🔹 Tipos (Types)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/types Listar todos os tipos Nenhuma
POST /wp-json/carz-api/v1/types Criar novo tipo JWT (obrigatório)
PUT /wp-json/carz-api/v1/types/{id} Atualizar tipo JWT (obrigatório)
DELETE /wp-json/carz-api/v1/types/{id} Deletar tipo JWT (obrigatório)

🔹 Status

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/status Listar todos os status Nenhuma
POST /wp-json/carz-api/v1/status Criar novo status JWT (obrigatório)
DELETE /wp-json/carz-api/v1/status/{id} Deletar status JWT (obrigatório)

🔹 Labels

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/labels Listar todos os labels Nenhuma
POST /wp-json/carz-api/v1/labels Criar novo label JWT (obrigatório)
DELETE /wp-json/carz-api/v1/labels/{id} Deletar label JWT (obrigatório)

🔹 Cidades (Cities)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/cities Listar todas as cidades Nenhuma
POST /wp-json/carz-api/v1/cities Criar nova cidade JWT (obrigatório)
PUT /wp-json/carz-api/v1/cities/{id} Atualizar cidade JWT (obrigatório)
DELETE /wp-json/carz-api/v1/cities/{id} Deletar cidade JWT (obrigatório)

🔹 Agentes (Agents)

Método Endpoint Descrição Autenticação
GET /wp-json/carz-api/v1/agents Listar todos os agentes API Key (opcional)
GET /wp-json/carz-api/v1/agents/{id} Obter agente específico API Key (opcional)
POST /wp-json/carz-api/v1/agents Criar novo agente JWT (obrigatório)
PUT /wp-json/carz-api/v1/agents/{id} Atualizar agente JWT (obrigatório)
DELETE /wp-json/carz-api/v1/agents/{id} Deletar agente JWT (obrigatório)

🔹 Upload de Mídia

Método Endpoint Descrição Autenticação
POST /wp-json/carz-api/v1/upload Fazer upload de imagem JWT (obrigatório)
DELETE /wp-json/carz-api/v1/media/{id} Deletar imagem JWT (obrigatório)

🔹 Endpoint Personalizado (opcional)

Você pode definir um endpoint personalizado em Configurações > Paradigma API.

Exemplo: Se você definir api/veiculos:

GET /api/veiculos          # Listar todos
GET /api/veiculos/{id}     # Obter específico

2️⃣ Configurar Endpoint Personalizado

  1. Acesse Configurações > Paradigma API
  2. No campo "Endpoint Personalizado", digite o caminho (ex: api/veiculos)
  3. Clique em Salvar Configurações
  4. Clique em Atualizar Permalinks
  5. Teste o endpoint clicando no botão "Testar"

3️⃣ Configurar Autenticação API Key (Opcional - para GET)

  1. Marque a opção "Requer Autenticação"
  2. Clique em "Gerar API Key" para criar uma chave segura
  3. Clique em Salvar Configurações
  4. Use a API Key nas suas requisições (veja exemplos abaixo)

🚀 Como Usar a API

🔹 Operações GET (Leitura) - Com/Sem API Key

Exemplo 1: JavaScript (Fetch) - Sem Autenticação

fetch('https://seusite.com/wp-json/carz-api/v1/vehicles')
    .then(response => response.json())
    .then(data => {
        console.log(`Total de veículos: ${data.length}`);
        data.forEach(vehicle => {
            console.log(`${vehicle.title} - ${vehicle.prices.price}`);
        });
    });

Exemplo 2: JavaScript - Com API Key no Header (Recomendado)

fetch('https://seusite.com/wp-json/carz-api/v1/vehicles', {
    headers: {
        'X-API-Key': 'carz_1234567890abcdef...'
    }
})
    .then(response => response.json())
    .then(data => {
        console.log(data);
    });

Exemplo 3: JavaScript - Com API Key na URL

const apiKey = 'carz_1234567890abcdef...';
fetch(`https://seusite.com/api/veiculos?api_key=${apiKey}`)
    .then(response => response.json())
    .then(data => {
        console.log(data);
    });

🔹 Operações POST/PUT/DELETE (Escrita) - Com JWT

Para criar, atualizar ou deletar recursos, você precisa de um token JWT válido.

Passo 1: Gerar Token JWT

IMPORTANTE: Você precisa criar um endpoint de login personalizado ou usar um plugin de autenticação JWT WordPress. O token deve ser gerado com o mesmo JWT_SECRET configurado no wp-config.php.

Exemplo básico de geração de token (executar no backend):

// Em um arquivo PHP do WordPress
require_once ABSPATH . 'wp-content/plugins/carztheme-api/jwt-handler.php';

$jwt_secret = JWT_SECRET; // Definido no wp-config.php

// Dados do token
$token_data = array(
    'user_id' => 1, // ID do usuário
    'email' => 'admin@exemplo.com',
);

// Gerar token válido por 24 horas (86400 segundos)
$token = Carz_JWT_Handler::generate_token($token_data, $jwt_secret, 86400);

echo "Seu token JWT: " . $token;

Exemplo com JavaScript usando biblioteca JWT (Node.js):

const jwt = require('jsonwebtoken');

const JWT_SECRET = 'K8mN2pQ5rS9tV3wX6zA4bC7dE0fG1hJ4kL8mN2pQ5rS9tV3'; // Mesmo do wp-config.php

const payload = {
    user_id: 1,
    email: 'admin@exemplo.com',
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60), // 24 horas
    iss: 'https://seusite.com'
};

const token = jwt.sign(payload, JWT_SECRET, { algorithm: 'HS256' });
console.log('Token JWT:', token);

Passo 2: Usar Token para Criar Veículo (POST)

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Seu token JWT

const newVehicle = {
    title: 'Ferrari F8 Tributo 2024',
    description: 'Superesportivo italiano com motor V8 turbo',
    price: '1500000',
    specifications: {
        year: '2024',
        fuel: 'Gasolina',
        transmission: 'Automática',
        mileage: '0'
    }
};

fetch('https://seusite.com/wp-json/carz-api/v1/vehicles', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(newVehicle)
})
    .then(response => response.json())
    .then(data => {
        if (data.error) {
            console.error('Erro:', data.error);
        } else {
            console.log('Veículo criado:', data);
        }
    })
    .catch(error => console.error('Erro:', error));

Passo 3: Atualizar Veículo (PUT)

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const vehicleId = 123;

const updatedData = {
    price: '1450000',
    specifications: {
        mileage: '500'
    }
};

fetch(`https://seusite.com/wp-json/carz-api/v1/vehicles/${vehicleId}`, {
    method: 'PUT',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(updatedData)
})
    .then(response => response.json())
    .then(data => {
        console.log('Veículo atualizado:', data);
    });

Passo 4: Deletar Veículo (DELETE)

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const vehicleId = 123;

fetch(`https://seusite.com/wp-json/carz-api/v1/vehicles/${vehicleId}`, {
    method: 'DELETE',
    headers: {
        'Authorization': `Bearer ${token}`
    }
})
    .then(response => response.json())
    .then(data => {
        console.log('Veículo deletado:', data);
    });

🔹 Exemplos Adicionais

Exemplo 4: PHP (cURL) - GET com API Key

$ch = curl_init('https://seusite.com/wp-json/carz-api/v1/vehicles');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: carz_1234567890abcdef...'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

foreach ($data as $vehicle) {
    echo $vehicle['title'] . ' - ' . $vehicle['prices']['price'] . PHP_EOL;
}

Exemplo 5: PHP (cURL) - POST com JWT

$token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

$newVehicle = array(
    'title' => 'Porsche 911 Turbo S',
    'price' => '1200000',
    'specifications' => array(
        'year' => '2024',
        'fuel' => 'Gasolina'
    )
);

$ch = curl_init('https://seusite.com/wp-json/carz-api/v1/vehicles');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($newVehicle));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

print_r($data);

Exemplo 6: Python - GET

import requests

headers = {'X-API-Key': 'carz_1234567890abcdef...'}
response = requests.get(
    'https://seusite.com/wp-json/carz-api/v1/vehicles',
    headers=headers
)

data = response.json()
print(f"Total: {len(data)}")

for vehicle in data:
    print(f"{vehicle['title']} - {vehicle['prices']['price']}")

Exemplo 7: Python - POST com JWT

import requests

token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

new_vehicle = {
    'title': 'Lamborghini Huracán',
    'price': '2000000',
    'specifications': {
        'year': '2024',
        'fuel': 'Gasolina'
    }
}

response = requests.post(
    'https://seusite.com/wp-json/carz-api/v1/vehicles',
    json=new_vehicle,
    headers=headers
)

print(response.json())

Exemplo 8: jQuery/AJAX - GET

$.ajax({
    url: 'https://seusite.com/wp-json/carz-api/v1/vehicles',
    method: 'GET',
    headers: {
        'X-API-Key': 'carz_1234567890abcdef...'
    },
    success: function(data) {
        console.log('Total:', data.length);
        $.each(data, function(i, vehicle) {
            console.log(vehicle.title, vehicle.prices.price);
        });
    }
});

Exemplo 9: jQuery/AJAX - POST com JWT

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

$.ajax({
    url: 'https://seusite.com/wp-json/carz-api/v1/vehicles',
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + token
    },
    contentType: 'application/json',
    data: JSON.stringify({
        title: 'Audi R8 V10',
        price: '1300000',
        specifications: {
            year: '2024'
        }
    }),
    success: function(data) {
        console.log('Veículo criado:', data);
    },
    error: function(xhr) {
        console.error('Erro:', xhr.responseJSON);
    }
});

🔧 Como Usar com n8n

1. HTTP Request Node - GET (Sem Autenticação)

Configure o nó HTTP Request:

  • Method: GET
  • URL: https://seusite.com/wp-json/carz-api/v1/vehicles
  • Authentication: None
  • Response Format: JSON

2. HTTP Request Node - GET (Com API Key)

Configure o nó HTTP Request:

  1. Method: GET
  2. URL: https://seusite.com/wp-json/carz-api/v1/vehicles
  3. Authentication: Clique em "Add Credential"
  4. Escolha Header Auth
  5. Configure as credenciais:
    • Name: X-API-Key
    • Value: carz_1234567890abcdef... (sua API Key)
  6. Response Format: JSON

3. HTTP Request Node - POST/PUT/DELETE (Com JWT)

Para criar, atualizar ou deletar veículos:

  1. Method: POST | PUT | DELETE
  2. URL:
    • POST: https://seusite.com/wp-json/carz-api/v1/vehicles
    • PUT: https://seusite.com/wp-json/carz-api/v1/vehicles/{{$json.id}}
    • DELETE: https://seusite.com/wp-json/carz-api/v1/vehicles/{{$json.id}}
  3. Authentication: Clique em "Add Credential"
  4. Escolha Header Auth
  5. Configure as credenciais:
    • Name: Authorization
    • Value: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (seu token JWT)
  6. Body Content Type: JSON
  7. Body (para POST/PUT):
{
  "title": "Ferrari F8 Tributo",
  "price": "1500000",
  "specifications": {
    "year": "2024",
    "fuel": "Gasolina",
    "transmission": "Automática"
  }
}

4. Processar Cada Veículo Individualmente (GET)

Adicione um nó Split Out após o HTTP Request:

  • Field to Split Out: Deixe vazio (o array já vem direto)
  • Isso criará um item separado para cada veículo
  • Cada veículo terá seu próprio JSON

5. Mapear Campos com Set Node

Adicione um nó Set para extrair os campos desejados:

Campo            | Expressão
-----------------|----------------------------------
title            | {{ $json.title }}
price            | {{ $json.prices.price }}
year             | {{ $json.specifications.year }}
fuel             | {{ $json.specifications.fuel }}
transmission     | {{ $json.specifications.transmission }}
mileage          | {{ $json.specifications.mileage }}
url              | {{ $json.url }}
image            | {{ $json.featured_image.url }}

6. Exemplo de Workflow Completo - GET

[HTTP Request - GET] 
  ↓ GET https://seusite.com/wp-json/carz-api/v1/vehicles
  ↓ Header: X-API-Key = sua-chave
  ↓
[Split Out] 
  ↓ (Cria um item para cada veículo)
  ↓
[Set] 
  ↓ Mapeia campos desejados
  ↓
[Google Sheets / Airtable / Webhook]
  ↓ Envia dados para destino

7. Exemplo de Workflow - Criar Veículos (POST)

[Webhook / Google Sheets / CSV]
  ↓ Fonte de dados dos veículos
  ↓
[Set] 
  ↓ Formata dados no formato esperado pela API
  ↓
[HTTP Request - POST]
  ↓ POST https://seusite.com/wp-json/carz-api/v1/vehicles
  ↓ Header: Authorization = Bearer {token}
  ↓ Body: JSON com dados do veículo
  ↓
[IF] 
  ↓ Verifica se criação foi bem-sucedida
  ↓
[Sucesso / Erro]

8. Exemplo de Workflow - Atualizar Preços (PUT)

[Schedule Trigger]
  ↓ Executa diariamente às 8h
  ↓
[HTTP Request - GET]
  ↓ Busca todos os veículos
  ↓
[Split Out]
  ↓ Separa cada veículo
  ↓
[Function]
  ↓ Aplica regra de desconto: preço * 0.9
  ↓
[HTTP Request - PUT]
  ↓ PUT https://seusite.com/wp-json/carz-api/v1/vehicles/{{$json.id}}
  ↓ Header: Authorization = Bearer {token}
  ↓ Body: { "price": "{{$json.new_price}}" }

9. Filtrar Veículos no n8n

Use o nó Filter para processar apenas veículos específicos:

// Apenas carros a partir de 2020
{{ $json.specifications.year >= 2020 }}

// Apenas com preço menor que 100000
{{ parseInt($json.prices.price) < 100000 }}

// Apenas Porsche
{{ $json.taxonomies.maker[0].name === "Porsche" }}

10. Gerenciar Token JWT no n8n

Opção 1: Token Fixo (mais simples)

  • Gere um token com validade longa (ex: 30 dias)
  • Use diretamente nas credenciais do n8n
  • Lembre-se de renovar antes de expirar

Opção 2: Token Dinâmico (mais seguro)

[Function Node - Generate JWT]
  ↓ Gera token usando biblioteca jsonwebtoken
  ↓
[Set Node]
  ↓ Armazena token em variável
  ↓
[HTTP Request - POST/PUT/DELETE]
  ↓ Usa token da variável

Código do Function Node:

const jwt = require('jsonwebtoken');

const JWT_SECRET = 'K8mN2pQ5rS9tV3wX6zA4bC7dE0fG1hJ4kL8mN2pQ5rS9tV3';

const payload = {
    user_id: 1,
    email: 'admin@exemplo.com',
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60), // 24h
    iss: 'https://seusite.com'
};

const token = jwt.sign(payload, JWT_SECRET, { algorithm: 'HS256' });

return [{
    json: {
        jwt_token: token
    }
}];

11. Webhook Trigger para Atualizações Automáticas

Configure um webhook no n8n para executar o workflow periodicamente:

  1. Adicione um nó Schedule Trigger
  2. Configure para executar a cada hora/dia
  3. O workflow buscará automaticamente os veículos atualizados

12. Tratamento de Erros no n8n

Adicione um nó Error Trigger para capturar falhas:

[Error Trigger]
  ↓ Captura erros de autenticação ou validação
  ↓
[Set]
  ↓ Formata mensagem de erro
  ↓
[Send Email / Slack / Discord]
  ↓ Notifica sobre o erro

📊 Estrutura de Resposta

✅ GET /vehicles - Sucesso (200 OK)

Formato: Array de objetos JSON (cada objeto = um veículo)

[
  {
    "id": 123,
    "title": "Ferrari F8 Tributo",
    "description": "Descrição completa...",
    "excerpt": "Resumo...",
    "slug": "ferrari-f8-tributo",
    "status": "publish",
    "date": "2024-01-15 10:30:00",
    "modified": "2024-01-20 15:45:00",
    "url": "https://seusite.com/cars/ferrari-f8-tributo",
    "featured_image": {
      "id": 456,
      "url": "https://seusite.com/wp-content/uploads/ferrari.jpg",
      "sizes": {
        "thumbnail": "...",
        "medium": "...",
        "large": "...",
        "full": "..."
      }
    },
    "gallery": [...],
    "prices": {
      "price": "1500000",
      "price2": "",
      "price_prefix": "R$",
      "price2_prefix": ""
    },
    "taxonomies": {
      "maker": [{
        "id": 10,
        "name": "Ferrari",
        "slug": "ferrari"
      }],
      "type": [...],
      "status": [...]
    },
    "specifications": {
      "model": "F8 Tributo",
      "year": "2024",
      "mileage": "0",
      "fuel": "Gasolina",
      "engine_size": "3.9",
      "engine_type": "V8 Turbo",
      "power": "720 cv",
      "transmission": "Automática",
      "drive": "Tração traseira",
      "doors": "2",
      "seats": "2",
      "exterior_color": "Rosso Corsa",
      "interior_color": "Preto",
      "condition": "Novo",
      "vin": "ZFF93VLA0L0123456",
      "registration_date": "2024-01-15"
    },
    "location": {
      "city": "São Paulo",
      "country": "Brasil",
      "address": "Av. Paulista, 1000",
      "location": "-23.5505,-46.6333"
    },
    "features": [
      "Ar condicionado",
      "Direção elétrica",
      "Freios ABS",
      "Airbag"
    ],
    "agent": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "phone": "+55 11 99999-9999"
    },
    "video": {
      "url": "https://youtube.com/watch?v=...",
      "embed": "<iframe>...</iframe>"
    }
  }
]

💡 Importante: A API retorna um array direto onde cada item é um veículo completo.

✅ POST /vehicles - Criação Bem-Sucedida (201 Created)

{
  "success": true,
  "message": "Veículo criado com sucesso",
  "id": 124,
  "data": {
    "id": 124,
    "title": "Porsche 911 Turbo S",
    "slug": "porsche-911-turbo-s",
    "url": "https://seusite.com/cars/porsche-911-turbo-s",
    ...
  }
}

✅ PUT /vehicles/{id} - Atualização Bem-Sucedida (200 OK)

{
  "success": true,
  "message": "Veículo atualizado com sucesso",
  "id": 123,
  "data": {
    "id": 123,
    "title": "Ferrari F8 Tributo",
    ...
  }
}

✅ DELETE /vehicles/{id} - Exclusão Bem-Sucedida (200 OK)

{
  "success": true,
  "message": "Veículo deletado com sucesso",
  "id": 123
}

❌ Erro de Autenticação JWT (401 Unauthorized)

Token ausente:

{
  "code": "rest_forbidden",
  "message": "Token de autenticação ausente. Use o header Authorization: Bearer {token}",
  "data": {
    "status": 401
  }
}

Token inválido ou expirado:

{
  "code": "rest_forbidden",
  "message": "Token JWT inválido ou expirado.",
  "data": {
    "status": 401
  }
}

JWT_SECRET não configurado:

{
  "code": "rest_forbidden",
  "message": "JWT_SECRET não configurado no servidor.",
  "data": {
    "status": 500
  }
}

❌ Erro de Autenticação API Key (401 Unauthorized)

{
  "code": "rest_forbidden",
  "message": "API Key inválida ou ausente.",
  "data": {
    "status": 401
  }
}

⚠️ Recurso Não Encontrado (404 Not Found)

{
  "code": "not_found",
  "message": "Veículo não encontrado.",
  "data": {
    "status": 404
  }
}

⚠️ Dados Inválidos (400 Bad Request)

{
  "code": "invalid_data",
  "message": "Dados inválidos ou incompletos",
  "data": {
    "status": 400,
    "errors": {
      "title": "O título é obrigatório",
      "price": "O preço deve ser numérico"
    }
  }
}

🎨 Formato do JSON

🚀 Modo Compacto (Padrão - Produção)

Por padrão, o JSON é retornado em uma única linha (compacto) para melhor performance e economia de banda:

# Produção (compacto, rápido)
GET /wp-json/carz-api/v1/vehicles

Resposta:

[{"id":123,"title":"Ferrari F8","price":"1500000"},{"id":124,"title":"Porsche 911","price":"1200000"}]

🐛 Modo Pretty Print (Desenvolvimento/Debug)

Adicione ?pretty na URL para formatação legível com indentação (útil para desenvolvimento e debug):

# Debug (formatado, legível)
GET /wp-json/carz-api/v1/vehicles?pretty

Resposta:

[
  {
    "id": 123,
    "title": "Ferrari F8",
    "price": "1500000"
  },
  {
    "id": 124,
    "title": "Porsche 911",
    "price": "1200000"
  }
]

💡 Dica: Use o modo pretty durante desenvolvimento e testes, mas remova em produção para melhor performance.

📋 Campos de Dados

Cada veículo contém:

🔹 Dados Básicos

  • id, title, description, excerpt
  • slug, status, date, modified, url

🔹 Imagens

  • featured_image - Imagem destacada (com 4 tamanhos)
  • gallery - Array de imagens (com 4 tamanhos cada)

🔹 Preços

  • prices.price / price2
  • prices.price_prefix / price2_prefix

🔹 Taxonomias

  • taxonomies.maker - Fabricante(s)
  • taxonomies.type - Tipo(s)
  • taxonomies.status - Status

🔹 Especificações (17 campos)

  • Modelo, Ano, Quilometragem
  • Combustível, Motor, Potência
  • Transmissão, Tração, Portas, Assentos
  • Cores, Condição, VIN, Data de registro

🔹 Localização

  • Cidade, País, Endereço, Coordenadas

🔹 Outros

  • features - Características/equipamentos
  • agent - Dados do vendedor
  • video - URLs de vídeo

🔐 Segurança

🔹 Dois Métodos de Autenticação

1. API Key (Para operações GET - Leitura)

A API Key pode ser enviada de 2 formas:

No header HTTP (Recomendado):

X-API-Key: carz_1234567890abcdef...

Na query string:

?api_key=carz_1234567890abcdef...

Quando usar:

  • Consultas públicas ou semi-públicas
  • Integrações simples de leitura
  • Dashboards e relatórios
  • Aplicações frontend

2. JWT (Para operações POST/PUT/DELETE - Escrita)

O token JWT deve ser enviado no header Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Quando usar:

  • Criar novos veículos
  • Atualizar informações
  • Deletar registros
  • Upload de imagens
  • Qualquer operação que modifique dados

Estrutura do token JWT:

{
  "header": {
    "typ": "JWT",
    "alg": "HS256"
  },
  "payload": {
    "user_id": 1,
    "email": "admin@exemplo.com",
    "iat": 1640000000,
    "exp": 1640086400,
    "iss": "https://seusite.com"
  },
  "signature": "..."
}

Algoritmos suportados:

  • HS256 (SHA-256) - Padrão
  • HS384 (SHA-384)
  • HS512 (SHA-512)

⚡ Recomendações de Segurança

Essenciais:

  • ✅ Use HTTPS em produção (obrigatório)
  • ✅ Configure um JWT_SECRET forte (mínimo 32 caracteres)
  • ✅ NUNCA exponha seu JWT_SECRET ou API Key no código frontend
  • ✅ Gere tokens JWT com validade limitada (máximo 24h recomendado)
  • ✅ Armazene tokens de forma segura (nunca em localStorage se possível)

Recomendadas:

  • ✅ Regenere a API Key periodicamente (a cada 3-6 meses)
  • ✅ Use variáveis de ambiente para armazenar chaves
  • ✅ Implemente rate limiting para evitar abuso
  • ✅ Habilite autenticação API Key mesmo para GET se os dados forem sensíveis
  • ✅ Prefira autenticação por header em vez de query string
  • ✅ Monitore logs de acesso à API
  • ✅ Use CORS configurado corretamente

Avançadas:

  • ✅ Implemente refresh tokens para renovação automática
  • ✅ Adicione IP whitelisting para endpoints críticos
  • ✅ Use webhook signatures para validar origem de requisições
  • ✅ Implemente two-factor authentication para geração de tokens
  • ✅ Configure WAF (Web Application Firewall)

🔒 Exemplo de Configuração Segura

wp-config.php:

// JWT Secret (usar valor forte e único)
define('JWT_SECRET', 'K8mN2pQ5rS9tV3wX6zA4bC7dE0fG1hJ4kL8mN2pQ5rS9tV3');

// Opcional: Tempo de expiração do token (em segundos)
define('JWT_EXPIRATION', 86400); // 24 horas

// Opcional: CORS permitido
define('CARZ_API_CORS_ORIGIN', 'https://seuapp.com');

Gerenciamento de Tokens:

// ❌ ERRADO - Nunca faça isso
const JWT_SECRET = 'meu-segredo'; // Exposto no frontend!

// ✅ CORRETO - Token gerado no backend e enviado ao frontend
// Backend gera o token
const token = generateJWT(userData, JWT_SECRET);
// Frontend apenas usa o token
fetch(url, { headers: { 'Authorization': `Bearer ${token}` } });

🐛 Troubleshooting

❌ Endpoint retorna 404

Soluções:

  1. Salve as configurações novamente em Configurações > Paradigma API
  2. Clique em "Atualizar Permalinks"
  3. Verifique se não há conflito com outras regras de rewrite
  4. Teste o endpoint padrão do WordPress: /wp-json/carz-api/v1/vehicles
  5. Desative e reative o plugin
  6. Vá em Configurações > Permalinks e clique em "Salvar"

❌ API retorna erro 401 - "Token ausente"

Problema: Header de autorização não está sendo enviado corretamente.

Soluções:

  1. Verifique se o header está no formato correto: Authorization: Bearer {token}
  2. Certifique-se de que há um espaço após "Bearer"
  3. Verifique se o servidor não está removendo o header Authorization (comum em alguns servidores Apache)
  4. Adicione ao .htaccess (se Apache):
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

❌ API retorna erro 401 - "Token JWT inválido"

Problema: Token expirado, inválido ou gerado com secret diferente.

Soluções:

  1. Verifique se o token não expirou (campo exp no payload)
  2. Confirme que está usando o mesmo JWT_SECRET do wp-config.php
  3. Gere um novo token
  4. Verifique se o algoritmo é suportado (HS256, HS384, HS512)
  5. Use jwt.io para decodificar e validar o token

❌ API retorna erro 500 - "JWT_SECRET não configurado"

Problema: Variável JWT_SECRET não foi definida no wp-config.php.

Soluções:

  1. Abra o arquivo wp-config.php na raiz do WordPress
  2. Adicione: define('JWT_SECRET', 'sua-chave-forte-aqui');
  3. Certifique-se de que a linha está antes de /* That's all, stop editing! */
  4. Salve o arquivo e teste novamente

❌ API retorna erro 401 - "API Key inválida"

Problema: API Key incorreta ou não foi enviada.

Soluções:

  1. Verifique se a autenticação está habilitada em Configurações > Paradigma API
  2. Confirme se a API Key está correta
  3. Teste com o header X-API-Key em vez de query string
  4. Gere uma nova API Key através do painel admin
  5. Se não quiser autenticação para GET, desmarque "Requer Autenticação"

❌ Não aparecem todos os veículos

Soluções:

  1. Verifique se os posts estão com status "publish"
  2. Confirme se o CPT cpt_cars está registrado
  3. Teste acessando o endpoint diretamente no navegador
  4. Verifique se não há filtros personalizados interferindo
  5. Desative outros plugins temporariamente para testar conflitos

❌ Erro "TRX Addons não encontrado"

Soluções:

  1. Instale e ative o TRX Addons
  2. Verifique se o Custom Post Type de Carros está habilitado no TRX Addons
  3. Acesse TRX Addons > Settings e ative o CPT "Cars"

❌ POST/PUT não funciona, mas GET funciona

Problema: Autenticação JWT não configurada ou token ausente.

Soluções:

  1. Configure o JWT_SECRET no wp-config.php
  2. Gere um token JWT válido
  3. Inclua o token no header: Authorization: Bearer {token}
  4. Verifique se o método HTTP está correto (POST, PUT, DELETE)
  5. Confirme que o Content-Type é application/json

❌ Erro CORS ao fazer requisição do navegador

Problema: Cross-Origin Resource Sharing bloqueando a requisição.

Soluções:

  1. Verifique se está usando HTTPS
  2. O plugin já habilita CORS por padrão
  3. Se necessário, adicione ao functions.php do tema:
add_filter('rest_pre_serve_request', function($served, $result, $request) {
    header('Access-Control-Allow-Origin: *');
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
    header('Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key');
    return $served;
}, 10, 3);

❌ Upload de imagem retorna erro

Soluções:

  1. Verifique permissões da pasta /wp-content/uploads/
  2. Confirme que o token JWT está válido
  3. Verifique o tamanho máximo de upload no PHP (upload_max_filesize)
  4. Use multipart/form-data no Content-Type para upload
  5. Confira se a imagem está no formato suportado (jpg, png, gif, webp)

❌ Resposta JSON vem sem formatação (compacta)

Problema: Por padrão, a API retorna JSON compacto para melhor performance.

Solução:

  • Adicione ?pretty na URL para formatação legível:
/wp-json/carz-api/v1/vehicles?pretty

🔧 Debug Avançado

Habilitar logs de erro do WordPress:

  1. Edite wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
  1. Verifique logs em: /wp-content/debug.log

Testar endpoints via cURL:

# GET com API Key
curl -H "X-API-Key: carz_abc123..." \
  https://seusite.com/wp-json/carz-api/v1/vehicles

# POST com JWT
curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Teste","price":"100000"}' \
  https://seusite.com/wp-json/carz-api/v1/vehicles

Verificar se JWT_SECRET está configurado:

// Executar em arquivo PHP temporário
<?php
require_once('wp-load.php');
echo defined('JWT_SECRET') ? 'JWT_SECRET está definido' : 'JWT_SECRET NÃO está definido';
?>

📝 Changelog

2.0.0 (Atual - Dezembro 2024)

  • ✨ [BREAKING] Reescrita completa do plugin com foco em API REST moderna
  • ✨ [NOVO] Suporte completo a métodos HTTP: GET, POST, PUT, DELETE
  • ✨ [NOVO] Autenticação JWT para operações de escrita (POST/PUT/DELETE)
    • Implementação nativa sem dependências externas
    • Suporte a algoritmos HS256, HS384, HS512
    • Validação de expiração automática
  • ✨ [NOVO] Endpoints para CRUD completo de:
    • Veículos (vehicles)
    • Fabricantes (makers)
    • Modelos (models)
    • Recursos (features)
    • Tipos (types)
    • Status
    • Labels
    • Cidades (cities)
    • Agentes (agents)
    • Upload de mídia
  • ✨ [NOVO] Autenticação API Key mantida para operações GET (retrocompatível)
  • ✨ [NOVO] Gerador seguro de API Key (64 caracteres)
  • ✨ [NOVO] Endpoint personalizado configurável
  • ✨ [NOVO] CORS habilitado para requisições cross-origin
  • ✨ [NOVO] Pretty print opcional com ?pretty
  • ✨ [NOVO] Coluna de status na lista de carros
  • 🔧 [MELHORIA] Interface administrativa completamente reformulada
  • 🔧 [MELHORIA] Documentação expandida com exemplos JWT
  • 🔧 [MELHORIA] Tratamento de erros mais detalhado
  • 🔧 [MELHORIA] Validação de dados aprimorada
  • 📚 [DOCS] Guia completo de autenticação JWT
  • 📚 [DOCS] Exemplos de uso com múltiplas linguagens
  • 📚 [DOCS] Workflows n8n para operações CRUD

1.0.0 (Versão Inicial)

  • ✅ API REST básica para listagem de veículos via GET
  • ✅ Autenticação opcional com API Key
  • ✅ Sincronização com API externa (removida na v2.0.0)

📞 Suporte

Para suporte, abra uma issue no repositório ou entre em contato.

� Links Úteis

🎓 Recursos de Aprendizagem

Autenticação JWT

WordPress REST API

Segurança

📄 Licença

GPL v2 ou posterior.

🚗 Paradigma REST API - Desenvolvido para o tema Carz
Versão 2.0.0 | by UnkDev | paradigma.lat

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages