POST /api/v2/server-side-api/vc/transactions/

Créer une transaction de monnaie virtuelle

Crédite ou débite une ou plusieurs monnaies virtuelles pour un profil en une seule transaction atomique. Utilisez un amount positif pour créditer (accorder) et un amount négatif pour débiter (dépenser). Tous les éléments sont appliqués ensemble — si l'un échoue, aucun n'est appliqué.

Chaque code de monnaie ne peut apparaître qu'une seule fois par requête. Un crédit via ce point de terminaison crée toujours un solde sans expiration.

Header parameters

adapty-customer-user-idstring

L'identifiant unique du client dans votre système. adapty-customer-user-id ou adapty-profile-id est requis.

adapty-profile-idstring

L'identifiant unique du profil dans votre système. Meilleure option si vous travaillez avec des profils anonymes. adapty-customer-user-id ou adapty-profile-id est requis.

Idempotency-Keystring · uuid

Un UUID v4 qui rend la requête idempotente. Si vous relancez une requête avec la même clé, Adapty renvoie le résultat de la transaction originale sans modifier à nouveau les soldes. Doit être un UUID v4 valide.

Request body

Corps de la requête pour créer une transaction de monnaie virtuelle.

itemsarray of objectrequired

Ajustements de solde à appliquer de manière atomique. Chaque code de monnaie ne peut apparaître qu'une seule fois.

currency_codestringrequired

Le code de la monnaie virtuelle à ajuster.

amountintegerrequired

Le montant à appliquer. Une valeur positive crédite (accorde) la monnaie ; une valeur négative la débite (dépense). Ne peut pas être nul.

metadataobject

Paires clé-valeur optionnelles stockées avec la transaction. Maximum 5 clés. Chaque clé correspond à ^[a-z0-9_]{1,30}$, et chaque valeur comporte au plus 200 caractères.

Responses

Transaction appliquée avec succès

Schema

Résultat d'une transaction de monnaie virtuelle.

transaction_idstringrequired

Identifiant unique de la transaction créée.

balancesarray of objectrequired

Solde après transaction pour chaque monnaie affectée par cette requête (une entrée par élément dans items). Pour consulter la liste complète des soldes du profil, utilisez GET /api/v2/server-side-api/vc/balances/.

codestringrequired

Code de la monnaie virtuelle.

namestringrequired

Nom d'affichage de la monnaie virtuelle.

balanceintegerrequired

Solde total, y compris les montants actuellement retenus.

heldintegerrequired

Somme de toutes les retenues actives (montants réservés). Actuellement toujours 0.

availableintegerrequired

Solde disponible à dépenser, calculé comme balance - held.

Example

{
  "transaction_id": "0190e8a4-1c2b-7def-8abc-2c1a4b6d8e90",
  "balances": [
    {
      "code": "COINS",
      "name": "Gold Coins",
      "balance": 12950,
      "held": 0,
      "available": 12950
    }
  ]
}

Requête incorrecte. Le champ error_code identifie la cause : insufficient_balance, unknown_currency, duplicate_currency, amount_zero, balance_overflow, empty_items, ou idempotency_key_invalid.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Example

{
  "errors": [
    {
      "source": "currency_code",
      "errors": [
        "Insufficient balance for currency COINS"
      ]
    }
  ],
  "error_code": "insufficient_balance",
  "status_code": 400
}

Non autorisé. La clé API est manquante ou invalide.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Interdit. L'API serveur pour les monnaies virtuelles n'est pas activée pour cette application. Contactez le support Adapty pour en demander l'accès.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Example

{
  "errors": [
    {
      "source": null,
      "errors": [
        "Server API for virtual currencies is not enabled for this app. Contact Adapty support to request access."
      ]
    }
  ],
  "error_code": "feature_not_enabled",
  "status_code": 403
}

Profil introuvable.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Conflit. Le champ error_code identifie la cause :

idempotency_in_flight — une requête avec la même Idempotency-Key est toujours en cours de traitement. Réessayez après l'intervalle indiqué dans l'en-tête de réponse Retry-After.
duplicate_source_transaction — la transaction du store sous-jacente a déjà été créditée, elle n'est donc pas appliquée à nouveau.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Example

{
  "errors": [
    {
      "source": null,
      "errors": [
        "A similar request is being processed."
      ]
    }
  ],
  "error_code": "idempotency_in_flight",
  "status_code": 409
}

Entité non traitable. Le corps de la requête n'a pas passé la validation du schéma — par exemple, items contient plus de 20 entrées, ou une clé ou valeur de metadata ne respecte pas ses contraintes.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Trop de requêtes. La limite de débit par application ou globale a été dépassée (error_code est rate_limited). Les limites par défaut sont 600 requêtes par minute par application et 6 000 requêtes par minute globalement.

Schema

errorsarray of objectrequired

sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Erreur interne du serveur

Try it

Authorization

Header parameters

adapty-customer-user-id

adapty-profile-id

Idempotency-Key

Body

curl --request POST \
  --url 'https://api.adapty.io/api/v2/server-side-api/vc/transactions/' \
  --header 'Authorization: Api-Key YOUR_SECRET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "currency_code": "COINS",
        "amount": -10
      }
    ]
  }'

const response = await fetch('https://api.adapty.io/api/v2/server-side-api/vc/transactions/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "items": [
      {
        "currency_code": "COINS",
        "amount": -10
      }
    ]
  }),
});
const data = await response.json();

import requests

response = requests.post('https://api.adapty.io/api/v2/server-side-api/vc/transactions/', headers={
    'Authorization': 'Api-Key YOUR_SECRET_API_KEY',
    'Content-Type': 'application/json',
}, json={
      "items": [
        {
          "currency_code": "COINS",
          "amount": -10
        }
      ]
    })
data = response.json()