Qué necesita la API para que una aplicación pueda operar

┌─────────────────────────────────────────────────────────────────────────┐
│  ┌────┐   OrderPilot  [ACTIVA]                        ┌──────────────┐  │
│  │logo│   Conectada el 6 de agosto · qué hace         │ Desconectar  │  │
│  └────┘   ( Ver pedidos )( Cambiar estados )( … )     └──────────────┘  │
│           ● Webhook activo · último evento hace 2 min · 1.284 hoy       │
└─────────────────────────────────────────────────────────────────────────┘
        48px      contenido flexible                        botón
   └── grid de 3 columnas: logo · cuerpo · acción ──┘

/* Tres columnas y ya está: el logo fijo, el cuerpo elástico, el botón a la derecha */
.app-card{
  display:grid; grid-template-columns:48px 1fr auto; gap:16px;
  align-items:start; padding:18px;
  border:1px solid #E7EAEF; border-radius:10px; background:#fff;
}
.app-logo{ width:48px; height:48px; border-radius:12px; object-fit:cover; }

/* el estado, en verde y en mayúsculas pequeñas: se lee de un vistazo */
.badge--ok{
  font-size:10.5px; font-weight:750; letter-spacing:.06em; text-transform:uppercase;
  padding:2px 8px; border-radius:5px; background:#EAF6F0; color:#48A57C;
}

/* los permisos, como etiquetas: en lenguaje humano, nunca "orders:write" */
.chips{ display:flex; flex-wrap:wrap; gap:6px; margin-top:12px; }
.chip{
  font-size:11.5px; padding:3px 9px; border-radius:999px;
  background:#F4F6F9; color:#6B7684; border:1px solid #E7EAEF;
}

