06 - FE Integration Contracts

Dokumen kontrak minimal FE terhadap API runtime saat ini.

FE Runtime Topology

Base Contract

Base path: /api/v1

Locale:

header Accept-Language: id|en

atau query ?lang=id|en

Response Envelope

Semua endpoint JSON mengikuti envelope dari ApiResponse:

success: boolean

code: string

message: string

request_id: string

timestamp: string

api_version: string

data: any (opsional)

meta: object (opsional)

errors: object|array (khusus error validasi)

Referensi:

app/Http/Responses/ApiResponse.php

app/Traits/HasApiResponse.php

Auth Headers

Authorization: Bearer <access_token>

X-Tenant-ID: <uuid> (opsional; wajib match tenant dalam token jika dikirim)

Token Ability Expectations

Central runtime auth: tenant:access atau platform:access

Tenant route: token tenant-scoped + valid tenant context

FE Auth Lifecycle (Recommended)

Critical Endpoints For FE

Auth

POST /auth/login

POST /auth/refresh

POST /auth/select-tenant

GET /auth/me

POST /auth/logout

Catatan kontrak tenant selection:

Pada response multi-tenant (data.tenants[]), FE dapat memakai pivot.membership_type dan pivot.last_login_at untuk label peran serta informasi "terakhir login" per tenant.

User Runtime

/user/security/*

/user/sessions*

/user/notifications*

Tenant Runtime

/tenant/billing/*

/tenant/integrations/*

/tenant/master-data/taxonomies*

`GET /auth/me` FE Shape

FE dapat mengandalkan:

current_tenant.id|name|slug (nullable)

authz.roles[]

authz.permissions[]

Contoh:

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "id": "...",
    "name": "Super Admin",
    "account": { "type": "platform_admin" },
    "current_tenant": { "id": "...", "name": "Garment Indonesia", "slug": "garment-indonesia" },
    "authz": {
      "roles": ["owner", "ppic"],
      "permissions": ["po.create", "po.approve", "mr.read"]
    }
  }
}

Error Handling Contract

401: unauthenticated / token invalid / session expired

403: ability/context mismatch (tenant token required, step-up missing, forbidden)

422: validation/business rule

429: throttled

FE wajib handle code dari response, bukan hanya HTTP status.

FE Error Strategy (Practical)

401: clear access token, trigger refresh flow.

401 setelah refresh gagal: logout lokal + redirect login.

403: tampilkan forbidden/feature-denied sesuai code.

422: tampilkan field-level validation dari errors.

gunakan request_id untuk issue tracing ke BE logs.

06 - FE Integration Contracts

FE Runtime Topology#

Base Contract#

Response Envelope#

Auth Headers#

Token Ability Expectations#

FE Auth Lifecycle (Recommended)#

Critical Endpoints For FE#

Auth#

User Runtime#

Tenant Runtime#

GET /auth/me FE Shape#

Error Handling Contract#

FE Error Strategy (Practical)#