Proceso de autenticación

Bienvenido a la guía de autenticación para acceder a las APIs de Orkestral.

Sigue las instrucciones a continuación para configurar tus credenciales, obtener un token de acceso y realizar solicitudes autenticadas a las APIs de la plataforma.

Objetivo

Orientar a los clientes sobre cómo obtener, renovar y utilizar un token de acceso para consumir los recursos protegidos de las APIs de Orkestral.

La autenticación actual utiliza OAuth 2.0 con las credenciales del cliente, el correo electrónico y la contraseña del usuario.

Entornos

Entorno	URL base
Pruebas	https://api-qas.orkestralpay.com.br
Producción	https://api.orkestralpay.com

Utiliza solamente la URL correspondiente al entorno proporcionado para tu integración.

Requisitos previos

Para realizar la autenticación, es necesario:

• tener una cuenta activa en Orkestral;
• tener un usuario vinculado al comercio;
• disponer del correo electrónico y la contraseña de ese usuario;
• disponer del client_id y el client_secret proporcionados por Orkestral durante el onboarding;
• utilizar una conexión HTTPS.

Credenciales utilizadas

El proceso utiliza dos conjuntos de credenciales.

Credenciales del cliente OAuth

Las credenciales del cliente identifican la aplicación que solicita el token:

• client_id;
• client_secret.

Estas credenciales se envían en el encabezado Authorization mediante Basic Auth.

Credenciales del usuario

Las credenciales del usuario identifican a quien realiza la autenticación:

• username: correo electrónico registrado en Orkestral;
• password: contraseña correspondiente al usuario.

Diferencia entre el client secret y la Clave secreta

El client_secret de la autenticación OAuth no es la misma Clave secreta que se muestra en la página Integración de la plataforma.

• El client_secret se utiliza para autenticar el cliente OAuth y obtener tokens.
• La Clave secreta de la página Integración se utiliza para validar el checksum de las notificaciones.

aviso

No utilices la Clave secreta de las notificaciones como client_secret.

Obtener un token de acceso

Para obtener un token, envía una solicitud HTTP POST a:

/oauth2/token

Encabezado de autenticación

El encabezado debe contener el client_id y el client_secret con el formato Basic Auth:

Authorization: Basic Base64(client_id:client_secret)

La mayoría de los clientes HTTP generan automáticamente la codificación Base64.

Cuerpo de la solicitud

Envía los parámetros con el formato application/x-www-form-urlencoded.

Parámetro	Obligatorio	Descripción
username	Sí	Correo electrónico registrado en Orkestral
password	Sí	Contraseña del usuario
grant_type	Sí	Debe tener el valor password

Ejemplo con cURL

curl --request POST \
  "${BASE_URL}/oauth2/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=${USER_EMAIL}" \
  --data-urlencode "password=${USER_PASSWORD}" \
  --data-urlencode "grant_type=password"

El parámetro --user de cURL crea automáticamente el encabezado Basic Auth.

precaución

No incluyas credenciales directamente en el código fuente ni en scripts versionados.

Respuesta exitosa

Cuando las credenciales son válidas, la API devuelve una respuesta similar a:

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Campos de la respuesta

Campo	Descripción
access_token	JWT utilizado para acceder a los recursos protegidos
refresh_token	Token usado para renovar el acceso sin reenviar la contraseña
token_type	Tipo de token, actualmente Bearer
expires_in	Tiempo de validez del access token, en segundos

Validez de los tokens

La configuración actual utiliza los siguientes períodos:

Entorno	Access token
Pruebas	30 minutos
Producción	15 minutos

El refresh token tiene una validez de 24 horas.

El cliente no debe asumir un valor fijo para el tiempo de expiración. Utiliza siempre el valor devuelto en el campo expires_in.

Utilizar el access token

Incluye el access token en el encabezado Authorization de cada solicitud protegida:

Authorization: Bearer access_token

Ejemplo de creación de una transacción:

