# Autenticação A GoPag API utiliza autenticação de dois fatores para garantir a segurança das comunicações: 1. **Bearer Token (OAuth 2.0)**: Obtido via Portal GoPag ou enviado pela GoPag (Entre em contato para solicitar) 2. **Certificado mTLS (ICP-Brasil)**: Autenticação bidirecional com certificado digital > **📋 CREDENCIAMENTO NECESSÁRIO** > > Para integrar com a GoPag API, você precisará de: > > * **Bearer Token**: Exportado pelo Portal GoPag ou enviado pelo seu consultor > * **Certificado digital ICP-Brasil**: e-CPF ou e-CNPJ para mTLS > > Entre em contato com nossa equipe de suporte para iniciar o processo de credenciamento. > > 📧 Email: ## Fluxo de Autenticação ``` ┌──────────┐ ┌─────────────┐ │ Cliente │ │ GoPag API │ └────┬─────┘ └──────┬──────┘ │ │ │ 1. Conexão TLS + Certificado mTLS (ICP-Brasil) │ ├──────────────────────────────────────────────────>│ │ │ │ 2. Validação do Certificado │ │<──────────────────────────────────────────────────┤ │ │ │ 3. Requisição API + Bearer Token │ ├──────────────────────────────────────────────────>│ │ │ │ 4. Validação Token + marketplace_id │ │ │ │ 5. Resposta │ │<──────────────────────────────────────────────────┤ │ │ ``` ## Passo 1: Obter Bearer Token ### Via Portal GoPag 1. Acesse o Portal GoPag 2. Navegue até **Configurações > API** 3. Clique em **Exportar Token** 4. Copie o Bearer Token gerado ### Via Consultor O Bearer Token pode ser enviado diretamente pelo seu consultor GoPag via e-mail ou canal seguro. ### Características do Token * **Tipo**: Bearer * **Validade**: Configurável (geralmente longa duração) * **Uso**: Incluir no header `Authorization` de todas as requisições ``` Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... ``` ## Passo 2: Configurar Certificado mTLS ### Recebimento do Certificado Após o credenciamento, você receberá da equipe GoPag: 1. **Certificado Digital ICP-Brasil** (`client.crt`) * Certificado público X.509 formato PEM * Tipo: e-CPF (pessoa física) ou e-CNPJ (pessoa jurídica) * Contém o `certSerialNumber` que deve corresponder ao seu `marketplace_id` 2. **Chave Privada** (`client.key`) * Chave privada RSA 2048 bits ou superior * **NUNCA compartilhe esta chave** 3. **CA Certificate** (`ca.crt`) * Certificado da Autoridade Certificadora **⚠️ IMPORTANTE**: O certificado é emitido exclusivamente pela equipe GoPag após análise e aprovação do credenciamento. ### Instalação #### Linux/MacOS ```bash # Criar diretório para certificados sudo mkdir -p /etc/ssl/gopag # Copiar certificados sudo cp client.crt /etc/ssl/gopag/ sudo cp client.key /etc/ssl/gopag/ sudo cp ca.crt /etc/ssl/gopag/ # Definir permissões sudo chmod 644 /etc/ssl/gopag/client.crt sudo chmod 644 /etc/ssl/gopag/ca.crt sudo chmod 600 /etc/ssl/gopag/client.key sudo chown app-user:app-group /etc/ssl/gopag/client.key ``` #### Verificar Certificado ```bash # Ver informações do certificado openssl x509 -in /etc/ssl/gopag/client.crt -text -noout # Verificar serial number (deve corresponder ao marketplace_id) openssl x509 -in /etc/ssl/gopag/client.crt -serial -noout ``` ### Configuração por Linguagem #### cURL ```bash curl https://api.gopag.com.br/v1/marketplaces/abc123.../sellers \ --cert /etc/ssl/gopag/client.crt \ --key /etc/ssl/gopag/client.key \ --cacert /etc/ssl/gopag/ca.crt \ -H "Authorization: Bearer SEU_TOKEN" ``` #### PHP (com cURL) ```php $ch = curl_init('https://api.gopag.com.br/v1/marketplaces/abc123.../sellers'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_SSLCERT => '/etc/ssl/gopag/client.crt', CURLOPT_SSLKEY => '/etc/ssl/gopag/client.key', CURLOPT_CAINFO => '/etc/ssl/gopag/ca.crt', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $accessToken, 'Content-Type: application/json' ] ]); $response = curl_exec($ch); curl_close($ch); ``` #### Node.js (com axios) ```javascript const fs = require('fs'); const https = require('https'); const axios = require('axios'); const httpsAgent = new https.Agent({ cert: fs.readFileSync('/etc/ssl/gopag/client.crt'), key: fs.readFileSync('/etc/ssl/gopag/client.key'), ca: fs.readFileSync('/etc/ssl/gopag/ca.crt') }); const response = await axios.get( 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers', { httpsAgent, headers: { 'Authorization': `Bearer ${accessToken}` } } ); ``` #### Python (com requests) ```python import requests response = requests.get( 'https://api.gopag.com.br/v1/marketplaces/abc123.../sellers', cert=('/etc/ssl/gopag/client.crt', '/etc/ssl/gopag/client.key'), verify='/etc/ssl/gopag/ca.crt', headers={'Authorization': f'Bearer {access_token}'} ) ``` #### Java (com OkHttp) ```java OkHttpClient client = new OkHttpClient.Builder() .sslSocketFactory(sslContext.getSocketFactory(), trustManager) .build(); Request request = new Request.Builder() .url("https://api.gopag.com.br/v1/marketplaces/abc123.../sellers") .header("Authorization", "Bearer " + accessToken) .build(); Response response = client.newCall(request).execute(); ``` ## Passo 3: Usar nas Requisições ### Header de Autorização Inclua o Bearer Token em todas as requisições: ```http GET /v1/marketplaces/abc123.../sellers HTTP/1.1 Host: api.gopag.com.br Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc... Accept: application/json ``` ### Validação do Marketplace ID **CRÍTICO**: O `certSerialNumber` do certificado mTLS **DEVE** corresponder ao `marketplace_id` na URL. ``` ✅ Correto: - certSerialNumber: marketplace-abc123 - URL: /v1/marketplaces/marketplace-abc123/sellers ❌ Erro 401: - certSerialNumber: marketplace-abc123 - URL: /v1/marketplaces/marketplace-xyz789/sellers ``` ## Tratamento de Erros de Autenticação ### 401 Unauthorized ```json { "type": "https://httpstatuses.com/401", "title": "Unauthorized", "status": 401, "detail": "Invalid or expired access token" } ``` **Causas comuns:** * Bearer Token inválido ou expirado * Token não fornecido no header **Solução:** * Verifique se o token está correto * Solicite um novo token via Portal GoPag ou consultor ### 401 Unauthorized (Marketplace) ```json { "type": "https://httpstatuses.com/401", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" } ``` **Causas comuns:** * `certSerialNumber` não corresponde ao `marketplace_id` * Certificado mTLS inválido ou expirado **Solução:** * Verifique se o `marketplace_id` na URL está correto * Confirme que seu certificado ainda está válido * Entre em contato com suporte se necessário ### 403 Forbidden ```json { "type": "https://httpstatuses.com/403", "title": "Forbidden", "status": 403, "detail": "Insufficient permissions" } ``` **Causas comuns:** * Tentando acessar recurso de outro marketplace * Permissões insuficientes **Solução:** * Verifique se está acessando apenas recursos do seu marketplace * Entre em contato com suporte se necessário ## Segurança - Melhores Práticas ### ✅ Fazer * Armazenar certificados e chaves em locais seguros * Usar variáveis de ambiente para Bearer Token * Validar certificados SSL do servidor * Usar HTTPS em todas as comunicações * Implementar timeout em requisições * Logar tentativas de autenticação (sem expor credenciais) ### ❌ Não Fazer * Commitar certificados, chaves ou tokens no Git * Expor Bearer Token em código cliente (frontend) * Compartilhar credenciais entre ambientes * Ignorar erros de validação SSL * Armazenar tokens sem proteção * Usar certificados expirados * Fazer hard-code de credenciais ## Ambientes ### Homologação ``` Base URL: https://api-stage.gopag.com.br ``` * Use credenciais de homologação * Certificado de homologação * Sem impacto em produção ### Produção ``` Base URL: https://api.gopag.com.br ``` * Use credenciais de produção * Certificado de produção * Transações reais **⚠️ NUNCA use credenciais de produção em homologação!** ## Próximos Passos * [Testar sua Autenticação](/developers/introducao/testando.md) * [Entender Códigos de Erro](/developers/introducao/codigos-erro.md) * [Começar a Integração](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/vendedores/listar.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gopag.com.br/developers/introducao/autenticacao.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.