API de Autenticación

Portal del Desarrollador — Getnet

1. Visión General

El servicio de Authentication es la puerta de entrada para todas las integraciones con la plataforma Getnet. Es responsable de confirmar la identidad de quien realiza una solicitud y, a cambio, emitir un token de acceso temporal.

Piénsalo como el "carnet digital" de tu integración: sin él, ningún otro servicio de la plataforma aceptará tus solicitudes. Con él en mano —y mientras esté dentro del plazo de validez—, puedes transitar libremente por los demás recursos disponibles.

2. Contexto y Casos de Uso

Utiliza este servicio siempre antes de llamar a cualquier otra API de Getnet. El token generado aquí es el requisito fundamental para todas las demás operaciones.

Escenarios típicos

Situación	Qué sucede
Tu aplicación acaba de iniciar	Llama a la API de autenticación para obtener el primer token antes de cualquier otra operación.
El token actual está por expirar	Renueva el token antes de que expire para evitar interrupciones en el flujo del usuario final.
Una solicitud devolvió `401 Unauthorized`	El token expiró o estaba mal formado — obtén uno nuevo y repite la operación.
Integración con un nuevo alcance de producto	Solicita un token con el `scope` correspondiente al conjunto de APIs que deseas utilizar.

3. Flujo Principal

El flujo es directo: tu aplicación presenta sus credenciales y recibe un token que debe ser reutilizado en todas las llamadas subsiguientes hasta el fin del tiempo de vida informado.

text

[Tu Aplicación] ──600;">POST /token──────────────────────► [Authentication API]
                  (credenciales en headers + body)
                ◄──200 OK { access_token, expires_in }──

[Tu Aplicación] ──Solicitud + Authorization header──► [Otras APIs Getnet]
                ◄──Respuesta de la operación────────────────

  ↺  Repite el 600;">POST /token cuando expires_in esté por finalizar.

text

[Tu Aplicación] ──600;">POST /token──────────────────────► [Authentication API]
                  (credenciales en headers + body)
                ◄──200 OK { access_token, expires_in }──

[Tu Aplicación] ──Solicitud + Authorization header──► [Otras APIs Getnet]
                ◄──Respuesta de la operación────────────────

  ↺  Repite el 600;">POST /token cuando expires_in esté por finalizar.

Pasos detallados

Prepara tus credenciales — Ten a mano el client_id, client_secret, channel y scope proporcionados por Getnet durante el onboarding.
Identifica al solicitante — Arma el cuerpo de la solicitud con los datos del usuario o sistema que inicia la sesión (branch, login, name, enrollment_number).
Envía la solicitud — Realiza un POST /token con las credenciales en los headers y los datos en el body.
Guarda el token — Almacena el access_token retornado de forma segura en la memoria de tu aplicación.
Usa el token — Incluye el access_token en el header Authorization de todas las llamadas a las demás APIs.
Controla la validez — Monitorea el campo expires_in (en segundos) y renueva el token antes de que expire.

4. Prerrequisitos

Antes de utilizar este servicio, necesitarás:

Credenciales de acceso — client_id y client_secret emitidos por Getnet durante el proceso de onboarding. Guárdalos de forma segura; nunca los expongas en el lado cliente (navegador, app móvil).
Canal de acceso (channel) — Identificador del canal por el cual tu aplicación se comunica con Getnet (ej.: canal de socio, canal directo). Definido por Getnet en el onboarding.
Alcance (scope) — Define qué grupos de APIs estás autorizado a consumir. Cada alcance se libera según el contrato comercial vigente.
Acceso a la red — Conexión con los endpoints:
- Homologación: https://api-homologacao.getnet.com.br:443
- Producción: https://api-backoffice.getnet.com.br:443

⚠️ Atención: Nunca utilices credenciales de producción en ambiente de homologación y viceversa.

5. Guía Rápida de Integración

Escenario: Obtener el primer token de acceso (happy path)

Endpoint: POST /v1/token

Qué enviar

Headers obligatorios:

Header	Ejemplo	Descripción
`client_id`	`tu-client-id`	Identificador de tu aplicación en Getnet.
`client_secret`	`tu-client-secret`	Contraseña/clave secreta de tu aplicación.
`channel`	`socio-xyz`	Canal de acceso definido en el onboarding.
`scope`	`oob`	Alcance de acceso a las APIs deseadas.
`Content-Type`	`application/json`	Formato del cuerpo de la solicitud.

Cuerpo de la solicitud (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"
}

Qué esperar en retorno

Status 200 OK:

json

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

json

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

Cómo usar el token retornado:

A partir de este momento, incluye el access_token en todas tus solicitudes a las demás APIs:

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

