Authentication API

Portal do Desenvolvedor — Getnet

1. Visão Geral

O serviço de Authentication é a porta de entrada para todas as integrações com a plataforma Getnet. Ele é responsável por confirmar a identidade de quem está fazendo uma requisição e, em troca, emitir um token de acesso temporário.

Pense nele como o "crachá digital" da sua integração: sem ele, nenhum outro serviço da plataforma aceita suas requisições. Com ele em mãos — e enquanto estiver dentro do prazo de validade —, você pode transitar livremente pelos demais recursos disponíveis.

2. Contexto e Casos de Uso

Use este serviço sempre antes de chamar qualquer outra API da Getnet. O token gerado aqui é o requisito fundamental para todas as demais operações.

Cenários típicos

Situação	O que acontece
Sua aplicação acabou de iniciar	Chame a API de autenticação para obter o primeiro token antes de qualquer outra operação.
O token atual está prestes a expirar	Renove o token antes que ele expire para evitar interrupções no fluxo do usuário final.
Uma requisição retornou `401 Unauthorized`	O token expirou ou foi mal formado — obtenha um novo e repita a operação.
Integração com um novo escopo de produto	Solicite um token com o `scope` correspondente ao conjunto de APIs que deseja utilizar.

3. Fluxo Principal

O fluxo é direto: sua aplicação apresenta suas credenciais e recebe um token que deve ser reutilizado em todas as chamadas subsequentes até o fim do tempo de vida informado.

text

[Sua Aplicação] ──600;">POST /token──────────────────────► [Authentication API]
                  (credenciais nos headers + body)
                ◄──200 OK { access_token, expires_in }──

[Sua Aplicação] ──Requisição + Authorization header──► [Demais APIs Getnet]
                ◄──Resposta da operação────────────────

  ↺  Repita o 600;">POST /token quando expires_in se aproximar do fim.

text

[Sua Aplicação] ──600;">POST /token──────────────────────► [Authentication API]
                  (credenciais nos headers + body)
                ◄──200 OK { access_token, expires_in }──

[Sua Aplicação] ──Requisição + Authorization header──► [Demais APIs Getnet]
                ◄──Resposta da operação────────────────

  ↺  Repita o 600;">POST /token quando expires_in se aproximar do fim.

Etapas detalhadas

Prepare suas credenciais — Tenha em mãos o client_id, client_secret, channel e scope fornecidos pela Getnet no momento do credenciamento.
Identifique o solicitante — Monte o corpo da requisição com os dados do usuário ou sistema que está iniciando a sessão (branch, login, name, enrollment_number).
Envie a requisição — Faça um POST /token com as credenciais nos headers e os dados no body.
Guarde o token — Armazene o access_token retornado de forma segura na memória da sua aplicação.
Use o token — Inclua o access_token no header Authorization de todas as chamadas às demais APIs.
Controle a validade — Monitore o campo expires_in (em segundos) e renove o token antes que ele expire.

4. Pré-requisitos

Antes de utilizar este serviço, você precisará de:

Credenciais de acesso — client_id e client_secret emitidos pela Getnet durante o processo de credenciamento. Guarde-os com segurança; nunca os exponha no lado cliente (browser, app mobile).
Canal de acesso (channel) — Identificador do canal pelo qual sua aplicação se comunica com a Getnet (ex.: canal de parceiro, canal direto). Definido pela Getnet no onboarding.
Escopo (scope) — Define quais grupos de APIs você está autorizado a consumir. Cada escopo é liberado conforme o contrato comercial vigente.
Acesso à rede — Conexão com os endpoints:
- Homologação: https://api-homologacao.getnet.com.br:443
- Produção: https://api-backoffice.getnet.com.br:443

⚠️ Atenção: Nunca utilize credenciais de produção em ambiente de homologação e vice-versa.

5. Guia de Integração Rápida

Cenário: Obter o primeiro token de acesso (happy path)

Endpoint: POST /v1/token

O que enviar

Headers obrigatórios:

Header	Exemplo	Descrição
`client_id`	`seu-client-id`	Identificador da sua aplicação na Getnet.
`client_secret`	`seu-client-secret`	Senha/chave secreta da sua aplicação.
`channel`	`parceiro-xyz`	Canal de acesso definido no credenciamento.
`scope`	`oob`	Escopo de acesso às APIs desejadas.
`Content-Type`	`application/json`	Formato do corpo da requisição.

Corpo da requisição (JSON):

json

{
  "branch": "0001",
  "login": "usuario.exemplo",
  "name": "Usuário Exemplo",
  "enrollment_number": "123456"
}

json

{
  "branch": "0001",
  "login": "usuario.exemplo",
  "name": "Usuário Exemplo",
  "enrollment_number": "123456"
}

O que esperar em retorno

Status 200 OK:

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": "3600"
}

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": "3600"
}

Como usar o token retornado:

A partir deste momento, inclua o access_token em todas as suas requisições às demais APIs:

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

💡 O token é válido por 3600 segundos (1 hora). Programe sua aplicação para renová-lo antes desse prazo.

6. Regras de Negócio

Campos obrigatórios

Headers — todos obrigatórios:

