API Trocaar

API REST somente leitura para conectar outras plataformas aos dados da Trocaar.

Introdução

Todas as respostas são JSON em UTF-8. Valores monetários em reais (BRL), datas em ISO 8601 (UTC). CORS liberado para chamadas de qualquer origem.

URL base:

https://trocaar.com.br/api/public/v1

Autenticação

Gere uma chave em Área administrativa → API. A chave aparece uma única vez; guarde-a em local seguro e nunca a exponha em sites ou apps públicos. Envie em um dos cabeçalhos:

Authorization: Bearer trc_live_xxxxxxxxxxxxxxxx
# ou
X-API-Key: trc_live_xxxxxxxxxxxxxxxx
curl -H "Authorization: Bearer $TROCAAR_API_KEY" \
  "https://trocaar.com.br/api/public/v1/trades?status=completed&limit=20"
const res = await fetch("https://trocaar.com.br/api/public/v1/products?status=active", {
  headers: { Authorization: `Bearer ${process.env.TROCAAR_API_KEY}` },
});
const { data, pagination } = await res.json();

Paginação

Listas aceitam limit (1–200, padrão 50) e offset. A resposta traz pagination.total para calcular as páginas.

Erros

401 unauthorizedChave ausente, inválida ou revogada
500 query_failedFalha interna ao consultar os dados
{ "error": "unauthorized", "message": "Chave de API ausente ou inválida." }

GET/stats

Indicadores gerais da operação: usuários, verificações pendentes, anúncios, trocas e disputas.

Exemplo de resposta

{
  "data": {
    "users": { "total": 1280, "verified": 940, "pending_verification": 12 },
    "products": { "active": 310, "pending_moderation": 8 },
    "trades": { "in_progress": 45, "completed": 702 },
    "disputes": { "open": 3 },
    "generated_at": "2026-10-01T18:00:00.000Z"
  }
}

GET/products

Lista de anúncios com categoria e fotos.

statuspending | active | traded | rejected | removed
category_idUUID da categoria (Carros, Motos, Smartphones)
limit / offsetPaginação (padrão 50, máximo 200)

Exemplo de resposta

{
  "data": [{
    "id": "8f1c…", "title": "Honda CG 160 2022", "condition": "good",
    "reference_value": 14500, "city": "São Paulo", "state": "SP",
    "status": "active", "categories": { "name": "Motos" },
    "product_photos": [{ "url": "…", "position": 0 }],
    "created_at": "2026-09-20T12:00:00Z"
  }],
  "pagination": { "limit": 50, "offset": 0, "total": 310 }
}

GET/trades

Negociações com status, método de conclusão e complemento (dinheiro ou créditos).

statusproposed | countered | accepted | awaiting_completion | in_dispute | completed | cancelled | rejected
updated_sinceData ISO 8601 — retorna apenas negociações alteradas depois dela (sincronização incremental)
limit / offsetPaginação (padrão 50, máximo 200)

Exemplo de resposta

{
  "data": [{
    "id": "c21a…", "status": "awaiting_completion", "method": "in_person",
    "complement_method": "cash", "cash_complement": 500, "credit_complement": 0,
    "offered_product_id": "…", "requested_product_id": "…",
    "updated_at": "2026-10-01T15:12:00Z"
  }],
  "pagination": { "limit": 50, "offset": 0, "total": 45 }
}

GET/users

Usuários com reputação, nível e situação de verificação. CPF, documentos e selfies nunca são retornados.

verification_statusunverified | pending | verified | rejected
limit / offsetPaginação (padrão 50, máximo 200)

Exemplo de resposta

{
  "data": [{
    "id": "5b0e…", "display_name": "Marina", "city": "Curitiba", "state": "PR",
    "verification_status": "verified", "rating_avg": 4.9, "trades_count": 14,
    "account_level": 2, "is_blocked": false
  }],
  "pagination": { "limit": 50, "offset": 0, "total": 1280 }
}