/* la salud del webhook: un punto de color dice más que un párrafo */
.health{ display:flex; align-items:center; gap:7px; margin-top:12px;
         font-size:12.5px; color:#6B7684; }
.dot{ width:7px; height:7px; border-radius:50%; }
.dot--ok { background:#48A57C; box-shadow:0 0 0 3px #48A57C22; }
.dot--bad{ background:#F05252; box-shadow:0 0 0 3px #F0525222; }

/* "Conectar otra aplicación": discontinuo, para que se lea como hueco y no como botón principal */
.btn--dashed{
  display:block; width:100%; margin-top:12px; padding:14px; text-align:center;
  border:1.5px dashed #D3D9E0; border-radius:10px;
  color:#6B7684; font-weight:600; text-decoration:none;
}
.btn--dashed:hover{ border-color:#F26522; color:#F26522; background:#FEF1EA; }

Route::post('/orders/{order}/status', [OrderApiController::class, 'updateStatus'])
     ->middleware(['auth.api', 'scope:orders:write']);

public function updateStatus(Request $r, Order $order)
{
    $datos = $r->validate([
        'status_id'       => ['required', 'integer', Rule::exists('statuses', 'id')],
        'reason_id'       => ['nullable', 'integer'],
        'postponed_date'  => ['nullable', 'date'],        // para APLAZAR
        'tag_ids'         => ['nullable', 'array'],       // etiquetas de estado
        'details'         => ['nullable', 'string', 'max:500'],
        'idempotency_key' => ['nullable', 'string', 'max:100'],
    ]);

    // 1) la misma clave no se aplica dos veces (evita duplicados si hay reintento)
    if ($clave = $datos['idempotency_key'] ?? null) {
        if ($previo = ApiIdempotency::where('key', $clave)->first()) {
            return response()->json($previo->response, $previo->status_code);
        }
    }

    // 2) transición permitida
    if (!$order->puedeTransicionarA($datos['status_id'])) {
        return response()->json(['ok' => 0, 'code' => 409,
            'error' => 'invalid_transition'], 409);
    }

    // 3) 🔴 LO MÁS IMPORTANTE DE TODO EL DOCUMENTO:
    //    si una validación falla, DECIR CUÁL. Hoy el panel responde 200 y no cambia
    //    nada, así que la integración reintenta a ciegas sin saber por qué.
    if ($fallo = $order->validarParaEstado($datos['status_id'])) {
        return response()->json(['ok' => 0, 'code' => 422,
            'error'   => 'validation_failed',
            'message' => $fallo->mensaje,   // "El teléfono debe tener al menos 10 dígitos"
            'field'   => $fallo->campo,     // "phone"
        ], 422);
    }

    // 4) aplicar + historial, con el mismo formato que escribe un asesor
    DB::transaction(function () use ($order, $datos, $r) {
        $anterior = $order->status_id;
        $order->update(array_filter([
            'status_id'      => $datos['status_id'],
            'postponed_date' => $datos['postponed_date'] ?? null,
        ]));
        if (!empty($datos['tag_ids'])) $order->statusTags()->sync($datos['tag_ids']);

        OrderStatusRecord::create([
            'order_id'          => $order->id,
            'old_status_id'     => $anterior,
            'current_status_id' => $datos['status_id'],
            'substatus_id'      => $datos['reason_id'] ?? null,
            'details'           => $datos['details'] ?? null,
            'created_by'        => $r->user()->id,
            'source'            => 'api',              // distingue humano de integración
            'app_id'            => $r->oauthClientId(),
        ]);
    });

    return response()->json(['ok' => 1, 'code' => 200,
        'order' => ['id' => $order->id, 'status_id' => $order->status_id]]);
}

// Las cuatro cosas que hoy hacemos posteando el formulario entero del panel.
// Todas ANTES del despacho; después, 409.
public function update(Request $r, Order $order)
{
    if ($order->fulfilled_at) {
        return response()->json(['ok' => 0, 'code' => 409,
            'error' => 'order_already_dispatched'], 409);
    }

    $datos = $r->validate([
        'address'            => ['nullable', 'string', 'max:120'],
        'address_2'          => ['nullable', 'string', 'max:120'],
        'city'               => ['nullable', 'string', 'max:80'],
        'province'           => ['nullable', 'string', 'max:80'],
        'zip'                => ['nullable', 'string', 'max:12'],
        // 🔴 el teléfono: validarlo POR PAÍS, no con un número fijo (ver punto 8)
        'phone'              => ['nullable', new TelefonoValido($order->country_code)],
        // el recargo del contra reembolso
        'total'              => ['nullable', 'numeric', 'min:0'],
        // elegir la agencia que mejor entrega en esa zona
        'shipping_method_id' => ['nullable', 'integer', Rule::exists('shipping_methods', 'id')],
        'carrier_observations' => ['nullable', 'string', 'max:255'],
    ]);

    $order->update(array_filter($datos, fn($v) => $v !== null));
    $order->registrarCambio($r->oauthClientId(), $datos);   // trazabilidad

    return response()->json(['ok' => 1, 'code' => 200, 'order' => new OrderResource($order)]);
}

public function index(Request $r)
{
    $q = Order::where('user_id', $r->user()->id);

    if ($s  = $r->query('status_id'))     $q->whereIn('status_id', explode(',', $s));
    if ($de = $r->query('from'))          $q->where('created_at', '>=', $de);
    if ($a  = $r->query('to'))            $q->where('created_at', '<=', $a);

    // el parámetro más útil: sincronizar sin repasarlo todo en cada pasada
    if ($d  = $r->query('updated_since')) $q->where('updated_at', '>', $d);

    $p = $q->orderBy('updated_at', 'desc')
           ->paginate(min((int) $r->query('per_page', 50), 100));

    return response()->json(['ok' => 1, 'code' => 200,
        'orders'     => OrderResource::collection($p->items()),
        'pagination' => ['page' => $p->currentPage(), 'per_page' => $p->perPage(),
                           'total' => $p->total(), 'total_pages' => $p->lastPage()]]);
}

// Los cuatro siguen el mismo patrón que `index()`: filtro del usuario, filtros opcionales,
// paginación y el mismo sobre de respuesta. Se ponen para que no falte ninguno.

public function carritosAbandonados(Request $r)     // GET /api/abandoned-carts
{
    $q = AbandonedCart::where('user_id', $r->user()->id);
    if ($d = $r->query('updated_since')) $q->where('updated_at', '>', $d);
    // el importe, DESGLOSADO (ver §8.2): products + shipping + cod_surcharge = total
    return $this->paginado($q, CartResource::class, $r);
}

public function incidencias(Request $r)                // GET /api/incidences
{
    $q = Incidence::with('order')->where('user_id', $r->user()->id);
    if ($s = $r->query('status')) $q->whereIn('status', explode(',', $s));
    // 🔴 con el MOTIVO LITERAL, no solo su id: es lo que permite decidir qué hacer
    return $this->paginado($q, IncidenceResource::class, $r);
}

public function gestionarIncidencia(Request $r, Incidence $inc)   // POST …/manage
{
    $d = $r->validate(['status' => ['required', 'integer'],
                        'comment' => ['nullable', 'string', 'max:500']]);
    $inc->update(['status' => $d['status']]);
    $inc->comentarios()->create(['texto' => $d['comment'] ?? null,
                                 'origin' => 'api', 'app_id' => $r->oauthClientId()]);
    return response()->json(['ok' => 1, 'code' => 200]);
}

public function productos(Request $r)                  // GET /api/products
{
    // 🔴 CON VARIANTES: el stock vive ahí, no en el producto padre
    $q = Product::with('variants:id,product_id,sku,stock,cost,weight');
    if ($s = $r->query('sku')) $q->whereHas('variants', fn($v) => $v->where('sku', $s));
    return $this->paginado($q, ProductResource::class, $r);
}

public function me(Request $r)                        // GET /api/me
{
    return response()->json(['ok' => 1, 'code' => 200,
        'user_id'           => $r->user()->id,
        'store_id'          => $r->user()->store_id,
        'country_code'      => $r->user()->country_code,
        'scopes'            => $r->scopes(),
        'token_expires_at'  => $r->token()->expires_at,
    ]);
}

// routes/web.php
Route::get ('/app/configuration/applications',        [AppsController::class, 'index']);
Route::delete('/app/configuration/applications/{app}', [AppsController::class, 'revoke']);

// AppsController.php
public function index()
{
    $apps = OauthAccessToken::with(['client', 'webhook'])
        ->where('user_id', auth()->id())
        ->where('revoked', false)
        ->get()
        ->map(fn($t) => [
            'id'        => $t->client->id,
            'nombre'    => $t->client->name,
            'logo'      => $t->client->logo_url,
            'conectada' => $t->created_at,
            'permisos'  => $t->scopesLegibles(),      // "Ver pedidos", no "orders:read"
            'webhook'   => [
                'activo'  => $t->webhook?->consecutive_failures === 0,
                'ultimo'  => $t->webhook?->last_success_at,
                'eventos' => $t->webhook?->events_today ?? 0,
            ],
        ]);

    return view('configuration.applications', compact('apps'));
}

public function revoke(OauthClient $app)
{
    DB::transaction(function () use ($app) {
        // 1) avisar ANTES de invalidar, para que la app pueda pararse sola
        $app->webhookDe(auth()->id())?->enviar('app.uninstalled', [
            'store_id' => auth()->user()->store_id,
        ]);
        // 2) invalidar tokens y borrar su webhook
        OauthAccessToken::where('client_id', $app->id)
            ->where('user_id', auth()->id())->update(['revoked' => true]);
        $app->webhookDe(auth()->id())?->delete();
    });

    return back()->with('ok', 'Aplicación desconectada');
}

<div class="apps">
  {{-- una tarjeta por aplicación conectada --}}
  @forelse ($apps as $app)
    <article class="app-card">
      <img class="app-logo" src="{{ $app['logo'] }}" alt="">

      <div class="app-body">
        <h3>{{ $app['nombre'] }}
          <span class="badge badge--ok">Activa</span>
        </h3>
        <p class="muted">Conectada el {{ $app['conectada']->isoFormat('D [de] MMMM [de] YYYY') }}</p>

        {{-- permisos en lenguaje humano, no scopes técnicos --}}
        <div class="chips">
          @foreach ($app['permisos'] as $p)
            <span class="chip">{{ $p }}</span>
          @endforeach
        </div>

        {{-- salud del webhook: que se vea de un vistazo si va o no --}}
        <p class="health">
          <i class="dot {{ $app['webhook']['activo'] ? 'dot--ok' : 'dot--bad' }}"></i>
          @if ($app['webhook']['activo'])
            Webhook activo · último evento {{ $app['webhook']['ultimo']->diffForHumans() }}
            · {{ number_format($app['webhook']['eventos'], 0, ',', '.') }} eventos hoy
          @else
            Webhook con fallos — la aplicación no está recibiendo avisos
          @endif
        </p>
      </div>

      <form method="POST" action="{{ route('apps.revoke', $app['id']) }}"
            onsubmit="return confirm('¿Desconectar {{ $app['nombre'] }}?')">
        @csrf @method('DELETE')
        <button class="btn btn--ghost">Desconectar</button>
      </form>
    </article>
  @empty
    <p class="muted">Todavía no tiene ninguna aplicación conectada.</p>
  @endforelse

  <a class="btn btn--dashed" href="{{ route('apps.directory') }}">+ Conectar otra aplicación</a>
</div>

// Sin firma, quien adivine la URL puede inyectar estados falsos.
public function send(Webhook $wh, string $event, array $payload): void
{
    $body = json_encode([
        'event'    => $event,
        'event_id' => (string) Str::ulid(),   // permite descartar duplicados
        'sent_at'  => now()->toIso8601String(),
        'data'     => $payload,
    ], JSON_UNESCAPED_UNICODE);

    $ts  = (string) now()->timestamp;
    $sig = hash_hmac('sha256', $ts . '.' . $body, $wh->secret);

    dispatch(new DeliverWebhookJob($wh->id, $body, $ts, $sig))->onQueue('webhooks');
}

// El job reintenta solo: 1 min · 5 min · 30 min · 2 h · 6 h
public $tries = 5;
public function backoff(): array { return [60, 300, 1800, 7200, 21600]; }

public function handle(): void
{
    $res = Http::timeout(10)->withHeaders([
            'X-Dropi-Signature' => 'sha256=' . $this->signature,
            'X-Dropi-Timestamp' => $this->timestamp,
            'X-Dropi-Event-Id'  => $this->eventId,
            'X-Dropi-Attempt'   => $this->attempts(),   // ¿es un reenvío?
        ])->withBody($this->body, 'application/json')->post($wh->url);

    if (!$res->successful()) {
        $wh->increment('consecutive_failures');   // a los 20 → pausar y avisar
        throw new \RuntimeException("webhook devolvió " . $res->status());
    }
    $wh->update(['consecutive_failures' => 0, 'last_success_at' => now()]);
}

$crudo = $request->getContent();          // el cuerpo CRUDO, sin decodificar
$ts    = $request->header('X-Dropi-Timestamp');

if (abs(time() - (int) $ts) > 300) abort(401);   // corta reenvíos

$esperada = hash_hmac('sha256', $ts . '.' . $crudo, $secreto);
if (!hash_equals($esperada, $recibida)) abort(401);  // tiempo constante

# La aplicación lo hace sola, justo después de autorizarse:
POST /api/webhooks
{
  "url":    "https://app.orderpilot.com/hooks/dropi",
  "events": ["order.created", "order.status_changed",
              "order.address_changed", "incidence.opened",
              "cart.abandoned", "app.uninstalled"]
}

# Dropi responde con el secreto de firma (se enseña UNA sola vez):
{ "ok": 1, "id": "wh_01J8FQ2K", "secret": "whsec_a3f9…" }

{
  "subtotal":      "…",     // los productos
  "shipping":      "…",     // el envío, si se cobra aparte
  "cod_surcharge": "…",     // el recargo del contra reembolso, si la tienda lo aplica
  "total":         "…",     // lo que el cliente acepta pagar al repartidor
  "currency":      "EUR"
}