🔑 Autenticação e Credenciais de Acesso

Para utilizar as APIs da Credsystem é necessário se autenticar usando o token de acesso obtido através do sistema de autenticação OAuth2.

O sistema de autenticação OAuth2 da Credsystem suporta a interação server-to-server entre uma aplicação web e os serviços da Credsystem. Para este cenário, você precisa de uma conta de serviço, que é uma conta impessoal que pertence à sua aplicação e não a um usuário individual. Administradores poderão solicitar que uma conta de serviço possa ter autorização para acessar dados de uma conta de usuário.

Para mais detalhes de como uma aplicação pode completar o processo de autenticação OAuth2 server-to-server através do protocolo HTTP, consulte este guia de Autenticação.

É obrigatório enviar o token obtido no header de suas requisições através da chave Authorization.

⚠️ Segurança Crítica

NUNCA exponha suas credenciais (client_id e client_secret) em código client-side (frontend, aplicativos móveis) ou em repositórios públicos. Estas credenciais devem ser armazenadas exclusivamente em servidores backend seguros.

📌 Importante

Os tokens JWT possuem tempo de expiração limitado. Implemente um sistema de renovação automática de tokens quando necessário. Tokens expirados retornarão erro 401 Unauthorized.

📋 Como Solicitar Credenciais

🌐 Solicitação pelo Portal do Desenvolvedor

A forma oficial de solicitar suas credenciais de API é através do nosso Portal do Desenvolvedor:

🚀 Solicitar Credenciais de API

Processo de Solicitação:

Acesse o Portal - Faça login no Portal do Desenvolvedor Credsystem
Preencha o Formulário - Clique no botão acima e preencha:
- E-mail corporativo (preenchido automaticamente)
- E-mail do contato comercial responsável
- APIs que deseja acessar
- Ambiente (Homologação ou Produção)
- Justificativa de negócio
Aguarde Aprovação - Sua solicitação será analisada em até 72 horas úteis
Receba os E-mails - Após aprovação, você receberá:
- ✅ Convite do SharePoint com documentação técnica (primeiro)
- ✅ E-mail com credenciais (Client ID e Secret)

📧 E-mails que Você Receberá

Após a aprovação da sua solicitação, você receberá dois e-mails importantes nesta ordem:

1️⃣ Convite do SharePoint (Primeiro)

Assunto: Credenciais de API - Portal do Desenvolvedor Credsystem

Conteúdo do e-mail:

Olá [Seu Nome],

Você foi convidado para acessar a documentação técnica da Credsystem no SharePoint!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📂 ACESSO AO SHAREPOINT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Botão: Aceitar Convite]

Este convite expira em 30 dias.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dúvidas? Entre em contato:
📧 suporte.tecnico@credsystem.com.br
🌐 https://desenvolvedor.credsystem.com.br

Atenciosamente,
Equipe Credsystem

2️⃣ E-mail com Credenciais de API (Após aceitar o convite)

Assunto: Credenciais de API - Portal do Desenvolvedor Credsystem

Conteúdo do e-mail:

Olá [Seu Nome],

Suas credenciais para acesso às APIs da Credsystem foram aprovadas!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔐 CREDENCIAIS DE ACESSO
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Ambiente: [Homologação/Produção]

Client ID: af9c9e3ca3aa4390b86083ebe5f60449
Client Secret: 5a948d61-c135-4671-9d6a-d0a2324b97e2

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 APIs APROVADAS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Autenticação OAuth 2.0
✓ Venda em Loja Física
✓ Arrecadação em Loja v2
[... outras APIs aprovadas]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Dúvidas? Entre em contato:
📧 suporte.tecnico@credsystem.com.br
🌐 https://desenvolvedor.credsystem.com.br

Atenciosamente,
Equipe Credsystem

💡 Importante

Você receberá dois e-mails separados nesta ordem:

Convite SharePoint (primeiro) - aceite para acessar documentação técnica completa
Credenciais de API (segundo) - Client ID e Secret para começar a integração

📋 Checklist de Recebimento

Após solicitar suas credenciais, verifique se recebeu:

✅ Convite do SharePoint para documentação técnica
✅ E-mail com Client ID e Client Secret

Não recebeu algum dos e-mails?

Verifique sua pasta de spam/lixo eletrônico
Aguarde até 72 horas úteis após a solicitação
Entre em contato com seu representante comercial da Credsystem

🔐 Sistemas de Autenticação

