> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmed.med.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Comece a usar a API NextMed Admin Service em poucos passos.

Este guia prepara você para chamar a API do Admin Service.

## Pré-requisitos

* Acesso à base URL da API (ex.: `http://localhost:8081` ou `http://localhost:8080/admin-service`).
* Credenciais ou headers exigidos pelo ambiente (ex.: header `origin`).

## Escolha a base URL

<Tabs>
  <Tab title="Serviço direto">
    Use `http://localhost:8081` quando o Admin Service estiver rodando sozinho. Os paths são `/users`, `/institutions`, `/protocols`, etc.
  </Tab>

  <Tab title="Via gateway">
    Use `http://localhost:8080/admin-service` quando o tráfego passar pelo gateway. Paths como usuários e instituições ficam em `/admin-service/users`, `/admin-service/institutions`; `/protocols` continua em `/protocols`.
  </Tab>
</Tabs>

## Sua primeira requisição

<Steps>
  <Step title="Defina a base URL">
    Escolha o ambiente (direto ou gateway) e use a URL correspondente em todas as requisições.
  </Step>

  <Step title="Inclua o header origin">
    A maioria dos endpoints exige o header `origin`. Substitua `your-origin` pelo valor configurado no seu deployment.
  </Step>

  <Step title="Liste usuários">
    Use um dos exemplos abaixo conforme a base URL escolhida.
  </Step>
</Steps>

<CodeGroup>
  ```bash Via gateway theme={"system"}
  curl -X GET "http://localhost:8080/admin-service/users" \
    -H "origin: your-origin"
  ```

  ```bash Serviço direto theme={"system"}
  curl -X GET "http://localhost:8081/users" \
    -H "origin: your-origin"
  ```
</CodeGroup>

<Tip>
  Se o seu ambiente usar Bearer token ou outros headers de autenticação, adicione-os à requisição (ex.: `-H "Authorization: Bearer YOUR_TOKEN"`).
</Tip>

## Exemplo: criar um protocolo

Criar um protocolo (path igual com ou sem gateway):

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST "http://localhost:8081/protocols" \
    -H "Content-Type: application/json" \
    -H "origin: your-origin" \
    -d '{
      "institutionId": "uuid-da-instituicao",
      "name": "Meu Protocolo",
      "prompt": "Prompt opcional para IA"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Sucesso (201) theme={"system"}
  {
    "id": "uuid-do-protocolo",
    "institutionId": "uuid-da-instituicao",
    "name": "Meu Protocolo",
    "prompt": "Prompt opcional para IA",
    "createdAt": "2025-03-09T18:00:00.000Z",
    "updatedAt": "2025-03-09T18:00:00.000Z"
  }
  ```
</ResponseExample>

<Check>
  Após o 201, use o `id` retornado para consultar ou atualizar o protocolo na [API Reference](/api-reference).
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Erro 401 Unauthorized">
    Verifique se o header `origin` está presente e com o valor esperado pelo ambiente. Em setups com gateway, confirme que o token ou sessão está sendo repassado corretamente.
  </Accordion>

  <Accordion title="Erro de CORS ou conexão recusada">
    Ao chamar de um browser, garanta que o backend permite a origem do front. Em desenvolvimento local, use a base URL correta (serviço direto ou gateway) e porta (ex.: 8081 ou 8080).
  </Accordion>

  <Accordion title="Protocolo não encontrado (404)">
    Confirme que o `institutionId` no body existe e que o path está correto: `POST /protocols` (sem prefixo `/admin-service`).
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="API Reference" icon="book-open" href="/api-reference">
    Endpoints, parâmetros e schemas gerados a partir do OpenAPI.
  </Card>

  <Card title="Introdução" icon="info" href="/introduction">
    Visão geral dos recursos e base URLs.
  </Card>
</CardGroup>