{ "openapi": "3.0.3", "info": { "title": "NAZ Partner Source API v1 / واجهات النظام المصدر", "version": "1.0.0", "description": "Mounted under the approved connection apiPath. All POST requests require raw-body HMAC. Source determines prices, taxes, fulfillment and upgrades." }, "servers": [ { "url": "https://source.example/naz/v1" } ], "components": { "schemas": { "PartnerEvent": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "type": { "type": "string", "enum": [ "product.upsert", "product.deleted", "service.upsert", "service.deleted", "plan.upsert", "plan.deleted", "subscription.upsert", "invoice.upsert", "order.status", "refund.approved" ] }, "entityId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "data": {} }, "required": [ "version", "id", "type", "entityId", "revision", "occurredAt", "data" ], "additionalProperties": false, "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "product.upsert" ] }, "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "enum": [ "SAR" ] }, "sku": { "type": "string", "maxLength": 100 }, "category": { "type": "string", "maxLength": 120 }, "images": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "variants": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "available": { "type": "boolean" } }, "required": [ "id", "name", "priceMinor", "available" ], "additionalProperties": false } }, "available": { "type": "boolean" }, "taxLabel": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "required": [ "name", "published", "priceMinor", "currency", "images", "variants", "available" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "service.upsert" ] }, "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "image": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "required": [ "name", "published" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "plan.upsert" ] }, "data": { "type": "object", "properties": { "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "enum": [ "SAR" ] }, "interval": { "type": "string", "enum": [ "month", "year", "one_time", "custom" ] }, "intervalDays": { "type": "integer", "minimum": 1, "maximum": 3660 }, "features": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "taxLabel": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "required": [ "serviceId", "name", "published", "priceMinor", "currency", "interval", "features" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "subscription.upsert" ] }, "data": { "type": "object", "properties": { "buyerRegistration": { "type": "string", "maxLength": 40 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "planId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "paused", "canceled", "expired", "provisioning" ] }, "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "features": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "usage": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "used": { "type": "number", "minimum": 0 }, "limit": { "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "name", "used", "limit" ], "additionalProperties": false } } }, "required": [ "buyerRegistration", "serviceId", "planId", "status", "features", "usage" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "invoice.upsert" ] }, "data": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "invoice", "credit_note" ] }, "status": { "type": "string", "enum": [ "issued", "paid", "void" ] }, "buyerKind": { "type": "string", "enum": [ "personal", "business" ] }, "buyerPhone": { "type": "string", "maxLength": 40 }, "buyerRegistration": { "type": "string", "maxLength": 40 }, "sourceCustomerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "currency": { "type": "string", "enum": [ "SAR" ] }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "documentPath": { "type": "string", "minLength": 1, "maxLength": 1500 }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "originalInvoiceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "reference", "kind", "status", "buyerKind", "issuedAt", "currency", "netMinor", "vatMinor", "grossMinor" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "order.status" ] }, "data": { "type": "object", "properties": { "nazOrderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "accepted", "processing", "shipped", "delivered", "collected", "activated", "disputed", "cancellation_requested" ] }, "tracking": { "type": "object", "properties": { "carrier": { "type": "string", "maxLength": 120 }, "number": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "maxLength": 1000, "format": "uri" } }, "additionalProperties": false } }, "required": [ "nazOrderId", "sourceOrderId", "status" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "refund.approved" ] }, "data": { "type": "object", "properties": { "nazOrderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceRefundId": { "type": "string", "minLength": 1, "maxLength": 160 }, "amountMinor": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 100000000 }, "eligibleNetMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "creditNoteId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "nazOrderId", "sourceRefundId", "amountMinor", "eligibleNetMinor", "creditNoteId", "reason" ], "additionalProperties": false } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "product.deleted" ] }, "data": { "type": "object" } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "service.deleted" ] }, "data": { "type": "object" } }, "required": [ "type", "data" ] }, { "properties": { "type": { "type": "string", "enum": [ "plan.deleted" ] }, "data": { "type": "object" } }, "required": [ "type", "data" ] } ] }, "Product": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "enum": [ "SAR" ] }, "sku": { "type": "string", "maxLength": 100 }, "category": { "type": "string", "maxLength": 120 }, "images": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "variants": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "available": { "type": "boolean" } }, "required": [ "id", "name", "priceMinor", "available" ], "additionalProperties": false } }, "available": { "type": "boolean" }, "taxLabel": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "required": [ "name", "published", "priceMinor", "currency", "images", "variants", "available" ], "additionalProperties": false }, "Service": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "image": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "required": [ "name", "published" ], "additionalProperties": false }, "Plan": { "type": "object", "properties": { "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "published": { "type": "boolean" }, "priceMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "enum": [ "SAR" ] }, "interval": { "type": "string", "enum": [ "month", "year", "one_time", "custom" ] }, "intervalDays": { "type": "integer", "minimum": 1, "maximum": 3660 }, "features": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "taxLabel": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "required": [ "serviceId", "name", "published", "priceMinor", "currency", "interval", "features" ], "additionalProperties": false }, "Subscription": { "type": "object", "properties": { "buyerRegistration": { "type": "string", "maxLength": 40 }, "serviceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "planId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "paused", "canceled", "expired", "provisioning" ] }, "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "features": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "usage": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false }, "used": { "type": "number", "minimum": 0 }, "limit": { "nullable": true, "type": "number", "minimum": 0 } }, "required": [ "name", "used", "limit" ], "additionalProperties": false } } }, "required": [ "buyerRegistration", "serviceId", "planId", "status", "features", "usage" ], "additionalProperties": false }, "Invoice": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "invoice", "credit_note" ] }, "status": { "type": "string", "enum": [ "issued", "paid", "void" ] }, "buyerKind": { "type": "string", "enum": [ "personal", "business" ] }, "buyerPhone": { "type": "string", "maxLength": 40 }, "buyerRegistration": { "type": "string", "maxLength": 40 }, "sourceCustomerId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "currency": { "type": "string", "enum": [ "SAR" ] }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "documentPath": { "type": "string", "minLength": 1, "maxLength": 1500 }, "documentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "originalInvoiceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "reference", "kind", "status", "buyerKind", "issuedAt", "currency", "netMinor", "vatMinor", "grossMinor" ], "additionalProperties": false }, "OrderStatus": { "type": "object", "properties": { "nazOrderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceOrderId": { "type": "string", "minLength": 1, "maxLength": 160 }, "status": { "type": "string", "enum": [ "accepted", "processing", "shipped", "delivered", "collected", "activated", "disputed", "cancellation_requested" ] }, "tracking": { "type": "object", "properties": { "carrier": { "type": "string", "maxLength": 120 }, "number": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "maxLength": 1000, "format": "uri" } }, "additionalProperties": false } }, "required": [ "nazOrderId", "sourceOrderId", "status" ], "additionalProperties": false }, "RefundApproval": { "type": "object", "properties": { "nazOrderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceRefundId": { "type": "string", "minLength": 1, "maxLength": 160 }, "amountMinor": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 100000000 }, "eligibleNetMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "creditNoteId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reason": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "nazOrderId", "sourceRefundId", "amountMinor", "eligibleNetMinor", "creditNoteId", "reason" ], "additionalProperties": false }, "Quote": { "type": "object", "properties": { "quoteId": { "type": "string", "minLength": 1, "maxLength": 160 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 160 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "currency": { "type": "string", "enum": [ "SAR" ] }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "shippingMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "totalMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "items": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 160 }, "variantId": { "type": "string", "minLength": 1, "maxLength": 160 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "unitMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 } }, "required": [ "productId", "quantity", "unitMinor" ], "additionalProperties": false } }, "subscriptionVersion": { "type": "string", "maxLength": 160 }, "description": { "type": "object", "properties": { "ar": { "type": "string", "maxLength": 4000 }, "en": { "type": "string", "maxLength": 4000 } }, "required": [ "ar" ], "additionalProperties": false } }, "required": [ "quoteId", "reservationId", "expiresAt", "currency", "netMinor", "vatMinor", "shippingMinor", "totalMinor", "items" ], "additionalProperties": false } }, "securitySchemes": { "connection": { "type": "apiKey", "in": "header", "name": "X-Naz-Connection" }, "signature": { "type": "apiKey", "in": "header", "name": "X-Naz-Signature" } } }, "security": [ { "connection": [], "signature": [] } ], "paths": { "/capabilities": { "post": { "description": "Return version:1 and only implemented and tested capabilities.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "version", "capabilities" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/changes": { "post": { "description": "Bounded resumable changes: {cursor:null|string,limit:100,reconcile:boolean}. No deletion from missing pages.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "reconcile": { "type": "boolean" } }, "required": [ "cursor", "limit", "reconcile" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PartnerEvent" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "events", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/shipping": { "post": { "description": "Source shipping/pickup options for buyer, address and requested lines.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "buyer": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal", "business" ] }, "phone": { "type": "string" }, "name": { "type": "string" }, "registration": { "type": "string" } }, "required": [ "kind", "phone", "name" ], "additionalProperties": false }, "address": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "line1": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string", "enum": [ "SA" ] } }, "required": [ "name", "phone", "city", "line1" ], "additionalProperties": false }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "productId", "quantity" ], "additionalProperties": false }, "maxItems": 30 } }, "required": [ "buyer", "address", "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "object" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "pickup": { "type": "boolean" } }, "required": [ "id", "name", "amountMinor", "pickup" ], "additionalProperties": false } } }, "required": [ "options" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/quotes": { "post": { "description": "Idempotent by nazOrderId. Atomic price/stock or upgrade quote and reservation. Echo subscriptionVersion. Exact integer source totals; expiry 1–15 minutes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "maxLength": 150 }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "kind": { "type": "string", "enum": [ "goods", "service" ] }, "nazOrderId": { "type": "string", "format": "uuid" }, "buyer": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal", "business" ] }, "phone": { "type": "string" }, "name": { "type": "string" }, "registration": { "type": "string" } }, "required": [ "kind", "phone", "name" ], "additionalProperties": false }, "address": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "line1": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string", "enum": [ "SA" ] } }, "required": [ "name", "phone", "city", "line1" ], "additionalProperties": false }, "shippingMethod": { "type": "string" }, "connectionId": { "type": "string", "format": "uuid" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "productId", "quantity" ], "additionalProperties": false }, "maxItems": 30 }, "serviceId": { "type": "string" }, "planId": { "type": "string" }, "subscriptionId": { "type": "string" }, "subscriptionVersion": { "type": "string" } }, "required": [ "idempotencyKey", "environment", "kind", "nazOrderId", "buyer" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/reservations/release": { "post": { "description": "Idempotently release by nazOrderId, even if the quote response was lost.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "maxLength": 150 }, "nazOrderId": { "type": "string", "format": "uuid" }, "reservationId": { "type": "string" } }, "required": [ "idempotencyKey", "nazOrderId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "released", "not_found" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/orders/commit": { "post": { "description": "Idempotently commit by nazOrderId; validate frozen reservation, quote and verified payment allocation. Do not charge again. Return rejected only for a final failure.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "maxLength": 150 }, "nazOrderId": { "type": "string", "format": "uuid" }, "nazCheckoutId": { "type": "string", "format": "uuid" }, "reservationId": { "type": "string" }, "quoteId": { "type": "string" }, "payment": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "reference": { "type": "string" }, "totalMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "cashMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "pointsMinor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "enum": [ "SAR" ] } }, "required": [ "environment", "reference", "totalMinor", "cashMinor", "pointsMinor", "currency" ], "additionalProperties": false }, "buyer": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal", "business" ] }, "phone": { "type": "string" }, "name": { "type": "string" }, "registration": { "type": "string" } }, "required": [ "kind", "phone", "name" ], "additionalProperties": false } }, "required": [ "idempotencyKey", "nazOrderId", "nazCheckoutId", "reservationId", "quoteId", "payment", "buyer" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceOrderId": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "rejected" ] } }, "required": [ "sourceOrderId", "status" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/refunds/request": { "post": { "description": "Buyer return request; source authorizes a signed refund.approved event with its original credit note.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "maxLength": 150 }, "nazOrderId": { "type": "string", "format": "uuid" }, "sourceOrderId": { "type": "string" }, "reason": { "type": "string", "minLength": 5, "maxLength": 300 } }, "required": [ "idempotencyKey", "nazOrderId", "sourceOrderId", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "rejected" ] } }, "required": [ "requestId", "status" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } }, "/refunds/confirm": { "post": { "description": "Idempotent acknowledgement of a verified refund result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "maxLength": 150 }, "nazOrderId": { "type": "string", "format": "uuid" }, "refundId": { "type": "string" }, "creditNoteId": { "type": "string" }, "providerRef": { "type": "string", "nullable": true } }, "required": [ "idempotencyKey", "nazOrderId", "refundId", "creditNoteId", "providerRef" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verified source response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "acknowledged" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "401": { "description": "Signature invalid or timestamp outside 300 seconds" }, "409": { "description": "Idempotency or subscription version conflict" }, "422": { "description": "Business validation or unimplemented capability" } } } } } }