Endpoints API

Backend: tcgcards-api corriendo en Cloud Run. Todos los endpoints REST. Prefix: /api/v1.

URL prod: https://tcgcards-api-1033181994095.us-central1.run.app

Autenticación

Hay 4 tipos de auth distintos según el endpoint:

Tipo	Cómo se envía	Quién la usa
none	—	Endpoints públicos (catálogo, feeds)
user JWT	Authorization: Bearer <jwt>	Login con Google → JWT propio firmado HS256
admin	user JWT + user.isAdmin === true	Solo admins del marketplace
admin token	X-Admin-Token: <token>	Endpoints de catálogo sync — usa ADMIN_TOKEN env var
internal auth	X-Internal-Auth: <secret>	Server-to-server (Next.js → API). Usa INTERNAL_AUTH_SECRET
internal cron	X-Internal-Cron-Secret: <secret>	Solo Cloud Scheduler. Usa INTERNAL_CRON_SECRET

Catálogo (público)

Método	Path	Auth	Descripción
GET	/api/v1/health	none	Healthcheck (devuelve status de conexión Mongo)
GET	/api/v1/tcgs	none	Lista TCGs habilitados
GET	/api/v1/tcgs/:slug	none	TCG específico
GET	/api/v1/tcgs/:slug/rarities	none	Rarezas disponibles
GET	/api/v1/sets	none	Lista paginada ?tcg=
GET	/api/v1/sets/:id	none	Set específico
GET	/api/v1/cards	none	Busca/filtra cards con facetas
GET	/api/v1/cards/suggest	none	Autocomplete
GET	/api/v1/cards/:id	none	Card específica
GET	/api/v1/cards/:id/listings	none	Listings activos de esa card
GET	/api/v1/cards/:id/recent-sales	none	Últimas 5 ventas
GET	/api/v1/sitemap/cards	none	Cards para sitemap XML
GET	/api/v1/sitemap/users	none	Usernames públicos para sitemap

Listings (catálogo de mercado)

Método	Path	Auth	Descripción
GET	/api/v1/listings	none	Búsqueda general (admin-grade)
GET	/api/v1/listings/cards	none	Feed público de listings tipo card
GET	/api/v1/listings/cards/facets	none	Facetas
GET	/api/v1/listings/bulk	none	Feed público de challa
GET	/api/v1/listings/bulk/facets	none	Facetas challa
GET	/api/v1/listings/sealed	none	Feed público de sellado
GET	/api/v1/listings/sealed/facets	none	Facetas sellado
GET	/api/v1/accessories	none	Feed de accesorios
GET	/api/v1/accessories/facets	none	Facetas accesorios
GET	/api/v1/listings/custom	none	Custom listings (legacy)
GET	/api/v1/listings/:id/public	none	Listing público
GET	/api/v1/listings/:id	none	Listing detallado
POST	/api/v1/listings	user JWT + active	Crea listing
PATCH	/api/v1/listings/:id	user JWT + active	Actualiza listing propio
DELETE	/api/v1/listings/:id	user JWT	Elimina listing propio
GET	/api/v1/users/me/listings	user JWT	Mis listings con filtros
GET	/api/v1/users/me/listings/facets	user JWT	Facetas de mis listings
POST	/api/v1/users/me/listings/bulk	user JWT	Acción bulk: pause/activate/mark_sold/delete
GET	/api/v1/users/:username/listings	none	Listings públicos de un seller
GET	/api/v1/users/:username/listings/facets	none	Facetas del seller

Carrito

Método	Path	Auth	Descripción
GET	/api/v1/me/cart	user JWT	Mi carrito enriquecido
POST	/api/v1/me/cart/items	user JWT + active	Agrega item
PATCH	/api/v1/me/cart/items/:listingId	user JWT + active	Actualiza cantidad (0 = elimina)
DELETE	/api/v1/me/cart/items/:listingId	user JWT + active	Elimina item
DELETE	/api/v1/me/cart	user JWT + active	Vacía carrito

Órdenes

