GraphQL

Endpoint: POST /graphql (și playground UI autentificat în app)

Autentificare

Authorization: Bearer {token} — Sanctum
X-Company-Id — obligatoriu (middleware dedicat)

Playground

Utilizatori autentificați cu modul Outbound pot accesa /graphql/playground din aplicația web — explorer schema + query history.

Queries

Query	Descriere
articles	Listă articole paginată
stock	Niveluri stoc
stockConnection	Paginare Relay-style
salesOrders	Comenzi vânzare
purchaseOrders	Comenzi achiziție
receptions	Recepții
returns	Retururi
partners	Parteneri
warehouses	Depozite

Mutations

Mutation	Permisiune tipică
createArticle	create articles
updateArticle	edit articles
createSalesOrder	create sales_orders
updateSalesOrderStatus	edit sales_orders
createReception	create receptions

Exemplu query


query {
  stock(first: 10) {
    id
    quantity
    article { code name }
    warehouse { name }
  }
}

Limite

Limită	Valoare tipică
Complexitate max	120
Adâncime max	12
Rate limit	per companie (configurabil)

Depășire → eroare GraphQL cu mesaj explicit.

Tipuri

Obiecte: Article, Stock, SalesOrder, PurchaseOrder, Reception, ReturnOrder, Partner, Warehouse, StockConnection, PageInfo.

Input: SalesOrderItemInput, ReceptionItemInput.

Schema snapshot (teste interne): disponibilă echipei de dezvoltare — nu necesară integratorilor.

Când GraphQL vs REST

Criteriu	GraphQL	REST v1/v2
CRUD complet PO/REC	—	Da
Query compus (stoc + articol + depozit)	Da	3+ request-uri
Cache CDN / proxy	Mai greu	Da
OpenAPI / codegen	Parțial	Da
Batch volume mare stoc	stockConnection	v2 cursor

Exemplu mutation — comandă vânzare


mutation {
  createSalesOrder(input: {
    partnerId: 5
    warehouseId: 1
    externalRef: "ERP-001"
    lines: [{ articleCode: "SKU-001", quantity: 10 }]
  }) {
    id
    code
    status
  }
}

Exemplu query — comenzi recente


query {
  salesOrders(first: 20, status: "IN_LUCRU") {
    id
    code
    status
    partner { name }
    lines { quantity article { code name } }
  }
}

Erori GraphQL

Răspuns HTTP 200 cu errors[] în body — verificați message și extensions.code. Rate limit depășit → mesaj explicit în errors.