A Credsystem oferece dois sistemas de autenticação OAuth2 dependendo do tipo de integração:

1️⃣ Red Hat SSO (Keycloak)

Usado para a maioria das APIs da Credsystem. Suporta três fluxos de autenticação:

🔑 Client Credentials Grant (Máquina-a-Máquina)

Quando usar:

Integração entre sistemas backend
APIs de servidor para servidor
Jobs automatizados e processos batch
Microserviços

Características:

✅ Sem envolvimento de usuário
✅ Ideal para aplicações server-side
✅ Token de curta duração (300 segundos)
✅ Renovação automática disponível

👤 Password Grant (Usuário e Senha)

Quando usar:

Aplicações web com login de usuário
Apps móveis com tela de autenticação
Cenários onde o usuário fornece credenciais diretamente

Características:

✅ Autenticação com username e password
✅ Access token + Refresh token
✅ Ideal para aplicações com usuários finais

🔄 Refresh Token

Quando usar:

Access token expirou (erro 401)
Manter usuário logado sem redigitar senha
Renovação proativa antes da expiração

Características:

✅ Renovação sem nova autenticação
✅ Mantém sessão ativa
✅ Refresh token válido por 1800 segundos

2️⃣ Oracle IDCS (Identity Cloud Service)

Usado especificamente para integrações com redes credenciadas.

Quando usar:

Integração com aplicações Oracle
APIs de redes credenciadas parceiras
Autenticação para lojas físicas específicas

Características:

✅ Autenticação via Basic Auth
✅ Scope específico por loja/rede
✅ Client Credentials Grant
✅ Token com validade configurável

📝 Exemplos de Autenticação

Red Hat SSO - Client Credentials

curl -X POST "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"

const getAccessToken = async () => {
  const response = await fetch(
    'https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: 'SEU_CLIENT_ID',
        client_secret: 'SEU_CLIENT_SECRET',
      }),
    }
  );
  
  const data = await response.json();
  return data.access_token;
};

// Usar o token nas requisições
const token = await getAccessToken();
const apiResponse = await fetch('https://api.credsystem.com.br/endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

import requests

def get_access_token():
    url = "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token"
    
    payload = {
        'grant_type': 'client_credentials',
        'client_id': 'SEU_CLIENT_ID',
        'client_secret': 'SEU_CLIENT_SECRET'
    }
    
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    
    response = requests.post(url, data=payload, headers=headers)
    return response.json()['access_token']

# Usar o token nas requisições
token = get_access_token()
api_response = requests.get(
    'https://api.credsystem.com.br/endpoint',
    headers={'Authorization': f'Bearer {token}'}
)

import java.net.http.*;
import java.net.URI;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class CredsystemAuth {
    public static String getAccessToken() throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = "grant_type=client_credentials" +
                     "&client_id=SEU_CLIENT_ID" +
                     "&client_secret=SEU_CLIENT_SECRET";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        JsonObject jsonObject = JsonParser.parseString(response.body()).getAsJsonObject();
        return jsonObject.get("access_token").getAsString();
    }
    
    public static void main(String[] args) throws Exception {
        String token = getAccessToken();
        
        // Usar o token nas requisições
        HttpRequest apiRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://api.credsystem.com.br/endpoint"))
            .header("Authorization", "Bearer " + token)
            .GET()
            .build();
    }
}

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Text.Json;
using System.Threading.Tasks;

public class CredsystemAuth
{
    private static readonly HttpClient client = new HttpClient();
    
    public static async Task<string> GetAccessToken()
    {
        var values = new Dictionary<string, string>
        {
            { "grant_type", "client_credentials" },
            { "client_id", "SEU_CLIENT_ID" },
            { "client_secret", "SEU_CLIENT_SECRET" }
        };
        
        var content = new FormUrlEncodedContent(values);
        var response = await client.PostAsync(
            "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token",
            content
        );
        
        var responseString = await response.Content.ReadAsStringAsync();
        var jsonDoc = JsonDocument.Parse(responseString);
        return jsonDoc.RootElement.GetProperty("access_token").GetString();
    }
    
    public static async Task Main()
    {
        string token = await GetAccessToken();
        
        // Usar o token nas requisições
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
        var apiResponse = await client.GetAsync("https://api.credsystem.com.br/endpoint");
    }
}

<?php

