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

# API

> Configure métodos de autenticação para conectar o RWS Integration a APIs REST

Conexões definem como o RWS Integration se autentica com APIs e serviços externos. Cada tipo de conexão lida com um padrão de autenticação diferente, desde chaves de API simples até fluxos OAuth 2.0.

Escolha o tipo de conexão com base em como a API de destino espera a autenticação:

| Tipo de Conexão                       | Quando Usar                                                      |
| ------------------------------------- | ---------------------------------------------------------------- |
| [Sem autenticação](#sem-autenticação) | API não requer nenhuma credencial                                |
| [Simple](#simple)                     | API requer apenas headers (chaves de API, auth básico)           |
| [OAuth 2.0](#oauth-2-0)               | API usa autenticação baseada em token com credenciais de cliente |
| [Session](#session)                   | API usa autenticação de sessão baseada em cookies                |
| [Google/GCP](#googlegcp)              | Conexão com serviços do Google Cloud Platform                    |

<CardGroup cols={2}>
  <Card title="Sem autenticação" icon="lock-open" href="#sem-autenticação">
    Nenhuma credencial necessária
  </Card>

  <Card title="Simple" icon="key" href="#simple">
    Apenas headers e query params
  </Card>

  <Card title="OAuth 2.0" icon="shield-halved" href="#oauth-2-0">
    Autenticação baseada em token
  </Card>

  <Card title="Session" icon="cookie" href="#session">
    Sessões baseadas em cookies
  </Card>

  <Card title="Google/GCP" icon="google" href="#googlegcp">
    Autenticação por service account
  </Card>
</CardGroup>

## Sem autenticação

A opção mais simples, e a que já vem selecionada por padrão ao criar uma nova conexão. Use quando a API não pede nenhuma credencial: as requisições são enviadas como estão, sem headers ou parâmetros extras.

### Quando usar

* APIs públicas que qualquer um pode chamar
* Endpoints de teste e sandbox
* Destinos como o webhook.site, que aceitam qualquer requisição

### Configuração

Nada a configurar: quando **Sem autenticação** está selecionado, os campos de parâmetros de header e query ficam ocultos.

<Note>
  Conexões que foram salvas anteriormente como **Simple** sem parâmetros agora aparecem como **Sem autenticação** ao serem editadas. É o mesmo comportamento, com um nome mais claro.

  Se você digitar parâmetros em **Simple** e depois trocar para **Sem autenticação**, os valores permanecem no formulário (voltar para Simple os restaura), mas não são salvos enquanto Sem autenticação estiver selecionado.
</Note>

## Simple

Tipo de conexão básico para APIs que autenticam via headers HTTP. Use quando a API requer uma chave de API estática, autenticação básica ou qualquer credencial baseada em header que não expira ou precisa de atualização.

### Quando usar

* APIs com chaves de API estáticas
* Serviços usando headers `Authorization: Basic`
* Qualquer API onde as credenciais são passadas diretamente nos headers

### Configuração

Conexões Simple requerem apenas os headers que a API de destino espera. Nenhuma configuração adicional é necessária.

**Campos obrigatórios:**

| Campo        | Descrição                                              |
| ------------ | ------------------------------------------------------ |
| Headers      | Pares chave-valor para incluir em todas as requisições |
| Query Params | Pares chave-valor para incluir como parâmetros de URL  |

## OAuth 2.0

Tipo de conexão para APIs que usam autenticação OAuth 2.0. O RWS Integration solicita um token de acesso do servidor OAuth e o inclui nas chamadas de API subsequentes.

### Quando usar

* APIs empresariais (Salesforce, HubSpot, Microsoft)
* APIs que requerem fluxo de credenciais de cliente
* Serviços onde os tokens expiram e precisam de atualização
* Qualquer API que emite tokens Bearer

### Configuração

Conexões OAuth 2.0 requerem detalhes sobre o endpoint de token, como extrair o token da resposta e como o token deve ser enviado nas requisições subsequentes.

**Campos obrigatórios:**

| Campo                         | Descrição                                                                                                                                                                                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token Type                    | Como o token é enviado: `Bearer` (header Authorization) ou `Api Token` (header personalizado)                                                                                                                                                       |
| Header Attribute Name         | O nome do header usado para enviar o token nas requisições subsequentes. Para o tipo `Bearer`, é automaticamente definido como `Authorization`. Para o tipo `Api Token`, especifique o nome do header personalizado (ex: `X-Auth-Token`, `Api-Key`) |
| Método                        | Método HTTP para a requisição de token (tipicamente `POST`)                                                                                                                                                                                         |
| Base URL                      | URL base do servidor OAuth                                                                                                                                                                                                                          |
| Path para URL de autenticação | Caminho do endpoint para requisições de token (ex: `/oauth/token`)                                                                                                                                                                                  |
| Token Path in Response        | Caminho JSON para extrair o token do corpo da resposta                                                                                                                                                                                              |

### Token Type e Header Attribute Name

O **Token Type** determina o formato usado ao enviar o token, enquanto o **Header Attribute Name** especifica qual header carrega o token:

| Token Type  | Header Attribute Name              | Header da Requisição Enviado    |
| ----------- | ---------------------------------- | ------------------------------- |
| `Bearer`    | `Authorization` (automático)       | `Authorization: Bearer {token}` |
| `Api Token` | Personalizado (ex: `X-Auth-Token`) | `X-Auth-Token: {token}`         |
| `Api Token` | Personalizado (ex: `Api-Key`)      | `Api-Key: {token}`              |

<Tip>
  **Exemplos de Token Path:**

  O token path indica ao RWS Integration onde encontrar o token de acesso na resposta do servidor OAuth.

  | Estrutura da Resposta                              | Token Path                    |
  | -------------------------------------------------- | ----------------------------- |
  | `{"access_token": "xyz"}`                          | `access_token`                |
  | `{"data": {"token": "xyz"}}`                       | `data.token`                  |
  | `{"response": {"credentials": {"bearer": "xyz"}}}` | `response.credentials.bearer` |
</Tip>

## Session

Tipo de conexão para APIs que usam autenticação baseada em sessão via cookies. O RWS Integration realiza uma requisição de login, captura os headers `Set-Cookie` e mantém a sessão para requisições subsequentes.

### Quando usar

* Sistemas legados com autenticação baseada em sessão
* APIs internas que requerem autenticação por cookie
* Serviços web com fluxos de login
* Sistemas que não suportam autenticação moderna baseada em token

### Configuração

Conexões Session requerem os detalhes do endpoint de login. O RWS Integration gerencia automaticamente a captura de cookies e o gerenciamento de sessão.

**Campos obrigatórios:**

| Campo                         | Descrição                                                   |
| ----------------------------- | ----------------------------------------------------------- |
| Método                        | Método HTTP para a requisição de login (tipicamente `POST`) |
| Base URL                      | URL base do servidor de autenticação                        |
| Path para URL de autenticação | Caminho do endpoint de login (ex: `/api/login`)             |

<Info>
  O RWS Integration captura todos os headers `Set-Cookie` da resposta de login e os inclui automaticamente em todas as requisições subsequentes para a mesma URL base.
</Info>

## Google/GCP

Tipo de conexão para serviços do Google Cloud Platform. Usa autenticação de conta de serviço para acessar APIs GCP como Google Sheets, BigQuery, Cloud Storage e outros.

### Quando usar

* Integração com Google Sheets
* Extração ou carregamento de dados do BigQuery
* Operações de arquivos no Google Drive
* Acesso ao Cloud Storage (GCS)
* Qualquer serviço de API GCP

### Configuração

Conexões GCP requerem uma conta de serviço com permissões apropriadas e os escopos OAuth para os serviços que você precisa acessar.

**Campos obrigatórios:**

| Campo                         | Descrição                                                              |
| ----------------------------- | ---------------------------------------------------------------------- |
| Google API Scopes             | Escopos OAuth necessários para os serviços GCP (um por linha)          |
| Google Service Account (JSON) | Conteúdo completo do arquivo JSON da chave da sua conta de serviço GCP |

### Escopos comuns

| Serviço                         | Escopo                                                  |
| ------------------------------- | ------------------------------------------------------- |
| Google Sheets (leitura/escrita) | `https://www.googleapis.com/auth/spreadsheets`          |
| Google Sheets (somente leitura) | `https://www.googleapis.com/auth/spreadsheets.readonly` |
| Google Drive                    | `https://www.googleapis.com/auth/drive`                 |
| BigQuery                        | `https://www.googleapis.com/auth/bigquery`              |
| Cloud Storage                   | `https://www.googleapis.com/auth/devstorage.read_write` |

### Permissões

<Warning>
  A conta de serviço deve ter permissões IAM apropriadas para os recursos que você deseja acessar. Para Google Sheets, compartilhe a planilha diretamente com o endereço de email da conta de serviço (`client_email` no JSON).
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Paginação" icon="arrows-rotate" href="/pt-br/features/extract/pagination">
    Lide com diferentes padrões de paginação
  </Card>

  <Card title="Regras de Negócio" icon="code" href="/pt-br/features/business-rules/overview">
    Transforme dados com JavaScript
  </Card>
</CardGroup>