canonical: https://jentic.com/apis/rota.sp.gov.br/rota-sp

# Rota Sp Ses Questionarios

The Ses Questionarios API registers patients and runs health screening questionnaires for the São Paulo state health secretariat (SES) integration platform. It creates or updates a patient record keyed on the patient's CPF (the federalId field), carrying address, contact details, and alcohol and nicotine dependency levels. A client fetches a questionnaire by id with its questions and answer options, then submits the chosen answers and receives a result with a risk level. The published server is the homologation (hml) environment of the Rota SP gateway.

## For AI agents

Register or update a São Paulo SES patient by CPF, fetch a screening questionnaire, and submit answers to get a scored risk level.

## Scope

Does not book appointments, store clinical notes, or issue prescriptions. Use for SES patient registration and dependency screening questionnaires only.

## Capabilities

- Create or update a patient record keyed on the CPF in the federalId field, with address, phone, email, and birthDate
- Record alcohol and nicotine dependency levels on a patient, such as HIGH_RISK, plus the cigaretteType used
- Fetch a screening questionnaire by id with its questions and the answer options for each
- Submit a completed questionnaire as idAnswer and idResponse pairs and read back the result and risk level

## Use cases

### AI intake agent for SES health screening

An AI intake assistant for a São Paulo health service collects a patient's details and walks them through a screening questionnaire. Through Jentic the agent searches for 'register a patient by CPF', loads the criaPaciente operation with its input schema, and submits the record with an OAuth 2.0 token injected at call time. It then fetches the questionnaire, presents each question with its answer options, and posts the answers to get the scored result.

Example prompt: Call POST /paciente with federalId, patientName, birthDate, and address, then GET `/questionario/1` and POST `/questionario/resultado` with the questionnaire id and the chosen idAnswer and idResponse pairs

### Alcohol and tobacco dependency screening

A public health programme screens patients for alcohol and nicotine dependency and needs the risk band stored against each patient. The patient schema carries lifeWithoutAlcool and lifeWithoutNicotine objects with a dependencyLevel enum, such as LOW_RISK or HIGHEST_RISK, and a cigaretteType enum covering cigarettes, electronic cigarettes, hookah, and other forms. Submitting the questionnaire result returns a level string the programme can map to follow-up care.

Example prompt: Submit POST `/questionario/resultado` for questionnaire id 1 with the patient's answers, then call POST /paciente for the same federalId with lifeWithoutNicotine.dependencyLevel set to the band that matches the returned level

### Rendering a questionnaire in a patient app

A patient-facing mobile or web app needs the current questionnaire content rather than hard-coded questions. GET `/questionario/{id}` returns the questionnaire name, description, and an answers array where each question carries its text and its list of response options with ids. The app renders the form from that payload, and a 204 response signals that no questionnaire was found for the id.

Example prompt: Call GET `/questionario/1` and list each question text with its response options and their ids

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/paciente` | Create or update a patient by CPF |
| GET | `/questionario/{id}` | Get a questionnaire with its questions |
| POST | `/questionario/resultado` | Submit answers and get the risk result |

## Key resources

- **Paciente** — Patient record keyed on federalId (CPF) with address, contact details, motherName, maritalStatus, and alcohol and nicotine dependency levels
- **Questionarios** — Screening questionnaire with an id, name, description, and an answers array of questions and response options
- **Resultado** — Submitted questionnaire answers as idAnswer and idResponse pairs, returning a result and a level

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 51 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 83 / 100
  - AI-Readiness & Agent Experience: 43 / 100
  - Agent Usability: 94 / 100
  - Security: 85 / 100
  - AI Discoverability: 17 / 100
- **View full report:** https://jentic.com/apis/rota.sp.gov.br/rota-sp/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Ses Questionarios API by hand means registering an IdpSP client, running the OAuth 2.0 client credentials flow against the SP government Keycloak realm with the `api:integrador.ses-questionarios` scope, and refreshing tokens yourself. Through Jentic you install once, import the API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** The three operations are distinct paths, and only the questionnaire read carries an id in the URL, so rules bound which operations your agent may call rather than which patient. You choose the operations it may call, so writes like patient creation or result submission are not included unless you add them.
- **Credential handling:** Your IdpSP client credentials are stored once, encrypted, by your own Jentic One instance and the token is injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'register a patient by CPF' or 'submit questionnaire answers', and Jentic returns the matching Ses Questionarios operation with its input schema so the agent sends the right fields without reading the Portuguese reference.

## Related APIs

- **DrChrono** — Full EHR with patient charts, appointments, and clinical records for medical practices
- **Typeform** — General-purpose form and survey builder with response collection
- **Jotform** — Online forms for collecting patient intake details before submission

## FAQ

### What authentication does the Ses Questionarios API use?

Per its OpenAPI spec, the Ses Questionarios API uses OAuth 2.0 through the IdpSP identity provider, with client credentials and authorization code flows against the rhsso.idp-hml.sp.gov.br token endpoint. All three operations request the `api:integrador.ses-questionarios` scope. Through Jentic the client secret is held by your own Jentic One instance and the token is attached at call time.

### Can I get a risk level from a completed questionnaire with the Ses Questionarios API?

Yes. POST `/questionario/resultado` takes the questionnaire id and an answers array of idAnswer and idResponse pairs, and returns a result string and a level such as Alto. Fetch the question and response ids first with GET `/questionario/{id}` so the submitted pairs match the questionnaire.

### What are the rate limits for the Ses Questionarios API?

The OpenAPI spec does not specify rate limits. The spec was published on SwaggerHub under the ses-questionarios project, so check with the Rota SP integration team that issues your IdpSP client for any limits on the homologation and production gateways.

### Is there a Ses Questionarios MCP server?

You do not need an MCP server to give your agent the Ses Questionarios API. Jentic connects it directly from the API Directory: import it, store your OAuth client credentials once, and your agent calls the patient and questionnaire operations on demand without extra tool definitions in its context.

### How do I register a patient through Jentic?

Search Jentic for 'register a patient by CPF', load the POST /paciente operation, and execute it with federalId, patientName, birthDate, and the address object. The operation creates the patient, or updates the existing record when the CPF is already known. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Ses Questionarios API?

Yes. For a read-only assistant, write a rule that allows only GET `/questionario/{id}`, so the agent can show questionnaires to patients but cannot create patient records or submit results. Add the resultado operation when the agent should also score answers, and every call it makes is logged.
