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

# Início rápido

> Faça sua primeira chamada autenticada à API do Portão 3

Este guia leva você das credenciais até sua primeira chamada de API bem-sucedida.

## Pré-requisitos

* Uma conta no Portão 3. Seu gerente de conta fornece **credenciais de usuário** (e-mail e senha) ou **credenciais de cliente de API** (`client_id` / `client_secret`) para integrações servidor a servidor.
* Seu `realmId` e `organizationId`, compartilhados durante o onboarding. Endpoints com escopo de tenant exigem ambos no caminho.

## Passo 1: Obtenha um token de acesso

Autentique-se no serviço Identity. Ambos os fluxos usam o mesmo endpoint e retornam o mesmo payload de token.

<Tabs>
  <Tab title="Credenciais de usuário">
    ```bash theme={null}
    curl -X POST https://api.identity.v2.portao3.com.br/auth/sign-in \
      -H "Content-Type: application/json" \
      -d '{
        "email": "you@yourcompany.com.br",
        "password": "your-password"
      }'
    ```
  </Tab>

  <Tab title="Cliente de API (servidor a servidor)">
    Envie seu `client_id` e `client_secret` como credenciais HTTP Basic e defina `grantType` no corpo:

    ```bash theme={null}
    # base64-encode the credentials; tr -d '\n' strips any line wrapping GNU base64 adds
    BASIC_AUTH=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64 | tr -d '\n')

    curl -X POST https://api.identity.v2.portao3.com.br/auth/sign-in \
      -H "Authorization: Basic $BASIC_AUTH" \
      -H "Content-Type: application/json" \
      -d '{ "grantType": "client_credentials" }'
    ```
  </Tab>
</Tabs>

Um login bem-sucedido retorna seus tokens:

```json theme={null}
{
  "accessToken": "eyJraWQiOi...",
  "idToken": "eyJraWQiOi...",
  "refreshToken": "eyJjdHkiOi..."
}
```

Use o `accessToken` como seu token bearer em cada requisição à API.

<Note>
  Se seu usuário tiver **MFA habilitado**, a resposta contém um `challenge` e um `session` em vez dos tokens. Complete o login com `POST /auth/confirm-mfa`, enviando seu `email`, o `userCode` de uso único do seu aplicativo autenticador e o valor de `session` retornado pelo login. A resposta contém seus tokens.
</Note>

## Passo 2: Faça sua primeira chamada

Verifique o token buscando o perfil do usuário autenticado:

```bash theme={null}
curl https://api.identity.v2.portao3.com.br/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Uma resposta `200` confirma que seu token funciona.

## Passo 3: Chame um endpoint com escopo de tenant

A maioria dos endpoints tem escopo do seu realm e organização. Por exemplo, liste seus contratos de cobrança:

```bash theme={null}
curl "https://api.billing.v2.portao3.com.br/realms/$REALM_ID/organizations/$ORG_ID/contracts" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Se receber um `403`, verifique se o `realmId` e o `organizationId` no caminho correspondem ao tenant ao qual suas credenciais pertencem.

## Passo 4: Renove seu token

Os tokens de acesso têm vida curta. Quando um expira, troque seu token de refresh por novos tokens em vez de fazer login novamente:

```bash theme={null}
curl -X POST https://api.identity.v2.portao3.com.br/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "<expired-access-token>",
    "refreshToken": "<your-refresh-token>"
  }'
```

Você também pode incluir seu `idToken` no corpo para renová-lo ao mesmo tempo.

## Próximos passos

<Columns cols={2}>
  <Card title="Explore a Referência da API" icon="code" href="/api-reference/overview">
    Todos os endpoints em todos os serviços do Portão 3, com esquemas e exemplos.
  </Card>

  <Card title="Obtenha suporte" icon="life-ring" href="mailto:suporte@portao3.com.br">
    Dúvidas sobre credenciais, tenancy ou um endpoint específico? Podemos ajudar.
  </Card>
</Columns>

<Tip>
  Travou? Envie um e-mail para [suporte@portao3.com.br](mailto:suporte@portao3.com.br) e inclua o `traceId` de qualquer resposta de erro.
</Tip>