Método	Path	Auth	Descripción
POST	/api/v1/orders/checkout	user JWT + active	Crea orden + MP preference
GET	/api/v1/orders/:id	user JWT	Detalle (buyer o seller)
POST	/api/v1/orders/:id/resume-payment	user JWT + active	Reanuda pago si quedó en awaiting_payment
PATCH	/api/v1/orders/:id/accept	user JWT (seller)	Acepta
PATCH	/api/v1/orders/:id/ship	user JWT (seller)	Marca como enviado
PATCH	/api/v1/orders/:id/complete	user JWT (buyer)	Confirma recepción
PATCH	/api/v1/orders/:id/cancel	user JWT	Cancela
GET	/api/v1/orders/:id/whatsapp	user JWT	Devuelve WhatsApp de la contraparte si activó esa preferencia
GET	/api/v1/me/orders/buyer	user JWT	Mis compras
GET	/api/v1/me/orders/seller	user JWT	Mis ventas

Chat

Método	Path	Auth	Descripción
GET	/api/v1/me/unread-count	user JWT	# de chats sin leer
GET	/api/v1/me/conversations	user JWT	Mis conversaciones recientes
GET	/api/v1/conversations/:orderId/messages	user JWT	Mensajes de la orden
POST	/api/v1/conversations/:orderId/messages	user JWT	Envía mensaje (rate-limited)

Reviews

Método	Path	Auth	Descripción
POST	/api/v1/orders/:orderId/review	user JWT	Deja review (después de completar)
GET	/api/v1/orders/:orderId/review	user JWT	Mi review en esa orden
GET	/api/v1/users/:username/reviews	none	Reviews recibidas por un seller

Disputes

Método	Path	Auth	Descripción
POST	/api/v1/orders/:id/dispute	user JWT	Abre dispute (buyer o seller)
GET	/api/v1/orders/:id/dispute	user JWT	Detalle dispute
POST	/api/v1/orders/:id/dispute/response	user JWT	Responde dispute (la otra parte)
GET	/api/v1/admin/disputes	admin	Cola de disputes
GET	/api/v1/admin/disputes/:id	admin	Detalle admin
POST	/api/v1/admin/disputes/:id/resolve	admin	Resuelve (outcome + adminNote)

Reports (moderación)

Método	Path	Auth	Descripción
POST	/api/v1/reports	user JWT	Reporta listing o user
GET	/api/v1/admin/reports	admin	Lista agrupada
GET	/api/v1/admin/reports/:id	admin	Detalle

Uploads

Método	Path	Auth	Descripción
POST	/api/v1/uploads/sign	user JWT	Firma URL para subir a Cloudinary. kind: listing / proof / avatar / dispute / banner / dispute_response

Banners (homepage)

Método	Path	Auth	Descripción
GET	/api/v1/banners	none	Banners activos
GET	/api/v1/admin/banners	admin	Todos (admin)
GET	/api/v1/admin/banners/:id	admin	Detalle
POST	/api/v1/admin/banners	admin	Crea
PATCH	/api/v1/admin/banners/:id	admin	Actualiza
POST	/api/v1/admin/banners/reorder	admin	Reordena
POST	/api/v1/admin/banners/:id/publish	admin	Publica
POST	/api/v1/admin/banners/:id/unpublish	admin	Despublica
POST	/api/v1/admin/banners/:id/archive	admin	Archiva
POST	/api/v1/admin/banners/:id/restore	admin	Restaura

Wallet

Método	Path	Auth	Descripción
GET	/api/v1/me/wallet	user JWT	Mi balance
GET	/api/v1/me/wallet/entries	user JWT	Mi ledger
GET	/api/v1/admin/wallet-system	admin	Balance + últimas 50 del system wallet
POST	/api/v1/admin/wallet-system/owner-draw	admin	Owner extrae fondos del system wallet
GET	/api/v1/admin/users/:userId/wallet	admin	Wallet de un user (auditado)
POST	/api/v1/admin/users/:userId/wallet/credit	admin	Acredita
POST	/api/v1/admin/users/:userId/wallet/debit	admin	Debita
POST	/api/v1/admin/reconcile	admin	Reconciliación manual

Cuentas bancarias

Método	Path	Auth	Descripción
GET	/api/v1/me/bank-account	user JWT	Mi cuenta (encrypted)
PUT	/api/v1/me/bank-account	user JWT	Crea/actualiza
DELETE	/api/v1/me/bank-account	user JWT	Elimina
GET	/api/v1/admin/users/:userId/bank-account	admin	Decrypted (auditado)