💡 El token es válido por 3600 segundos (1 hora). Programa tu aplicación para renovarlo antes de ese plazo.

6. Reglas de Negocio

Campos obligatorios

Headers — todos obligatorios:

client_id
client_secret
channel
scope

Body — todos obligatorios (pueden enviarse como string vacío):

branch — Agencia o sucursal del solicitante. Utilizado para auditoría y trazabilidad de las acciones del canal.
login — Identificador del usuario en la organización. Utilizado para auditoría y trazabilidad de las acciones del canal.
name — Nombre legible del usuario. Utilizado para auditoría y trazabilidad de las acciones del canal.
enrollment_number — Número de matrícula del usuario. Utilizado para auditoría y trazabilidad de las acciones del canal.

💡 Estos campos existen para que el canal pueda identificar quién realizó cada acción en la plataforma. Si el canal no tiene esa necesidad de trazabilidad interna, todos los campos pueden enviarse como string vacío (""). Lo que no está permitido es omitirlos o enviarlos como null.

Validez del token

El campo expires_in se retorna como string numérica representando segundos.
No debes reutilizar un token expirado. El intento resultará en 401 Unauthorized.
No existe endpoint de "refresh token" — se debe generar un nuevo token con una nueva llamada a POST /token.

Alcance y permisos

El alcance (scope) determina qué APIs puedes consumir con ese token.
Llamar a una API fuera del alcance concedido resultará en 403 Forbidden.
Si necesitas ampliar el alcance, contacta a Getnet para revisión contractual.

7. Manejo de Errores

Tabla de errores

Código HTTP	Nombre	Qué significa	Qué hacer
`400`	Bad Request	La solicitud está malformada: un header obligatorio está ausente, vacío o con valor inválido; o un campo del body no está permitido.	Verifica los headers y el body. Consulta el campo `details` de la respuesta para identificar exactamente qué campo tiene el problema.
`401`	Unauthorized	Las credenciales proporcionadas (`client_id` y `client_secret`) son inválidas o están ausentes.	Confirma que estás usando las credenciales correctas para el ambiente (homologación o producción). Nunca mezcles credenciales entre ambientes.
`403`	Forbidden	Autenticación válida, pero tu aplicación no tiene permiso para acceder al recurso solicitado con el alcance actual.	Verifica el `scope` enviado. Si el acceso es legítimo, solicita la liberación del alcance al equipo de Getnet.
`500`	Internal Server Error	Error inesperado en la plataforma Getnet.	Intenta nuevamente después de unos instantes. Si el problema persiste, contacta al soporte de Getnet con el timestamp y los headers de la solicitud para facilitar el diagnóstico.

Ejemplos de respuesta de error

400 — Header ausente o 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 — Credenciales 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"
    }
  ]
}

💡 Consejo: Siempre inspecciona el array details en las respuestas de error. Contiene el campo exacto y la razón de la falla, agilizando mucho el diagnóstico.

8. Glosario

Término	Definición
access_token	Credencial temporal emitida por la API de autenticación tras una validación exitosa. Debe enviarse en todas las solicitudes a las APIs de la plataforma.
expires_in	Tiempo de vida del `access_token`, en segundos, contado desde el momento de la emisión. Tras ese plazo, el token es inválido y se debe solicitar uno nuevo.
client_id	Identificador único de la aplicación (cliente) registrada en Getnet. Análogo a un "nombre de usuario" para sistemas.
client_secret	Clave secreta asociada al `client_id`. Debe tratarse con el mismo cuidado que una contraseña — nunca exponerla en logs o código fuente.
channel	Canal de comunicación por el cual la aplicación accede a la plataforma Getnet (ej.: socio, integrador, canal directo). Definido durante el onboarding.
scope	Conjunto de permisos que determina qué APIs y recursos puede acceder la aplicación con el token generado.
branch	Código de la agencia o sucursal asociada al solicitante del token. Utilizado para fines de trazabilidad y auditoría.
enrollment_number	Número de matrícula del usuario dentro de la organización. Identifica de forma única al operador o sistema que inició la sesión.
login	Identificador textual del usuario en la organización (nombre de usuario/login corporativo).
error_code	Código interno de Getnet que categoriza el tipo de error ocurrido (ej.: `GENERIC-400`, `GENERIC-401`). Útil al contactar soporte técnico.
Homologação	Entorno de pruebas, separado de producción, donde las integraciones se validan sin impacto real. URL: `api-homologacao.getnet.com.br`.
Produção	Entorno real, con transacciones y datos verdaderos. URL: `api-backoffice.getnet.com.br`.

En esta página

API de Autenticación