Welcome to the our developers zone!


If you want to integrate your Healthcare Platform (EMR, EHR, HMS) or your APP with the OPTretina service
Congratulations! this is now possible and you are in the right place.
Explore our HL7 or our HTTP APIs available!

API for developers

API for developers


OPTretina HL7 Interface / API

Contact us to obtain the HL7 Interface – technical documentation


OPTretina HTTP Interface / API

HTTP client implementation in PHP 

1.  Sample code in PHP

Sample code in PHP for the OPTretina API HTTP client implementation

2. Implementation Details

2.1 Communication protocol

Optretina API is a REST implementation based on HTTP protocol for communication and JSON for data serialization. The character encoding used is UTF-8

2.2 Authentication

Clients should authenticate before invoking any API method with the exception of the authentication method. Optretina implements OAuth2 for authentication ( The grant method used is Client Grant. API Clients must authenticate using their account user and password. An access token will be provided by the authentication method, this access token should be present in all API calls. If API call is GET, the access_token parameter should by passed by GET. If it is a POST call the access_token should be passed by POST

2.3 Data Encoding

Data from the Client to the Server is sent using standard POST requests, encoded using “application/x-www-form-urlencoded“. Files are sent using “multipart/form-data“. This is the same way an standard browser sents information.

All data from the Server to the Client is exchanged using JSON (JavaScript Object Notation, RFC 4627). JSON is a widely used serialization format with many available libraries on almost every programming language (More info at

3. Calling API methods

3.1 HTTP Request

API Methods can be called by POST or GET, having a different behaviour for each HTTP verb.

All data sent by POST is encoded using “application/x-www-form-urlencoded” and “multipart/form-data“. API Method parameters are passed directly in the URL path.

3.2 HTTP Reply

API replies are always encoded using JSON. The reply is a JSON encoded object containing always two properties:

  • success: true|false
  • sontent: response specific object

When success is false “content” value is a string with the error message.

4. API methods reference

4.1 Authorization

The OAuth2 authorization method.

  • Verb: POST
  • Path: /authorize
  • Params:
    • client_id: Client username
    • client_secret: Client password
    • grant_type: Currently “client_credentials” is supported only
  • Return:
    • access_token

4.2 Case List

List all cases accessible by the user

  • Verb: GET
  • Path: /cases
  • Params: None
  • Return: Returns an array of cases, each one containing the following fields:
    • id
    • history_number
    • first_name
    • last_name
    • secondary_last_name
    • visit_date
    • status

4.3 Case info

Gets all information given a case ID

  • Verb: GET
  • Path: /cases/:id
  • Params:
    • id: Case id
  • Return: Returns an array of cases, each one containing the following fields:
    • id: Case identifier
    • history_number: Patient history number
    • first_name Patient first name
    • last_name Patient last name
    • secondary_last_name Patient secondary last name
    • visit_date Patient visit date
    • status Case status (One of new, pending, draft, reported)

4.4 Case report

Given a case id obtain its report

  • Verb: GET
  • Path: /cases/report/:id
  • Params:
    • id: Case id
  • Return: Returns a report in PDF format encoded in base64

4.5 Case creation

Create a case passing all needed parameters

  • Verb: POST
  • Path: /cases/
  • Params:
    • history_number: Patient history number
    • fist_name: Patient fist name
    • last_name: Patient last name
    • secondary_last_name: Patient secondary last name
    • gender: Patient gender (0 for male, 1 for female)
    • age: Patient age
    • visit_date: Visit date, preferred format is ISO 8601 (2014-09-10T13:40:21+00:00)
    • diabetes: Patient has diabetes (0 for no, 1 for yes)
    • visit_reason: Visit reason
    • ophtalmic_antecedents: Ophtalmic antecedents
    • other_relevant_info: Other relevant information
    • retinologist_notes: Notes for the retinologist
    • od_iop: Oculus Dexter – Intra Ocular Pressure
    • od_va: Oculus Dexter – Visual Acuity
    • od_axis: Oculus Dexter – Axis
    • od_cylinder: Oculus Dexter – Cylinder
    • od_sphere: Oculus Dexter – Sphere
    • od_add: Oculus Dexter – Addition
    • od_prism: Oculus Dexter – Prism
    • od_prism_base: Oculus Dexter – Prism Base
    • os_iop: Oculus Sinister – Intra Ocular Pressure
    • os_va: Oculus Sinister – Visual Acuity
    • os_axis: Oculus Sinister – Axis
    • os_cylinder: Oculus Sinister – Cylinder
    • os_sphere: Oculus Sinister – Sphere
    • os_add: Oculus Sinister – Addition
    • os_prism: Oculus Sinister – Prism
    • os_prism_base: Oculus Sinister – Prism Base
    • images: Array of images sent using standard multipart/form-data
    • callback_url: URL to be called when the report is ready
  • Return: Returns the inserted case id

5. Callback URL

The system will make a POST request when the report is ready to the specified callback_url when the case was created

The POST request will contain the “case” parameter with the case id as value.



Please contact us to request your credentials to connect to our sandbox environment. Once the integration is validated by us and you are ready we will give you the production credentials.

We use own and third party cookies to improve your user experience and offer the best services. If you continue browsing , we consider that you accept their use. More Info

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.