Autenticação e chaves de API

As credenciais DEUNA identificam o comerciante e o ambiente usado por uma integração. A autorização necessária depende do endpoint e do chamador, portanto verifique o painel de autorização no catálogo de endpoints antes de implementar uma solicitação.

Escolha a credencial correta#

Autorização de back-end do comerciante#

As operações do comerciante que usam autorização de chave de API esperam a chave privada em X-Api-Key.

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

Alguns endpoints também aceitam um Authorization cabeçalho para transportar a identidade do cliente:

Authorization: Bearer USER_ACCESS_TOKEN

O token Bearer não substitui uma chave de API privada necessária. Envie-o somente quando o endpoint documentar o suporte do Bearer e a operação precisar de contexto de cliente autenticado, como instrumentos armazenados ou métodos de pagamento específicos do cliente.

Ambientes#

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

Armazene e gire chaves#

• 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ção#

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 taxa#

Quando uma solicitação autenticada excede a taxa de solicitação permitida, a API retorna 429 Too Many Requests. Honra Retry-After quando estiver presente, recue em vez de enviar uma série de novas tentativas e reutilize a chave e o corpo de idempotência originais para a mesma tentativa de pagamento. Os limites podem variar de acordo com a conta e o endpoint.

Continuar#