Autenticação e chaves de API

As credenciais da DEUNA respondem a duas perguntas diferentes: qual aplicação do comerciante está sendo utilizada., e, quando aplicável, Qual cliente autenticado está utilizando-o. Inicie identificando o ponto de execução da solicitação e a autoridade necessária, e, em seguida, confirme os requisitos exatos. catálogo de endpoints.

Decida qual credencial usarPerguntar à Athia sobre isto#

Faça as seguintes perguntas:

1. A solicitação é executada em um navegador ou aplicativo móvel? Use a chave API pública ou o contexto da aplicação documentado para o SDK ou endpoint. Nunca coloque a chave privada nesse cliente.
2. Seu backend executa uma operação de comerciante? Use a chave API privada em X-Api-Key para chamadas entre servidores, como criar, recuperar, capturar, reembolsar ou cancelar um pedido.
3. É necessário que a DEUNA reconheça o cliente autenticado? Adicione o token de acesso de curta duração do cliente como Authorization: Bearer … apenas quando o endpoint suporta. Isso fornece ao pedido o contexto específico do cliente para recursos como dados de perfil, endereços, instrumentos de pagamento armazenados ou fluxos de carteira autorizados pelo cliente.

Escolha a credencial corretaPerguntar à Athia sobre isto#

Chave API pública: integração no lado do clientePerguntar à Athia sobre isto#

Utilize a chave pública quando o código da DEUNA for executado em um ambiente não confiável, como um navegador ou aplicativo móvel. Exemplos de uso incluem a inicialização de um widget ou SDK da DEUNA, bem como a identificação do comerciante e do ambiente para tokenização e experiências de pagamento suportadas no lado do cliente.

A chave pública é intencionalmente segura para ser incluída na configuração do cliente, mas não é uma chave secreta e não concede permissão para realizar capturas, reembolsos, cancelamentos ou outras operações no backend do comerciante. Mantenha a chave pública associada ao ambiente de sandbox ou produção correto.

Chave API privada: autorização entre servidoresPerguntar à Athia sobre isto#

Utilize a chave API privada quando seu backend confiável fizer uma chamada para um endpoint do comerciante. As operações do comerciante que utilizam a autorização por chave API exigem a chave privada em X-Api-Key, nunca em 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 acesso do cliente: contexto de usuário autenticadoPerguntar à Athia sobre isto#

Utilize um token de acesso do cliente quando a operação deve ser executada no contexto de um cliente da DEUNA autenticado e o endpoint suporta autenticação via Bearer. Envie-o no Authorization cabeçalho:

Authorization: Bearer USER_ACCESS_TOKEN

O token Bearer é a resposta. qual cliente Está em funcionamento. A chave da API fornece as respostas. qual aplicação ou sistema de backend do comerciante está a contactar. Dependendo do ponto de extremidade, uma solicitação do cliente pode, portanto, exigir tanto a chave da API do cliente como o token Bearer do cliente.

Não envie um token Bearer apenas porque o cabeçalho está disponível. Não utilize a chave privada do comerciante como um token Bearer, e não trate um token do cliente como autorização para operações exclusivas do comerciante. Se o seu backend encaminha o contexto do cliente, faça-o apenas para um endpoint que suporte explicitamente essa combinação.

AmbientesPerguntar à Athia sobre isto#

Sandbox e produção são isolados. Cada ambiente possui seu próprio URL base, chaves de API, configuração do comerciante, conexões, dados e estado de pagamento.

Armazene e gire chavesPerguntar à Athia sobre isto#

• Armazene chaves privadas em um gerenciador de segredos ou em uma configuração de tempo de execução protegida.
• Defina o acesso ao serviço e ao ambiente que precisam da chave.
• Edite credenciais de logs de solicitação e anexos de suporte.
• Implante uma chave substituta antes de revogar a chave antiga para que o tráfego de produção continue com segurança.
• Coordene a emissão e rotação de chaves com seu operador administrativo autorizado ou DEUNA TAM.

Falhas de autenticaçãoPerguntar à Athia sobre isto#

Uma falha de autorização normalmente retorna 401 Unauthorized ou 403 Forbidden. Antes de tentar novamente, verifique:

1. A credencial está presente no cabeçalho documentado.
2. A chave pertence ao ambiente e ao comerciante solicitado.
3. O endpoint oferece suporte ao método de autorização que você enviou.
4. A chave ou token do cliente não expirou ou foi revogada.
5. Qualquer contexto necessário de comerciante, loja ou cliente está presente.

Não tente novamente um erro de autorização indefinidamente. Preservar a resposta request_id quando disponível e inclua-o ao entrar em contato com o suporte.

Limites de taxaPerguntar à Athia sobre isto#

A DEUNA não aplica um limite de solicitações por segundo para todas as integrações. A API Gateway avalia os limites configurados como um número máximo de solicitações dentro de um período de tempo. O limite efetivo pode variar de acordo com o comerciante, o ambiente, o método HTTP e o endpoint.

Quando uma solicitação excede um limite aplicável, o gateway retorna 429 Too Many Requests com o Retry-After header. A resposta em nível de rota tem a seguinte estrutura:

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"
}

Os campos da resposta podem variar quando uma proteção em nível de gateway rejeita a solicitação. Considere o código de status HTTP e o Retry-After header como autoritativos.

Alça 429 Trate as respostas com segurança

1. Pare de enviar solicitações por pelo menos o número de segundos especificado em Retry-After.
2. Tente novamente com retrocesso exponencial e jitter, em vez de liberar imediatamente o tráfego em espera como um novo pico.
3. Para a mesma operação de pagamento, reutilize a chave de idempotência original e o corpo da solicitação exatamente igual.
4. Coordene o controle de tráfego entre os workers e as instâncias da aplicação; loops de repetição por processo podem exceder um limite compartilhado para o comerciante ou endpoint.
5. Se 429 As respostas são enviadas após a redução do tráfego, preservando o corpo da resposta e o ID da solicitação, e entre em contato com o suporte da DEUNA ou com seu Gerente de Contas Técnicas (TAM).

Solicite um aumento do limite

Peça ao suporte da DEUNA ou ao seu TAM para revisar o limite antes de um aumento planejado no tráfego. Inclua:

• O ambiente e o ID do comerciante.
• Os métodos HTTP e endpoints afetados.
• As taxas de solicitação sustentadas e de pico esperadas, a duração do pico e a data de lançamento planejada.
• Os endereços IP públicos ou CIDRs de saída utilizados pelos sistemas do comerciante que se comunicam com a DEUNA.

Não inclua chaves de API, tokens Bearer ou outros segredos em solicitações de suporte.

ContinuarPerguntar à Athia sobre isto#