Claves de autenticación y API

Las credenciales de DEUNA responden a dos preguntas diferentes: **¿qué aplicación del comercio está realizando la llamada?**y, cuando corresponda, **¿qué cliente registrado la está utilizando?**Comience por determinar dónde se ejecuta la solicitud y qué autoridad necesita, y luego confirme el requisito exacto en el catálogo de endpoints.

Decide qué credencial utilizarPreguntar a Athia sobre esto#

Responda a estas preguntas en orden:

1. ¿La solicitud se ejecuta en un navegador o en una aplicación móvil? Utilice la clave API pública o el contexto de la aplicación documentado para el SDK o el punto final. Nunca coloque la clave privada en ese cliente.
2. ¿Su backend realiza una operación de comercio? Utilice la clave API privada en X-Api-Key para llamadas entre servidores, como la creación, recuperación, captura, reembolso o anulación de un pedido.
3. ¿Es necesario que DEUNA reconozca al cliente registrado? Añada el token de acceso del cliente de corta duración como Authorization: Bearer … solo cuando el punto final lo admita. Esto proporciona a la solicitud el contexto específico del cliente para recursos como datos de perfil, direcciones, instrumentos de pago almacenados o flujos de billetera autorizados por el cliente.

Elija la credencial correctaPreguntar a Athia sobre esto#

Clave API pública: integración del lado del clientePreguntar a Athia sobre esto#

Utilice la clave API pública cuando el código de DEUNA se ejecuta en un cliente no de confianza, como un navegador o una aplicación móvil. Los usos típicos incluyen la inicialización de un widget o SDK de DEUNA, así como la identificación del comerciante y el entorno para la tokenización y las experiencias de pago compatibles con el cliente.

La clave pública está diseñada para ser incluida en la configuración del cliente, pero no es una clave secreta y no otorga permiso para realizar capturas, reembolsos, anulaciones u otras operaciones del lado del comerciante. Mantenga la clave pública asociada al entorno de sandbox o producción correcto.

Clave API privada: autorización entre servidoresPreguntar a Athia sobre esto#

Utilice la clave API privada cuando su backend de confianza llama a un punto final del comerciante. Las operaciones del comerciante que utilizan la autorización mediante API requieren la clave privada en X-Api-Key, nunca en Authorization: Bearer ….

curl --request GET \
  --url https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY"

const response = await fetch("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", {
  method: "GET",
  headers: {
    "X-Api-Key": "YOUR_PRIVATE_API_KEY"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
    headers={
        "X-Api-Key": "YOUR_PRIVATE_API_KEY"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: YOUR_PRIVATE_API_KEY"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN"))
      .header("X-Api-Key", "YOUR_PRIVATE_API_KEY")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "YOUR_PRIVATE_API_KEY")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Token de usuario: contexto de usuario autenticadoPreguntar a Athia sobre esto#

Utilice un token de acceso del cliente cuando la operación debe actuar en el contexto de un cliente de DEUNA autenticado y el punto final admite el soporte de "Bearer". Envíe este token en el Authorization encabezado:

Authorization: Bearer USER_ACCESS_TOKEN

El token "Bearer" responde a la pregunta ¿qué cliente está actuando. La clave API responde a la pregunta ¿qué aplicación o backend del comerciante está llamando. Dependiendo del punto final, una solicitud del cliente puede requerir tanto una clave de API de la aplicación como el token "Bearer" del cliente.

No envíe un token "Bearer" para un flujo de invitado simplemente porque el encabezado está disponible. No utilice una clave privada del comerciante como token "Bearer" y no trate un token de cliente como autoridad para operaciones exclusivas del comerciante. Si su backend pasa el contexto del cliente, páselo solo a un punto final que lo admita explícitamente.

AmbientesPreguntar a Athia sobre esto#

Sandbox y producción están aislados. Cada entorno tiene su propia URL base, claves de API, configuración del comerciante, conexiones, datos y estado de pago.

Almacenar y rotar clavesPreguntar a Athia sobre esto#

• Almacene las claves privadas en un administrador de secretos o en una configuración de tiempo de ejecución protegida.
• Acceso de alcance al servicio y entorno que necesita la clave.
• Redactar credenciales de registros de solicitudes y archivos adjuntos de soporte.
• Implemente una clave de reemplazo antes de revocar la clave anterior para que el tráfico de producción continúe de manera segura.
• Coordina la emisión y rotación de claves con tu operador Administrador autorizado o DEUNA TAM.

Fallos de autenticaciónPreguntar a Athia sobre esto#

Un error de autorización normalmente regresa 401 Unauthorized o 403 Forbidden. Antes de volver a intentarlo, verifique:

1. La credencial está presente en el encabezado documentado.
2. La clave pertenece al entorno y al comerciante solicitados.
3. El punto final admite el método de autorización que envió.
4. La clave o token de cliente no ha caducado ni ha sido revocado.
5. Cualquier contexto de comerciante, tienda o cliente requerido está presente.

No vuelva a intentar un error de autorización indefinidamente. Preservar la respuesta request_id cuando esté disponible e inclúyalo cuando se comunique con el soporte.

Límites de velocidadPreguntar a Athia sobre esto#

DEUNA no aplica un valor de "request-per-second" público a todas las integraciones. El API Gateway evalúa los límites configurados como un número máximo de solicitudes dentro de un período de tiempo. El límite efectivo puede variar según el comerciante, el entorno, el método HTTP y el punto final.

Cuando una solicitud excede un límite aplicable, el gateway devuelve 429 Too Many Requests con Retry-After encabezado. La respuesta a nivel de ruta tiene esta forma:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1

{
  "error": "rate_limit_exceeded",
  "message": "maximum requests",
  "code": 429,
  "endpoint": "/merchants/orders",
  "total_requests": 101,
  "retry_after": "1s"
}

Los campos de respuesta pueden variar cuando una medida de seguridad a nivel de gateway rechaza la solicitud. Consulte el código de estado HTTP y Retry-After encabezado como la fuente de información.

Manejar 429 maneje las respuestas de forma segura

1. Deje de enviar solicitudes durante al menos el número de segundos especificados en Retry-After.
2. intente de nuevo con retroceso exponencial y jitter en lugar de liberar inmediatamente el tráfico en cola como una nueva oleada.
3. Para la misma operación de pago, reutilice la clave de idempotencia original y el cuerpo de la solicitud exacto.
4. Coordine el control de tráfico entre trabajadores e instancias de aplicación; los bucles de reintento por proceso pueden superar un límite compartido para un comerciante o punto final.
5. si 429 Las respuestas se reciben después de reducir el tráfico, conserve el cuerpo de la respuesta y el ID de la solicitud, y luego póngase en contacto con el Soporte de DEUNA o con su Administrador Técnico (TAM).

Solicite un aumento de límite

Solicite a DEUNA Support o a su TAM que revise el límite antes de un aumento de tráfico planificado. Incluya:

• El entorno y el ID del comerciante.
• Los métodos HTTP y puntos finales afectados.
• Las tasas de solicitud sostenidas y máximas esperadas, la duración de la oleada y la fecha de implementación planificada.
• Las direcciones IP públicas o rangos CIDR de salida utilizados por los sistemas del comerciante que se comunican con DEUNA.

No incluya claves de API, tokens Bearer u otros secretos en una solicitud de soporte.

ContinuarPreguntar a Athia sobre esto#