Elementi essenziali per l’integrazione API

Configura questi aspetti condivisi prima di integrare una risorsa dell’API DEUNA. Le stesse regole di ambiente, rete, nuovo tentativo e timeout valgono per ordini, pagamenti, utenti, link di pagamento e abbonamenti.

Ambienti#

Sandbox e produzione sono isolati e usano credenziali, dati ed endpoint webhook differenti.

Consulta Autenticazione e ambienti per i tipi di credenziali, la rotazione e gli esempi di richiesta.

Raccolta Postman#

Usa la raccolta Postman di DEUNA per esplorare le richieste prima di sviluppare un client.

Apri la raccolta DEUNA in Postman

1. Accedi a Postman e crea un fork della raccolta nel tuo workspace.
2. Seleziona l’ambiente sandbox o produzione.
3. Imposta merchant_id, public_api_keye private_api_key con i valori dell’ambiente.
4. Inizia da un’operazione del catalogo degli endpoint.

Indirizzi IP#

Preferisci una allowlist di domini quando la policy di rete lo consente. Se il ricevitore di webhook o un provider di pagamento o antifrode richiede una allowlist IP, usa gli indirizzi seguenti.

Codici di risposta#

Le operazioni riuscite restituiscono una risposta 2xx . Una risposta 4xx indica che autenticazione, autorizzazioni, dati o stato della risorsa devono cambiare. Una risposta 5xx è un errore temporaneo di DEUNA o del provider e deve essere ritentata solo quando l’operazione può essere ripetuta in sicurezza.

Usa il riferimento per risposte e codici di errore per identificare causa, policy di nuovo tentativo e azione correttiva.

Richieste idempotenti#

Invia una X-Idempotency-Key stabile per ogni operazione distinta che crea o modifica lo stato di un pagamento. Riutilizza la stessa chiave e un corpo identico dopo un errore di rete o un timeout del client. Usa una chiave nuova per un nuovo tentativo di business.

X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/json

Consulta Creare un pagamento per il contratto specifico dell’acquisto e l’esempio di nuovo tentativo.

Timeout del client#

Un timeout del client significa che il chiamante ha smesso di attendere; non dimostra che il pagamento sia fallito. L’elaborazione può proseguire attraverso controlli antifrode, instradamento e provider dopo la disconnessione.

Quando una richiesta di pagamento scade:

1. Mantieni bloccato il fulfillment e contrassegna il tentativo come in attesa di riconciliazione nel tuo sistema.
2. Conserva l’ID ordine, il corpo e la chiave di idempotenza originale.
3. Ritenta solo quando l’operazione è idonea, con la stessa chiave e un corpo identico.
4. Riconcilia lo stato finale da un webhook verificato o da una ricerca ordine appropriata nel catalogo degli endpoint.
5. Mostra il risultato riconciliato all’acquirente e completa eventuali storni o rimborsi prima del fulfillment.