Withdrawals

Método	Path	Auth	Descripción
POST	/api/v1/me/withdrawals	user JWT	Solicita retiro
GET	/api/v1/me/withdrawals	user JWT	Mis retiros
GET	/api/v1/admin/withdrawals	admin	Lista cola
GET	/api/v1/admin/withdrawals/:id	admin	Detalle
POST	/api/v1/admin/withdrawals/:id/complete	admin	Marca como pagado
POST	/api/v1/admin/withdrawals/:id/cancel	admin	Cancela

Webhook MP

Método	Path	Auth	Descripción
POST	/api/v1/webhooks/mp	MP signature	Webhook de Mercado Pago. Maneja approvals/rejects/late refunds

Admin — moderation

Método	Path	Auth	Descripción
POST	/api/v1/admin/moderation/hide-listing	admin	Oculta listing
POST	/api/v1/admin/moderation/unhide-listing	admin	Restaura listing
POST	/api/v1/admin/moderation/warn-user	admin	Advierte user
POST	/api/v1/admin/moderation/suspend-user	admin	Suspende (7/30/90/null días)
POST	/api/v1/admin/moderation/unsuspend-user	admin	Levanta suspensión
POST	/api/v1/admin/moderation/ban-user	admin	Banea permanente
POST	/api/v1/admin/moderation/unban-user	admin	Desbanea
POST	/api/v1/admin/moderation/dismiss-report	admin	Desestima 1 report
POST	/api/v1/admin/moderation/dismiss-target-reports	admin	Desestima todos los reports de un target

Admin — overview + orders + users

Método	Path	Auth	Descripción
GET	/api/v1/admin/overview	admin	Dashboard overview
GET	/api/v1/admin/orders	admin	Búsqueda de órdenes
GET	/api/v1/admin/orders/:id	admin	Detalle
GET	/api/v1/admin/users	admin	Cola moderation
GET	/api/v1/admin/users/:username/moderation	admin	Info moderation

Admin — catálogo (sync)

Estos endpoints son para sincronización del catálogo desde TCGplayer. Usan X-Admin-Token.

Método	Path	Auth	Descripción
GET	/api/v1/admin/stats	admin token	Stats por TCG
POST	/api/v1/admin/sync/:tcg	admin token	Dispara sync (fire-and-forget)

Usuarios

Método	Path	Auth	Descripción
POST	/api/v1/users/upsert	internal auth	Crea/actualiza user desde Next.js auth bridge
GET	/api/v1/users/me	user JWT	Mi perfil
PATCH	/api/v1/users/me	user JWT	Edita perfil
GET	/api/v1/users/by-id/:id	none	Perfil público por id
GET	/api/v1/users/:username	none	Perfil público por username
POST	/api/v1/users/me/acknowledge-warning	user JWT	Reconoce advertencia
GET	/api/v1/users/me/can-delete	user JWT	Verifica si puede eliminar cuenta
DELETE	/api/v1/users/me	user JWT	Elimina cuenta (soft delete)

Internal cron

Método	Path	Auth	Descripción
POST	/api/v1/internal/cron/orders-tick	cron secret	Tick de órdenes (auto-cancel / auto-complete)
POST	/api/v1/internal/cron/orders-awaiting-payment-cleanup	cron secret	Cancela órdenes con timeout
POST	/api/v1/internal/cron/wallet-reconcile	cron secret	Reconcilia wallet
POST	/api/v1/internal/cron/refunds-reconcile	cron secret	Reconcilia refunds

Notas técnicas

• Rate limits globales: 600 req/min. Endpoints con limiter propio: uploads, listings POST, chat, reviews.
• Amounts: siempre CLP centavos (integer). Nunca pesos. Mostrarse con formatPriceCents().
• Paginación:
  • ?page=N (offset-based) para queries simples.
  • ?cursor=<iso> o ?offset=<iso> (cursor-based) para feeds grandes.
• Timestamps: ISO 8601 UTC.
• Phone format: 569XXXXXXXX (E.164 Chile, privado).