{ "info": { "_postman_id": "c2e7a4f1-8b3d-4e6a-9a55-1f0c7d2b6e42", "name": "Basmtak Clinics Partner API v1", "description": "Read a clinic's patients, appointments and invoices, book and cancel appointments, and receive signed webhooks (appointment.*, invoice.*, claim.*, patient.erased). Money is always integer halalas (1 SAR = 100); ids of clinical rows are ULIDs; times are ISO-8601 in the branch's zone. Errors are JSON {error, message, details}; the message follows Accept-Language (ar or en). Lists answer {data, meta} and page with ?page and ?per_page (at most 100). No diagnoses, clinical notes or photos ever travel through this API.\n\nGenerated from the OpenAPI file at /developers/openapi.yaml. Set {{token}} to an API client token (Office → Developers). «Subscribe» stores {{webhook_id}} and {{webhook_secret}}.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code >= 400 && pm.response.headers.get('Content-Type') && pm.response.headers.get('Content-Type').includes('json')) {", " pm.test('error answers carry {error, message, details}', function () {", " const j = pm.response.json();", " pm.expect(j).to.have.property('error');", " pm.expect(j).to.have.property('message');", " });", "}" ] } } ], "variable": [ { "key": "base_url", "value": "https://clinics.basmtak.com/partner/v1", "type": "string" }, { "key": "token", "value": "", "type": "string" }, { "key": "lang", "value": "ar", "type": "string" }, { "key": "webhook_id", "value": "", "type": "string" }, { "key": "webhook_secret", "value": "", "type": "string" }, { "key": "receiver_url", "value": "https://example.com/basmtak/webhook", "type": "string" } ], "item": [ { "name": "meta", "description": "Connectivity and what this server offers", "item": [ { "name": "Check the token and see the client's abilities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/ping", "host": [ "{{base_url}}" ], "path": [ "ping" ] }, "description": "Check the token and see the client's abilities\n\nAbility: any" } }, { "name": "Abilities, the event catalogue, rate limits and the spec version", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/meta", "host": [ "{{base_url}}" ], "path": [ "meta" ] }, "description": "Abilities, the event catalogue, rate limits and the spec version\n\nAbility: any" } } ] }, { "name": "patients", "description": "The patient read subset (demographics and identifiers, never clinical content)", "item": [ { "name": "List patients", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/patients", "host": [ "{{base_url}}" ], "path": [ "patients" ], "query": [ { "key": "page", "value": "", "description": "integer", "disabled": true }, { "key": "per_page", "value": "", "description": "integer", "disabled": true }, { "key": "file_no", "value": "", "description": "string", "disabled": true }, { "key": "phone", "value": "", "description": "E.164", "disabled": true }, { "key": "updated_since", "value": "", "description": "ISO-8601; only patients changed since then", "disabled": true } ] }, "description": "Demographics and identifiers only. Search by file_no, national id or phone through the filters below.\n\nAbility: patients:read" } }, { "name": "One patient", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/patients/:id", "host": [ "{{base_url}}" ], "path": [ "patients", ":id" ], "variable": [ { "key": "id", "value": "", "description": "ULID (26 characters)" } ] }, "description": "One patient\n\nAbility: patients:read" } } ] }, { "name": "appointments", "description": "Appointments, booking and cancellation", "item": [ { "name": "List appointments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/appointments", "host": [ "{{base_url}}" ], "path": [ "appointments" ], "query": [ { "key": "page", "value": "", "description": "integer", "disabled": true }, { "key": "per_page", "value": "", "description": "integer", "disabled": true }, { "key": "branch_id", "value": "", "description": "integer", "disabled": true }, { "key": "patient_id", "value": "", "description": "string", "disabled": true }, { "key": "practitioner_id", "value": "", "description": "string", "disabled": true }, { "key": "from", "value": "", "description": "ISO-8601 date or date-time (inclusive)", "disabled": true }, { "key": "to", "value": "", "description": "ISO-8601 date or date-time (exclusive)", "disabled": true }, { "key": "status", "value": "", "description": "string", "disabled": true } ] }, "description": "List appointments\n\nAbility: appointments:read" } }, { "name": "Book an appointment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/appointments", "host": [ "{{base_url}}" ], "path": [ "appointments" ] }, "description": "Books a free slot (GET the clinic's slots through the portal rules the SCHEDULING package publishes). external_ref makes the call idempotent per API client: the same external_ref answers 200 with the same appointment, never a second booking. The patient is named by id or by phone (a new patient file is opened when the phone is unknown).\n\nAbility: appointments:write", "body": { "mode": "raw", "raw": "{\n \"branch_id\": 1,\n \"practitioner_id\": \"01J9ZJ0000000000000000000D\",\n \"appointment_type_id\": 3,\n \"starts_at\": \"2027-04-02T18:00:00+03:00\",\n \"patient_id\": \"01J9ZJ0000000000000000000P\",\n \"external_ref\": \"crm-1001\",\n \"note\": \"يفضل الفترة المسائية\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "One appointment", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/appointments/:id", "host": [ "{{base_url}}" ], "path": [ "appointments", ":id" ], "variable": [ { "key": "id", "value": "", "description": "ULID (26 characters)" } ] }, "description": "One appointment\n\nAbility: appointments:read" } }, { "name": "Cancel an appointment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/appointments/:id/cancel", "host": [ "{{base_url}}" ], "path": [ "appointments", ":id", "cancel" ], "variable": [ { "key": "id", "value": "", "description": "ULID (26 characters)" } ] }, "description": "Cancelling twice is a no-op (200). A completed or in-progress appointment answers 409 appointment_locked.\n\nAbility: appointments:write", "body": { "mode": "raw", "raw": "{\n \"reason\": \"patient_request\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "invoices", "description": "Issued invoices and their payment state", "item": [ { "name": "List issued invoices", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/invoices", "host": [ "{{base_url}}" ], "path": [ "invoices" ], "query": [ { "key": "page", "value": "", "description": "integer", "disabled": true }, { "key": "per_page", "value": "", "description": "integer", "disabled": true }, { "key": "patient_id", "value": "", "description": "string", "disabled": true }, { "key": "branch_id", "value": "", "description": "integer", "disabled": true }, { "key": "status", "value": "", "description": "string", "disabled": true }, { "key": "issued_from", "value": "", "description": "ISO-8601 date (inclusive)", "disabled": true }, { "key": "issued_to", "value": "", "description": "ISO-8601 date (exclusive)", "disabled": true } ] }, "description": "List issued invoices\n\nAbility: invoices:read" } }, { "name": "One invoice with its lines and payments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/invoices/:id", "host": [ "{{base_url}}" ], "path": [ "invoices", ":id" ], "variable": [ { "key": "id", "value": "", "description": "ULID (26 characters)" } ] }, "description": "One invoice with its lines and payments\n\nAbility: invoices:read" } } ] }, { "name": "webhooks", "description": "REST hooks (Zapier and Make)", "item": [ { "name": "Your subscriptions", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/webhooks", "host": [ "{{base_url}}" ], "path": [ "webhooks" ], "query": [ { "key": "page", "value": "", "description": "integer", "disabled": true }, { "key": "per_page", "value": "", "description": "integer", "disabled": true } ] }, "description": "Your subscriptions\n\nAbility: webhooks" } }, { "name": "Subscribe (REST hook)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/webhooks", "host": [ "{{base_url}}" ], "path": [ "webhooks" ] }, "description": "The answer carries the subscription id and its signing secret. The secret is shown only here. The client must hold the ability that reads each event's data (appointments:read, invoices:read, patients:read).\n\nAbility: webhooks", "body": { "mode": "raw", "raw": "{\n \"target_url\": \"https://hooks.zapier.com/hooks/standard/123/abc\",\n \"event\": \"appointment.created\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('subscribed (201)', function () { pm.response.to.have.status(201); });", "const j = pm.response.json();", "if (j.id) pm.collectionVariables.set('webhook_id', String(j.id));", "if (j.secret) pm.collectionVariables.set('webhook_secret', j.secret); // shown only once" ] } } ] }, { "name": "The events, each with the ability it needs and sample data", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/webhooks/events", "host": [ "{{base_url}}" ], "path": [ "webhooks", "events" ] }, "description": "The events, each with the ability it needs and sample data\n\nAbility: webhooks" } }, { "name": "Recent real objects of one event (REST hook perform list)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/webhooks/events/:event/recent", "host": [ "{{base_url}}" ], "path": [ "webhooks", "events", ":event", "recent" ], "query": [ { "key": "limit", "value": "", "description": "1 to 25, default 3", "disabled": true } ], "variable": [ { "key": "event", "value": "appointment.created", "description": "string" } ] }, "description": "The newest real objects of one event, each wrapped in the envelope a delivery carries {id, event, tenant_id, occurred_at, api_version, data}, newest first. Zapier calls this as the REST Hook trigger's perform list when a user tests a Zap; Make uses it to fetch sample data. id is event:object-id (stable, for de-duplication), not the uuid of a live delivery. Besides webhooks the client needs the ability that receives the event. meta.sample is the static sample, for a clinic with no data yet; data is empty until the event's package publishes its recent objects.\n\nAbility: webhooks" } }, { "name": "One subscription", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "webhooks", ":id" ], "variable": [ { "key": "id", "value": "{{webhook_id}}", "description": "integer" } ] }, "description": "One subscription\n\nAbility: webhooks" } }, { "name": "Change the URL, the events, the description or switch it on or off", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "webhooks", ":id" ], "variable": [ { "key": "id", "value": "{{webhook_id}}", "description": "integer" } ] }, "description": "Change the URL, the events, the description or switch it on or off\n\nAbility: webhooks", "body": { "mode": "raw", "raw": "{\n \"events\": [\n \"appointment.created\",\n \"appointment.cancelled\"\n ],\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Unsubscribe (REST hook)", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" } ], "url": { "raw": "{{base_url}}/webhooks/:id", "host": [ "{{base_url}}" ], "path": [ "webhooks", ":id" ], "variable": [ { "key": "id", "value": "{{webhook_id}}", "description": "integer" } ] }, "description": "Unsubscribe (REST hook)\n\nAbility: webhooks" } }, { "name": "Mint a new signing secret (the old one stops at once)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/webhooks/:id/rotate", "host": [ "{{base_url}}" ], "path": [ "webhooks", ":id", "rotate" ], "variable": [ { "key": "id", "value": "{{webhook_id}}", "description": "integer" } ] }, "description": "Mint a new signing secret (the old one stops at once)\n\nAbility: webhooks", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Send a signed ping to this subscription now", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Accept-Language", "value": "{{lang}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url}}/webhooks/:id/test", "host": [ "{{base_url}}" ], "path": [ "webhooks", ":id", "test" ], "variable": [ { "key": "id", "value": "{{webhook_id}}", "description": "integer" } ] }, "description": "Delivers a `ping` event (data {subscription_id, message}) and answers the delivery row with its status and the receiver's HTTP status.\n\nAbility: webhooks", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Webhook signature", "description": "Sends a sample appointment.created delivery, signed with {{webhook_secret}} the way Basmtak signs every delivery, to {{receiver_url}} (your endpoint). Your receiver should accept it, and reject it once you change one byte of the body. Events: appointment.created, appointment.updated, appointment.cancelled, invoice.issued, invoice.paid, claim.updated, patient.erased.", "item": [ { "name": "Simulate a signed delivery to your receiver", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// X-Basmtak-Signature = \"sha256=\" + hex HMAC-SHA256(secret, ts + \"\\n\" + \"POST\" + \"\\n\" + path + \"\\n\" + hex SHA-256(raw body))", "const secret = pm.collectionVariables.get('webhook_secret');", "if (!secret) throw new Error('Set webhook_secret first (Subscribe stores it)');", "const ts = Math.floor(Date.now() / 1000).toString();", "const body = pm.request.body ? pm.request.body.raw : '';", "const url = pm.collectionVariables.replaceIn(pm.request.url.toString());", "let path = url.replace(/^[a-z]+:\\/\\/[^\\/]+/i, '').split('?')[0].split('#')[0];", "if (!path) path = '/';", "const canonical = ts + '\\n' + 'POST' + '\\n' + path + '\\n' + CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);", "const sig = 'sha256=' + CryptoJS.HmacSHA256(canonical, secret).toString(CryptoJS.enc.Hex);", "pm.request.headers.upsert({ key: 'X-Basmtak-Timestamp', value: ts });", "pm.request.headers.upsert({ key: 'X-Basmtak-Signature', value: sig });" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Basmtak-Event", "value": "appointment.created" }, { "key": "X-Basmtak-Event-Id", "value": "7d3f0c52-1a4b-4c8e-9f21-6b0d2e5a9c11" } ], "body": { "mode": "raw", "raw": "{\n \"id\": \"7d3f0c52-1a4b-4c8e-9f21-6b0d2e5a9c11\",\n \"event\": \"appointment.created\",\n \"tenant_id\": 1,\n \"occurred_at\": \"2027-04-02T18:21:07+03:00\",\n \"api_version\": \"v1\",\n \"data\": {\n \"id\": \"01J9ZK3Q7R8S9T0V1W2X3Y4Z5A\",\n \"patient_id\": \"01J9ZJ0000000000000000000P\",\n \"branch_id\": 1,\n \"practitioner_id\": \"01J9ZJ0000000000000000000D\",\n \"appointment_type_id\": 3,\n \"status\": \"booked\",\n \"starts_at\": \"2027-04-02T18:00:00+03:00\",\n \"ends_at\": \"2027-04-02T18:30:00+03:00\",\n \"room_id\": 2,\n \"source\": \"partner\",\n \"external_ref\": \"crm-1001\",\n \"note\": null,\n \"created_at\": \"2027-04-01T09:12:07+03:00\",\n \"updated_at\": \"2027-04-01T09:12:07+03:00\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{receiver_url}}", "host": [ "{{receiver_url}}" ] } } } ] } ] }