API Reference
The obeliOmed REST API exposes contract endpoints for external integrations, ObelioPortalWeb (patient portal), and future mobile clients.
Interactive reference (Swagger UI) → /docs/api/reference/obeliomed-api
Tools & auto-generation
The API reference is generated automatically on each merge to develop in any plugin repo.
The CI pipeline (.github/workflows/auto-gen.yml) runs:
| Tool | Output | Source |
|---|---|---|
swagger-php | OpenAPI YAML + interactive Swagger UI | #[OA\*] annotations in plugin Controllers |
phpDocumentor | PHP class / method HTML reference | PHPDoc on every public class and method |
schemaspy (XML) | DB schema Markdown (tables, columns, FKs) | Table/*.xml from each plugin |
Mermaid | ER diagrams inline | Auto-rendered via @docusaurus/theme-mermaid |
Authentication
All endpoints require a valid FacturaScripts API token:
GET /api/patients HTTP/1.1
X-FS-Token: <your-token>
Or HTTP Basic Auth with username:token.
Generate tokens in FacturaScripts → Admin → Users → API Token.
Base URL
| Environment | URL |
|---|---|
| Production | https://docs.obeliomed.com/api |
| Local XAMPP dev | http://localhost/FacturaScripts/api/3 |
Conventions
- Multi-tenant: every request is scoped to the company (
idEmpresa) carried by the token — no extra parameter needed. - Clinic center: pass
codalmacento scope to a specific center within the company. - Versioning: CalVer
YYMMDD.NN— breaking changes get a new path prefix (/v2/). Current version returned inX-obeliomed-Versionresponse header. - Pagination:
offset+limitparameters; response includesmeta.total. - Partial updates:
PATCHendpoints accept only the fields you want to change. - Legal guardian: when
patient.requires_legal_guardian = true, communication endpoints target the guardian contact by default.
Coverage
| Plugin | Endpoints | Status |
|---|---|---|
| ObelioCore (patients) | GET/POST /patients, GET/PATCH /patients/{id} | ✅ Spec live |
| ObelioScheduling | GET/POST /appointments, GET/PATCH /appointments/{id}, POST /appointments/{id}/checkin | ✅ Spec live |
| ObelioComms | POST /comms/send | ✅ Spec live |
| ObelioAudit | GET /audit/events | ✅ Spec live |
| ObelioDocs | /documents/* | 🔜 Sprint 2 auto-gen |
| ObelioConsents | /consents/* | 🔜 Sprint 2 auto-gen |
| ObelioOphthalmology | /clinical/* | 🔜 Sprint 2 auto-gen |