function getAccessToken() {
    $url = "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token";
    
    $data = array(
        'grant_type' => 'client_credentials',
        'client_id' => 'SEU_CLIENT_ID',
        'client_secret' => 'SEU_CLIENT_SECRET'
    );
    
    $options = array(
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($data)
        )
    );
    
    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $response = json_decode($result, true);
    
    return $response['access_token'];
}

// Usar o token nas requisições
$token = getAccessToken();

$opts = array(
    'http' => array(
        'header' => "Authorization: Bearer " . $token
    )
);
$context = stream_context_create($opts);
$api_response = file_get_contents('https://api.credsystem.com.br/endpoint', false, $context);
?>

Red Hat SSO - Password Grant

cURL
JavaScript
Python

curl -X POST "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "username=usuario@exemplo.com" \
  -d "password=SenhaSegura123!" \
  -d "scope=openid profile email"

const authenticateUser = async (username, password) => {
  const response = await fetch(
    'https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'password',
        client_id: 'SEU_CLIENT_ID',
        client_secret: 'SEU_CLIENT_SECRET',
        username: username,
        password: password,
        scope: 'openid profile email'
      }),
    }
  );
  
  const data = await response.json();
  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresIn: data.expires_in
  };
};

import requests

def authenticate_user(username, password):
    url = "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token"
    
    payload = {
        'grant_type': 'password',
        'client_id': 'SEU_CLIENT_ID',
        'client_secret': 'SEU_CLIENT_SECRET',
        'username': username,
        'password': password,
        'scope': 'openid profile email'
    }
    
    response = requests.post(url, data=payload)
    data = response.json()
    
    return {
        'access_token': data['access_token'],
        'refresh_token': data['refresh_token'],
        'expires_in': data['expires_in']
    }

Red Hat SSO - Refresh Token

cURL
JavaScript
Python

curl -X POST "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "refresh_token=SEU_REFRESH_TOKEN"

const refreshAccessToken = async (refreshToken) => {
  const response = await fetch(
    'https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        client_id: 'SEU_CLIENT_ID',
        client_secret: 'SEU_CLIENT_SECRET',
        refresh_token: refreshToken
      }),
    }
  );
  
  const data = await response.json();
  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresIn: data.expires_in
  };
};

def refresh_access_token(refresh_token):
    url = "https://sso.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token"
    
    payload = {
        'grant_type': 'refresh_token',
        'client_id': 'SEU_CLIENT_ID',
        'client_secret': 'SEU_CLIENT_SECRET',
        'refresh_token': refresh_token
    }
    
    response = requests.post(url, data=payload)
    data = response.json()
    
    return {
        'access_token': data['access_token'],
        'refresh_token': data['refresh_token'],
        'expires_in': data['expires_in']
    }

Oracle IDCS - Client Credentials

cURL
JavaScript
Python

# Exemplo para LOJA-A
curl -X POST "https://idcs-0fe1bec59571471484a8896c1a0d7a62.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic BASE64_CLIENT_ID_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=LOJA-A-HML-cc3e9c9b-7d64-4ff3-a86a-1d7teste19ac13"

Gerando Basic Auth

O header Authorization: Basic deve conter client_id:client_secret em Base64:

echo -n "client_id:client_secret" | base64

const getIDCSToken = async (clientId, clientSecret, scope) => {
  const basicAuth = btoa(`${clientId}:${clientSecret}`);
  
  const response = await fetch(
    'https://idcs-0fe1bec59571471484a8896c1a0d7a62.identity.oraclecloud.com/oauth2/v1/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': `Basic ${basicAuth}`
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        scope: scope
      }),
    }
  );
  
  const data = await response.json();
  return data.access_token;
};

// Exemplo de uso
const token = await getIDCSToken(
  'SEU_CLIENT_ID',
  'SEU_CLIENT_SECRET',
  'LOJA-A-HML-cc3e9c9b-7d64-4ff3-a86a-1d7teste19ac13'
);

import requests
import base64

def get_idcs_token(client_id, client_secret, scope):
    url = "https://idcs-0fe1bec59571471484a8896c1a0d7a62.identity.oraclecloud.com/oauth2/v1/token"
    
    # Gerar Basic Auth
    credentials = f"{client_id}:{client_secret}"
    basic_auth = base64.b64encode(credentials.encode()).decode()
    
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': f'Basic {basic_auth}'
    }
    
    payload = {
        'grant_type': 'client_credentials',
        'scope': scope
    }
    
    response = requests.post(url, data=payload, headers=headers)
    return response.json()['access_token']