curl --request POST \
  "${BASE_URL}/transaction/payin/${MERCHANT_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "IP: ${CLIENT_IP}" \
  --data @transaction.json

El MERCHANT_ID indicado en la URL debe corresponder al comercio presente en el token. Se rechazará cualquier intento de operar en nombre de otro comercio.

Renovar el access token

Cuando el access token expire, utiliza el refresh token para obtener un nuevo conjunto de tokens.

Envía una nueva solicitud HTTP POST a:

/oauth2/token

Cuerpo de la renovación

Parámetro	Obligatorio	Descripción
grant_type	Sí	Debe tener el valor refresh_token
refresh_token	Sí	Token devuelto en la autenticación anterior

Ejemplo con cURL

curl --request POST \
  "${BASE_URL}/oauth2/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

La renovación devuelve un nuevo access token y un nuevo refresh token.

Después de una renovación exitosa:

• sustituye el access token anterior;
• almacena el nuevo refresh token devuelto;
• actualiza el tiempo de expiración utilizando el nuevo expires_in.

Tratamiento recomendado para un token expirado

Al recibir una respuesta 401 Unauthorized:

1. Comprueba si hay un refresh token disponible.
2. Realiza un único intento de renovación.
3. Si la renovación se completa correctamente, repite la solicitud original con el nuevo access token.
4. Si la renovación falla, finaliza la sesión y solicita una nueva autenticación.

Evita ciclos infinitos de renovación y repetición de la solicitud.

Códigos de respuesta

Endpoint de autenticación

Estado	Descripción
200 OK	Token generado o renovado correctamente
400 Bad Request	Parámetro ausente, solicitud inválida o correo/contraseña incorrectos
401 Unauthorized	client_id o client_secret no válido
403 Forbidden	Usuario no activado, cuenta bloqueada o contraseña expirada

Recursos protegidos

Estado	Descripción
401 Unauthorized	Token ausente, no válido, expirado o perteneciente a otro comercio
403 Forbidden	Usuario autenticado sin permiso para realizar la operación

Errores específicos de autenticación

Usuario no activado

{
  "error": "user_not_activated",
  "message": "User not activated"
}

El usuario debe completar la activación de la cuenta antes de autenticarse.

Cuenta bloqueada temporalmente

{
  "error": "account_temporarily_locked",
  "message": "Account temporarily locked"
}

Después de diez intentos no válidos en un período de quince minutos, la cuenta se bloquea temporalmente durante treinta minutos.

Contraseña expirada

{
  "error": "password_expired",
  "message": "Password expired",
  "token": "token-para-cambiar-la-contrasena"
}

La contraseña del usuario expira después de noventa días.

El campo token de esta respuesta está destinado al proceso de cambio de contraseña. No debe utilizarse como access token.

Cierre de la sesión

Al cerrar una sesión:

• elimina el access token del almacenamiento local;
• elimina el refresh token;
• elimina las cookies y demás información de la sesión;
• no reutilices tokens almacenados anteriormente.

Si existe la sospecha de que el client_secret, la contraseña o los tokens se han visto comprometidos, interrumpe la integración y contacta al equipo responsable de Orkestral.

Buenas prácticas de seguridad

• Utiliza siempre HTTPS.
• Nunca envíes tokens o credenciales en parámetros de la URL.
• No incluyas credenciales directamente en el código fuente.
• Utiliza un gestor de secretos.
• No almacenes tokens en logs.
• No expongas el client_secret en aplicaciones frontend.
• Restringe el acceso al client_secret únicamente a los servicios responsables de la autenticación.
• Utiliza el valor de expires_in para controlar la validez del token.
• Renueva el token solamente cuando sea necesario.
• No compartas tokens entre entornos.
• Utiliza credenciales diferentes para pruebas y producción.
• Implementa alertas para intentos repetidos de autenticación sin éxito.
• En caso de compromiso, sustituye las credenciales junto con el equipo de Orkestral.