Documentação da API

API REST para pesquisa de stock de peças automóvel — greenparts data

Quick Start

1. Registe-se e obtenha uma chave de API:

POST https://api.greenparts.ai/data/auth/register-user

2. Crie uma API Key no dashboard ou use o Bearer Token:

POST https://api.greenparts.ai/api-keys

3. Pesquise stock:

curl -X POST https://api.greenparts.ai/data/search \

-H "X-API-Key: gp_sua_chave" \

-H "Content-Type: application/json" \

-d '{"reference":"1K0615301M"}'

Créditos: Cada pesquisa com resultados consome 1 crédito. Pesquisas sem resultados = 0 créditos. Recebe 10 créditos grátis ao registar-se.

Autenticação

A API aceita dois métodos de autenticação:

API Key (recomendado)

Header: X-API-Key: gp_xxxxx

Ideal para integração server-to-server.

Bearer Token

Header: Authorization: Bearer token

Obtido via login. Expira em 30 dias.

Parâmetros de Pesquisa

Campo	Tipo	Descrição
reference	string	OEM, aftermarket or generic reference. Also searches in associated references.
vehicle_make	string	Vehicle brand (e.g.: BMW, Volkswagen).
vehicle_model	string	Vehicle model (e.g.: Golf, Serie 3).
part_id	int	Part ID in the greenparts data catalog.
text	string	Free text search on title and description (FULLTEXT).
condition	string	Filter by condition: novo, usado_bom, usado_aceitavel, recondicionado, para_pecas.
is_oem	bool	Filter OEM parts only.
is_aftermarket	bool	Filter aftermarket parts only.
country	string	Filter by seller country (ISO 3166, e.g.: PT, ES, DE).
price_min	float	Minimum price (EUR).
price_max	float	Maximum price (EUR).
page	int	Results page (default: 1). Page 1 costs 1 credit.
per_page	int	Results per page (default: 20, max: 100).
search_token	string	Token from first search. Send to paginate without spending credits (valid 10 min).

Pelo menos um dos campos referencia, marca_veiculo, parte_id ou texto é obrigatório.

Paginação grátis com search_token

A primeira pesquisa com resultados custa 1 crédito e retorna um search_token.
Enviar o search_token nas páginas seguintes (page=2,3,…) permite paginar sem gastar créditos.
O token expira após 10 minutos.
Token armazenado em memória no servidor (cleanup automático a cada 5 min).
Pesquisas sem resultados não consomem créditos e não geram token.

# 1ª página — custa 1 crédito, recebe search_token

curl -X POST https://api.greenparts.ai/data/search \

-H "X-API-Key: gp_xxx" \

-d '{"reference":"1K0615301M"}'

# 2ª página — usa o token, custa 0 créditos

curl -X POST https://api.greenparts.ai/data/search \

-H "X-API-Key: gp_xxx" \

-d '{"reference":"1K0615301M","page":2,"search_token":"a1b2c3..."}'

Resposta da Pesquisa

A resposta inclui:

results — Array of items with references, prices, condition, location, seller data
stats — price_min/max/avg, total_results, total_sellers, by_condition breakdown
credits_spent — 0 if no results, 1 on first page with results, 0 on paginated pages
search_token — Send this in subsequent requests to paginate for free (valid 10 minutes)
total_pages — For pagination

{
  "success": true,
  "credits_spent": 1,
  "search_token": "a1b2c3d4e5f6...",
  "total": 42,
  "page": 1,
  "total_pages": 3,
  "stats": {
    "price_min": 15,
    "price_max": 250,
    "price_avg": 78.5,
    "total_sellers": 8
  },
  "results": [
    {
      "id": 1234,
      "referencia_oem": "1K0615301M",
      "titulo": "Disco Travão Frente",
      "condicao": "usado_bom",
      "preco": 35,
      "moeda": "EUR",
      "vendor_nome": "Auto Peças Lda",
      "location_country_code": "PT"
    }
  ]
}

Pesquisa

POST

/data/search

Search stock by reference, vehicle or free text. Costs 1 credit if results found. Returns search_token for free pagination.

Auth: API Key ou Bearer Token

{ "reference": "1K0615301M" }

POST

/data/search/stats

Price statistics for a reference. Costs 1 credit if results found.

Auth: API Key ou Bearer Token

{ "reference": "1K0615301M" }

Catálogos

GET

/data/catalog/parts?q=filtro&lang=pt

Pesquisar catálogo de peças (~1.656 peças, 6 idiomas).

GET

/data/catalog/brands

Marcas de veículos disponíveis no stock.

GET

/data/catalog/models/:brand

Modelos por marca.

GET

/data/catalog/variants/:model

Variantes por modelo.

GET

/data/catalog/vehicle-makes

Catálogo completo de marcas (1.119 marcas).

GET

/data/catalog/vehicle-models/:makeId

Modelos por marca (20.524 modelos).

GET

/data/catalog/vehicle-variants/:modelId

Variantes por modelo (105K+ variantes com specs técnicas).

GET

/data/catalog/vehicle-engines/:variantId

Motores por variante.

GET

/data/catalog/types

Tipos de peça.

GET

/data/catalog/groups

Grupos de peça.

GET

/data/catalog/locations

Localizações de peça.

GET

/data/catalog/sides

Lados de peça.

GET

/data/catalog/conditions

Condições de stock (Usado, Novo, Recondicionado, etc.).

GET

/data/catalog/quality

Níveis de qualidade.

GET

/data/catalog/packaging

Tipos de embalagem.

GET

/data/catalog/labelling

Tipos de etiquetagem.

GET

/data/catalog/fuels

Tipos de combustível.

GET

/data/catalog/countries

Países (ISO 3166, 6 idiomas).

GET

/data/catalog/languages

Idiomas suportados.

Créditos

GET

/data/credits/balance

Saldo de créditos de pesquisa.

Auth: Bearer Token

GET

/data/credits/packages

Pacotes de créditos disponíveis para compra.

POST

/data/credits/purchase

Comprar créditos (Stripe checkout).

Auth: Bearer Token

{ "package_id": 3, "payment_method": "stripe" }

GET

/data/credits/history

Histórico de pesquisas e consumo de créditos.

Auth: Bearer Token

Autenticação

POST

/auth/login

{ "email": "...", "password": "..." }

POST

/auth/register

Registar nova conta.

POST

/data/auth/register-user

Registar como utilizador API do greenparts data.

Rate Limits

Os limites de rate são configuráveis por API Key. Por defeito:

60 requests por minuto
1.000 requests por hora
Sem limite de spending diário (configurável no dashboard)

Códigos de Erro

Código	Descrição
400	Parâmetros inválidos ou em falta
401	Autenticação necessária ou inválida
403	Créditos insuficientes
404	Recurso não encontrado
429	Rate limit excedido
500	Erro interno do servidor

Base URL: https://api.greenparts.ai

Criar Conta API