client_id
client_secret
channel
scope

Body — todos obrigatórios (podem ser enviados como string vazia):

branch — Agência ou filial do solicitante. Utilizado para auditoria e rastreabilidade das ações do canal.
login — Identificador do usuário na organização. Utilizado para auditoria e rastreabilidade das ações do canal.
name — Nome legível do usuário. Utilizado para auditoria e rastreabilidade das ações do canal.
enrollment_number — Número de matrícula do usuário. Utilizado para auditoria e rastreabilidade das ações do canal.

💡 Esses campos existem para que o canal consiga identificar quem realizou cada ação na plataforma. Se o canal não tiver essa necessidade de rastreabilidade interna, todos os campos podem ser enviados como string vazia (""). O que não é permitido é omiti-los ou enviá-los como null.

Validade do token

O campo expires_in é retornado como string numérica representando segundos.
Você não deve reaproveitar um token expirado. A tentativa resultará em 401 Unauthorized.
Não existe endpoint de "refresh token" — um novo token deve ser gerado com uma nova chamada ao POST /token.

Escopo e permissões

O escopo (scope) determina quais APIs você pode consumir com aquele token.
Chamar uma API fora do escopo concedido resultará em 403 Forbidden.
Caso precise ampliar o escopo, entre em contato com a Getnet para revisão contratual.

7. Tratamento de Erros

Tabela de erros

Código HTTP	Nome	O que significa	O que fazer
`400`	Bad Request	A requisição está malformada: um header obrigatório está ausente, vazio ou com valor inválido; ou um campo do body não é permitido.	Verifique os headers e o body. Consulte o campo `details` da resposta para identificar exatamente qual campo está com problema.
`401`	Unauthorized	As credenciais fornecidas (`client_id` e `client_secret`) são inválidas ou estão ausentes.	Confirme se está usando as credenciais corretas para o ambiente (homologação ou produção). Nunca misture credenciais entre ambientes.
`403`	Forbidden	Autenticação válida, mas sua aplicação não tem permissão para acessar o recurso solicitado com o escopo atual.	Verifique o `scope` enviado. Se o acesso for legítimo, solicite a liberação do escopo à equipe Getnet.
`500`	Internal Server Error	Erro inesperado no lado da plataforma Getnet.	Tente novamente após alguns instantes. Se o problema persistir, acione o suporte da Getnet com o timestamp e os headers da requisição para facilitar o diagnóstico.

Exemplos de resposta de erro

400 — Header ausente ou inválido:

json

{
  "status_code": 400,
  "name": "HeaderValidation",
  "message": "Bad Request",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "channel is invalid",
      "description_detail": "\"channel\" is not allowed to be empty"
    }
  ]
}

json

{
  "status_code": 400,
  "name": "HeaderValidation",
  "message": "Bad Request",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "channel is invalid",
      "description_detail": "\"channel\" is not allowed to be empty"
    }
  ]
}

401 — Credenciais inválidas:

json

{
  "status_code": 401,
  "name": "Unauthorized",
  "message": "Unauthorized",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-401",
      "description": "Unauthorized",
      "description_detail": "CODE 01"
    }
  ]
}

json

{
  "status_code": 401,
  "name": "Unauthorized",
  "message": "Unauthorized",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-401",
      "description": "Unauthorized",
      "description_detail": "CODE 01"
    }
  ]
}

💡 Dica: Sempre inspecione o array details nas respostas de erro. Ele contém o campo exato e a razão da falha, agilizando muito o diagnóstico.

8. Glossário

Termo	Definição
access_token	Credencial temporária emitida pela API de autenticação após validação bem-sucedida. Deve ser enviada em todas as requisições às APIs da plataforma.
expires_in	Tempo de vida do `access_token`, em segundos, contado a partir do momento da emissão. Após esse prazo, o token é inválido e um novo deve ser solicitado.
client_id	Identificador único da aplicação (cliente) registrada na Getnet. Análogo a um "nome de usuário" para sistemas.
client_secret	Chave secreta associada ao `client_id`. Deve ser tratada com o mesmo cuidado de uma senha — nunca exposta em logs ou código-fonte.
channel	Canal de comunicação pelo qual a aplicação acessa a plataforma Getnet (ex.: parceiro, integrador, canal direto). Definido durante o onboarding.
scope	Conjunto de permissões que determina quais APIs e recursos a aplicação pode acessar com o token gerado.
branch	Código da agência ou filial associada ao solicitante do token. Utilizado para fins de rastreabilidade e auditoria.
enrollment_number	Número de matrícula do usuário dentro da organização. Identifica unicamente o operador ou sistema que iniciou a sessão.
login	Identificador textual do usuário na organização (nome de usuário/login corporativo).
error_code	Código interno da Getnet que categoriza o tipo de erro ocorrido (ex.: `GENERIC-400`, `GENERIC-401`). Útil ao acionar o suporte técnico.
Homologação	Ambiente de testes, separado da produção, onde integrações são validadas sem impacto real. URL: `api-homologacao.getnet.com.br`.
Produção	Ambiente real, com transações e dados verdadeiros. URL: `api-backoffice.getnet.com.br`.

Nesta página

Authentication API