# Trocar código OAuth por token > `POST /api/v0/oauth/token` · Referência interativa: https://developers.superfrete.com/referencia#exchangeOAuthToken - **Method:** `POST` - **Path:** `/api/v0/oauth/token` - **Operation ID:** `exchangeOAuthToken` - **Tags:** Autenticação O fluxo OAuth tem duas etapas: o seller autoriza a sua aplicação no navegador e você recebe um **código de autorização**; depois o seu backend troca esse código por um **token de acesso** nesta rota. Para usar o fluxo, peça ao time de integrações o `client_id` e o `client_secret` da sua aplicação e informe a `redirect_uri` que vai receber o código. ## Passo 1: pedir a autorização do seller Abra no navegador do seller a página de autorização do ambiente: - **Sandbox:** `https://sandbox.superfrete.com/#/auth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&state={state}` - **Produção:** `https://web.superfrete.com/#/auth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&state={state}` | Parâmetro | Obrigatório | Descrição | | -------------- | ----------- | ------------------------------------------------------------------------------------------------------ | | `client_id` | Sim | Identificador numérico da sua aplicação. | | `redirect_uri` | Sim | URL de retorno. Precisa começar com a URL cadastrada na SuperFrete. | | `state` | Não | Valor aleatório gerado por você. Volta igual no retorno; confira do seu lado para se proteger de CSRF. | Quando o seller clica em **Autorizar**, a SuperFrete faz um `GET` **do servidor dela** para a URL cadastrada com `?code={code}&state={state}` e, em seguida, leva o navegador do seller para o mesmo endereço. A sua URL precisa responder `2xx` a esse `GET` servidor a servidor; se ela falhar, a autorização falha. > **Atenção** > > O `code` vale por **10 minutos** e só pode ser trocado uma vez. Ele não é o token de acesso. ## Passo 2: trocar o código pelo token Chame esta rota a partir do seu backend, nunca do navegador, porque ela leva o `client_secret`. O corpo pode ir em JSON ou em `application/x-www-form-urlencoded`. A `redirect_uri` precisa ser **idêntica** à cadastrada. O token devolvido **não expira** e não há refresh token. Ele deixa de valer quando o seller remove a integração no painel. O token dá acesso a todas as rotas desta API para a conta do seller; não existem escopos. ## Effective servers - `https://sandbox.superfrete.com` Sandbox (testes, etiquetas sem validade) - `https://api.superfrete.com` Produção ## Authentication No authentication required. ## Header parameters - **`User-Agent` (required)**: `string` Nome da sua aplicação com um e-mail de contato técnico, no formato `Aplicação (email@exemplo.com)`. Hoje só [Listar pedidos](https://developers.superfrete.com/referencia/md/listOrders.md) recusa um valor fora desse formato, mas envie em todas as rotas. **Example:** ```json "MinhaLoja (dev@minhaloja.com.br)" ``` ## Request body **Required:** `true` **Content type:** `application/json` schema: `OAuthTokenRequest` - **`client_id` (required)**: `string` Identificador numérico da sua aplicação, fornecido pela SuperFrete. - **`client_secret` (required)**: `string` Segredo da sua aplicação, fornecido pela SuperFrete. Nunca exponha no front-end. - **`code` (required)**: `string` Código recebido no Passo 1. Vale por 10 minutos e só pode ser trocado uma vez. - **`grant_type` (required)**: `string`, possible values: `"authorization_code"` - **`redirect_uri` (required)**: `string` Idêntica à URL cadastrada na SuperFrete. - **`state`**: `string` Aceito e ignorado pela SuperFrete. Valide o `state` do seu lado no retorno do Passo 1. **Example:** ```json { "grant_type": "authorization_code", "client_id": "1700000000", "client_secret": "9f86d081884c7d659a2feaa0c55ad015", "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIza0NLR3F6bFBGZkNFajJYMVRrb2IwN1NOMk0yIiwiaWF0IjoxNzMwMjk0MDAwLCJleHAiOjE3MzAyOTQ2MDB9.c2lnbmF0dXJl", "state": "a1b2c3d4", "redirect_uri": "https://minhaplataforma.com.br/superfrete/callback" } ``` **Content type:** `application/x-www-form-urlencoded` *Schema `OAuthTokenRequest` is shown above.* **Example:** ```json { "grant_type": "authorization_code", "client_id": "", "client_secret": "", "redirect_uri": "", "code": "", "state": "" } ``` ## Responses ### 200 Token emitido. **Content type:** `application/json` - **`access_token` (required)**: `string` Token de acesso. Use no header `Authorization: Bearer {access_token}`. - **`expires_in` (required)**: `string`, possible values: `"never"` Sempre `never`. O token não expira. - **`token_type` (required)**: `string`, possible values: `"Bearer"` **Example:** ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIza0NLR3F6bFBGZkNFajJYMVRrb2IwN1NOMk0yIiwiaWF0IjoxNzMwMjk0MTIwfQ.c2lnbmF0dXJl", "expires_in": "never", "token_type": "Bearer" } ``` ### 400 Parâmetro ausente ou inválido. Os valores de `error` possíveis são: - `invalid_request`: falta `grant_type`, `client_id`, `client_secret`, `redirect_uri` ou `code`, ou o `code` não pôde ser lido. - `unsupported_grant_type`: `grant_type` diferente de `authorization_code`. **Content type:** `application/json` schema: `OAuthError` - **`error` (required)**: `string`, possible values: `"invalid_request", "unsupported_grant_type", "invalid_client", "unauthorized_client", "server_error"` Código do erro OAuth. - **`error_description` (required)**: `string` - **`http_status` (required)**: `integer` - **`message` (required)**: `string` **Example: missingParameter** Parâmetro ausente ```json { "error": "invalid_request", "http_status": 400, "error_description": "Required parameter 'client_id' was missing", "message": "Required parameter 'client_id' was missing" } ``` **Example: unsupportedGrantType** grant_type não suportado ```json { "error": "unsupported_grant_type", "http_status": 400, "error_description": "The grant type requested was not recognized", "message": "The grant type requested was not recognized" } ``` ### 401 Credenciais ou código recusados. Os valores de `error` possíveis são: - `invalid_client`: `client_id`, `client_secret` ou `redirect_uri` não conferem com o cadastro. - `unauthorized_client`: o `code` passou dos 10 minutos de validade. **Content type:** `application/json` *Schema `OAuthError` is shown above.* **Example: invalidClient** Credenciais do cliente inválidas ```json { "error": "invalid_client", "http_status": 401, "error_description": "Client authentication failed", "message": "Client authentication failed" } ``` **Example: expiredCode** Código expirado ```json { "error": "unauthorized_client", "http_status": 401, "error_description": "Authorization code has expired", "message": "Authorization code has expired" } ``` ### 500 Erro interno. Também acontece quando o mesmo `code` é trocado pela segunda vez. **Content type:** `application/json` *Schema `OAuthError` is shown above.* **Example:** ```json { "error": "server_error", "http_status": 500, "error_description": "An server error has occurred", "message": "An server error has occurred" } ``` ## Schemas - `OAuthError` — shown above. - `OAuthTokenRequest` — shown above.