01Listado completo · 30 endpoints

02Mapa de interacciones · quién llama a quién

03Detalle expandible · estilo Swagger interactivo

02Convenciones del API

03Códigos de error estandarizados

04Authentication flow

1. POST /api/auth/login  → access_token (1h) + refresh_token (30d) cookies httpOnly
2. Cualquier request    → header Authorization: Bearer 
3. Token vencido         → 401 → POST /api/auth/refresh con cookie refresh_token
4. Refresh vencido       → re-login obligatorio
5. POST /api/auth/logout → limpia cookies httpOnly · invalida refresh_token en DB

05Anti-patrones reportados

06Versionado y breaking changes

• v1.0.0 actual · sin path versioning explícito
• v2.0.0 futuro: agregar /v1/ prefix antes de cualquier breaking change
• Anuncio breaking change: 90 días en Doc 41 Changelog + email a founders
• Endpoints deprecated: header Sunset: + log warning del cliente

07Performance esperada

08Detalle endpoints Suppliers (Doc 13 §08 · ADR-0003)

POST /api/suppliers

Crea un proveedor dropship. Soporta 4 auth modes: api_key · oauth · email_automated · whatsapp_business.

// Request
{
  "supplier_code": "proveedor-x",
  "display_name": "Proveedor X SpA",
  "rut": "76.123.456-7",
  "auth_mode": "api_key",
  "credentials": { "api_key": "..." },
  "contact_email": "ventas@proveedor.cl",
  "payment_terms": "7d post-venta · transferencia CLP"
}

// Response 201
{
  "id": "uuid",
  "supplier_code": "proveedor-x",
  "status": "active"
}

Validation Zod: supplier_code slug · auth_mode enum · credentials matches schema según auth_mode.

POST /api/suppliers/:id/sync-catalog

Dispara SupplierAdapter.syncCatalog() · upsert en mkt_supplier_products.

// Response 200
{
  "synced_count": 342,
  "new_count": 28,
  "updated_count": 314,
  "deactivated_count": 0,
  "duration_ms": 8432
}

POST /api/suppliers/:id/purchase-orders

Crea OC dropship (uso interno desde flujo orden) o manual desde dashboard.

// Request
{
  "items": [{ "supplier_sku": "SKU-X-001", "qty": 2 }],
  "ship_to": {
    "full_name": "Juan Pérez",
    "rut": "12.345.678-9",
    "street": "Av. Providencia 1234",
    "city": "Santiago",
    "region": "RM",
    "phone": "+56912345678"
  },
  "order_id": "uuid-orden-marketplace"  // opcional · NULL si manual
}

// Response 201
{
  "id": "uuid-po",
  "external_po_id": "PROV-X-99887",
  "status": "created",
  "total_clp": 45000,
  "expected_shipped_at": "2026-05-30T00:00:00Z"
}

POST /api/webhooks/supplier/:supplier_code

Recibe webhook de proveedor (HMAC firmado). Eventos: shipped · delivered · cancelled · stock_changed.

// Request (firma en header X-Supplier-Signature)
{
  "event_type": "shipped",
  "external_po_id": "PROV-X-99887",
  "tracking_number": "CHX-12345",
  "courier": "Chilexpress",
  "occurred_at": "2026-05-28T14:23:00Z"
}

// Response 200
{ "ok": true, "event_id": "uuid" }

09Detalle endpoints Ads (Doc 02 BBP P14)

POST /api/ads/accounts

Conecta cuenta publicitaria con OAuth. Tokens cifrados en Supabase Vault.

// Request
{
  "provider": "mercado_ads",   // o "meta" | "google_ads" | "tiktok"
  "oauth_code": "...",          // recibido del flow OAuth callback
  "display_name": "SMC SpA · Mercado Ads",
  "monthly_budget_clp": 500000
}

// Response 201
{
  "id": "uuid",
  "provider": "mercado_ads",
  "external_account_id": "MLA123456",
  "is_active": true
}

POST /api/ads/campaigns

Crea campaña en provider remoto + sincroniza row local.

// Request
{
  "account_id": "uuid",
  "name": "Black Friday 2026",
  "product_ids": ["uuid-sku-1", "uuid-sku-2"],
  "budget_clp": 100000,
  "start_date": "2026-11-25",
  "end_date": "2026-11-30"
}

// Response 201
{
  "id": "uuid",
  "external_campaign_id": "ADS-99887",
  "status": "active"
}

GET /api/ads/metrics

Time series spend/clicks/conv/roas. Filtro por campaign_id · date_range.

GET /api/ads/metrics?campaign_id=uuid&date_from=2026-05-01&date_to=2026-05-27

// Response 200
{
  "campaign_id": "uuid",
  "rows": [
    { "date": "2026-05-27", "impressions": 4523, "clicks": 89, "conversions": 7, "spend_clp": 12000, "revenue_clp": 84000, "roas": 7.0 }
  ],
  "summary": {
    "total_spend": 240000,
    "total_revenue": 1820000,
    "average_roas": 7.58,
    "alerts": []
  }
}

Si ROAS <1.5 últimos 7 días · summary.alerts incluye { "type": "low_roas", "suggestion": "pausar o cambiar creatividad" }.

POST /api/ads/events

Envía conversion event server-side (Meta CAPI · Google Enhanced Conversions · TikTok Events). Hashed PII según provider spec.

// Request
{
  "provider": "meta_capi",
  "event_type": "purchase",
  "event_id": "uuid-order-1",   // idempotency
  "user_data": {
    "em": "sha256-hash-email",
    "ph": "sha256-hash-phone"
  },
  "custom_data": {
    "value": 45000,
    "currency": "CLP",
    "content_ids": ["sku-1"]
  }
}

// Response 200
{ "ok": true, "queued_for_provider": true }

Cron /api/cron/ads-events-batch (5min) envía batch pendientes a cada provider.