# Platform API (/it/platform-api)





La Tapaya Platform API Le consente di gestire esercenti, pagamenti e impostazioni dell'organizzazione dal Suo server. Gli
endpoint necessari dipendono da come la Sua app accetta i pagamenti; non tutti gli integratori hanno bisogno di tutte le sezioni.

<SwaggerBanner href="https://api.tapaya.com/openapi/index.html" />

<Callout title="Gli enum sono numerici" type="info">
  Campi come `businessTypeId`, `countryId`, `currencyId`, `documentType` e `refundReasonId` sono tutti enum
  numerici. I valori possibili per ciascuno sono elencati nella
  [documentazione Swagger](https://api.tapaya.com/openapi/index.html), non in questa guida.
</Callout>

## Quali sezioni La riguardano [#which-sections-apply-to-you]

| La Sua integrazione                                                                                                        | [Autenticazione dell'esercente](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations) | [Onboarding degli esercenti](/platform-api/merchant_onboarding) | [Reportistica e pagamenti](/platform-api/reporting) |
| -------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------: | :-------------------------------------------------: |
| **Accept SDK** (incorporato nella Sua app)                                                                                 |                                                       🟢 Obbligatoria                                                      |                          🟡 Facoltativo                         |                    🟡 Facoltativa                   |
| **Solo app Tapaya Terminal** ([intent/deeplink](/in-store/integration/card_terminal#integrate-without-the-sdk), senza SDK) |                                                      ⚪ Non necessaria                                                      |                          🟡 Facoltativo                         |                    🟡 Facoltativa                   |
| **Solo reportistica / back office**                                                                                        |                                                      ⚪ Non necessaria                                                      |                         ⚪ Non necessario                        |                   🟢 Obbligatoria                   |

* **Autenticazione dell'esercente**: l'SDK si autentica come esercente utilizzando un token di accesso richiesto dal Suo backend. Non
  è necessaria per le integrazioni con Tapaya Terminal: l'esercente accede direttamente all'app Tapaya Terminal, quindi non esiste
  alcuna sessione SDK che il Suo backend debba autenticare.
* **Onboarding degli esercenti**: facoltativo per ogni integrazione di pagamento, in presenza o online. Un esercente completa l'onboarding una sola volta e
  quell'onboarding copre entrambi i canali. L'onboarding avviene tramite la Tapaya Platform UI, un invito ospitato o l'API, a seconda di
  chi deve raccogliere i dati dell'esercente.
* **Reportistica e pagamenti**: facoltativa per entrambe le integrazioni di pagamento se crea dashboard proprie;
  obbligatoria (e sufficiente da sola) se si limita a recuperare i dati di reportistica senza una propria integrazione di pagamento.

Tutte le righe richiedono comunque l'[autenticazione](#authentication) con un Server Secret Token.

<Callout title="Usare la Secret key per il Checkout" type="info">
  Il [Checkout online](/online/integration/api_integration#authentication) accetta la stessa **Secret key** della
  [pagina API Keys](https://platform.tapaya.com/api-keys/), qui chiamata Server Secret Token.
  Il Checkout richiede `Authorization: Bearer <secret-key>` e associa l'organizzazione a un esercente.
  Consulti [Autenticazione di Checkout](/online/integration/api_integration#authentication) per i requisiti di associazione dell'esercente.
</Callout>

## Ambienti [#environments]

La Tapaya Platform API supporta i seguenti ambienti:

* **Produzione:** Ospitato su `https://api.tapaya.com`. Questo ambiente utilizza account reali e movimenta fondi reali. &#x2A;*Non utilizzi l'ambiente di produzione per i test.**
* **Sandbox:** Ospitata su `https://api.sandbox.tapaya.com`. Questo ambiente Le consente di testare l'integrazione senza alcun movimento di fondi reali. Per saperne di più sui test, consulti la nostra [guida a test / sandbox](/in-store/getting-started/testing).

## Autenticazione [#authentication]

Le richieste alla Platform API utilizzano il Suo Server Secret Token, indicato come **Secret key** nella pagina API Keys. Lo passi così com'è nell'header `Authorization` delle Sue richieste HTTP.

```http
Authorization: REPLACE_ME
```

Per autenticare la Sua piattaforma presso l'API, deve generare una **Secret key**, qui chiamata Server Secret Token, nella [pagina API Keys](https://platform.tapaya.com/api-keys/) e sostituire con essa *REPLACE\_ME* qui sopra.

<Callout title="Avviso di sicurezza" type="warn">
  Il Suo Server Secret Token ha privilegi elevati. **Non** lo esponga **mai** nel codice lato client (app mobili, browser
  web). Deve essere utilizzato esclusivamente dai Suoi server backend sicuri.
</Callout>

Se un token viene compromesso, lo revochi dalla [pagina API Keys](https://platform.tapaya.com/api-keys/); la revoca
ha effetto immediato e non può essere annullata. Generi un token sostitutivo prima o dopo la revoca, a seconda delle esigenze;
non esiste un'azione di “rotazione” sul posto, quindi aggiorni la configurazione del Suo backend con il nuovo token una volta creato.

<Callout title="Nessuna limitazione dell'ambito delle chiavi" type="info">
  Ogni Server Secret Token ha gli stessi privilegi a livello di intera organizzazione; al momento i token non possono essere limitati a
  endpoint o esercenti specifici. Consideri qualsiasi token equivalente a un accesso completo all'API per la Sua organizzazione.
</Callout>

Il server è accessibile esclusivamente tramite il protocollo HTTPS, con TLS 1.2 o versioni successive imposto a livello di infrastruttura. È applicato un limite di frequenza (100 richieste al minuto per indirizzo IP); le richieste che sovraccaricano il server restituiscono un errore `429 Too Many Requests`.