# Exemplo de uso
token = get_idcs_token(
    'SEU_CLIENT_ID',
    'SEU_CLIENT_SECRET',
    'LOJA-A-HML-cc3e9c9b-7d64-4ff3-a86a-1d7teste19ac13'
)

🔒 Segurança e Boas Práticas

⚠️ Segurança Crítica

NUNCA exponha suas credenciais (client_id e client_secret) em:

❌ Código client-side (frontend, aplicativos móveis)
❌ Repositórios públicos (GitHub, GitLab, etc.)
❌ Logs ou mensagens de erro
❌ URLs ou query parameters

✅ Armazene credenciais exclusivamente em servidores backend seguros

✅ Checklist de Segurança

⏱️ Gerenciamento de Tokens

Tipo de Token	Validade Padrão	Ação Recomendada
Access Token (Keycloak)	300s (5 min)	Renovar automaticamente
Refresh Token (Keycloak)	1800s (30 min)	Usar para renovação
Access Token (IDCS)	Configurável	Verificar no response

📌 Importante

Os tokens JWT possuem tempo de expiração limitado. Implemente um sistema de renovação automática de tokens quando necessário. Tokens expirados retornarão erro 401 Unauthorized.

⚡ Problemas Comuns

❌ Erro 401 - Unauthorized

Possíveis causas:

Token expirado
Credenciais inválidas
Client ID ou Secret incorretos
Realm incorreto

Solução:

Verifique se as credenciais estão corretas
Tente renovar o token com refresh_token
Verifique se o realm está correto na URL
Confirme que o token está sendo enviado no header Authorization: Bearer <token>

❌ Erro 400 - Bad Request

Possíveis causas:

Parâmetros obrigatórios faltando
Formato incorreto do body
grant_type inválido

Solução:

Verifique todos os parâmetros obrigatórios
Confirme que o Content-Type é application/x-www-form-urlencoded
Valide o grant_type (deve ser: client_credentials, password ou refresh_token)

❌ Erro 403 - Forbidden

Possíveis causas:

Client sem permissões necessárias
Scope não autorizado
Ambiente incorreto

Solução:

Verifique se o client tem as roles necessárias
Confirme que está usando o ambiente correto (homologação/produção)
Entre em contato com o suporte para revisar permissões

🔄 Próximos Passos

Agora que você tem suas credenciais e sabe como se autenticar:

📋 Como Solicitar Credenciais​

🌐 Solicitação pelo Portal do Desenvolvedor​

📧 E-mails que Você Receberá​

1️⃣ Convite do SharePoint (Primeiro)​

2️⃣ E-mail com Credenciais de API (Após aceitar o convite)​

📋 Checklist de Recebimento​

🔐 Sistemas de Autenticação​

1️⃣ Red Hat SSO (Keycloak)​

🔑 Client Credentials Grant (Máquina-a-Máquina)​

👤 Password Grant (Usuário e Senha)​

🔄 Refresh Token​

2️⃣ Oracle IDCS (Identity Cloud Service)​

📝 Exemplos de Autenticação​

Red Hat SSO - Client Credentials​

Red Hat SSO - Password Grant​

Red Hat SSO - Refresh Token​

Oracle IDCS - Client Credentials​

🔒 Segurança e Boas Práticas​

✅ Checklist de Segurança​

⏱️ Gerenciamento de Tokens​

⚡ Problemas Comuns​

🔄 Próximos Passos​

📋 Como Solicitar Credenciais

🌐 Solicitação pelo Portal do Desenvolvedor

📧 E-mails que Você Receberá

1️⃣ Convite do SharePoint (Primeiro)

2️⃣ E-mail com Credenciais de API (Após aceitar o convite)

📋 Checklist de Recebimento

🔐 Sistemas de Autenticação

1️⃣ Red Hat SSO (Keycloak)

🔑 Client Credentials Grant (Máquina-a-Máquina)

👤 Password Grant (Usuário e Senha)

🔄 Refresh Token

2️⃣ Oracle IDCS (Identity Cloud Service)

📝 Exemplos de Autenticação

Red Hat SSO - Client Credentials

Red Hat SSO - Password Grant

Red Hat SSO - Refresh Token

Oracle IDCS - Client Credentials

🔒 Segurança e Boas Práticas

✅ Checklist de Segurança

⏱️ Gerenciamento de Tokens

⚡ Problemas Comuns

🔄 Próximos Passos