# API

Descrizione API del servizio Payment Container

# Informazioni Generali

### Swagger

- [Ambiente Dev](https://payment-container-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config)
- [Ambiente Test](https://payment-container-test.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/)

L'ambiente di produzione non esponse swagger.

Url base di produzione è: **https://payment-container.agyo.io/**

---

### Headers

Per chiamare correttamente gli endpoint messi a disposizione dal servizio Payment Container, è necessario includere gli headers come descritto [qui](https://digital-docs.ts-paas.com/books/integrazione-e-utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital).

Tutte le API `public` non hanno necessità degli headers e possono essere utilizzate pubblicamente. Questo perchè anche un utente finale, non necessariamente TS Digital, può effettuare tali operazioni

<p class="callout warning">In questa guida tutti gli endpoint sono descritti senza il prefisso `/api/vX` che va dunque anteposto</p>

---

### URLs UI

- DEV: **https://apps-dev.agyo.io/payment-container-front/**
- TEST: **https://test.tsdigital-pay.com/payment-container-front/**
- PROD: **https://tsdigital-pay.com/**

# Richiesta di pagamento

<p class="callout warning">Il path parameter `token` è l'identificativo univoco risultante dalla creazione di una Payment Request</p>

#### Creazione richiesta di pagamento

<p class="callout info">Se si intende sfruttare questa api per avere un match univoco tra una fattura e una richiesta di pagamento, guardare la pagina [**Fatturazione**](https://digital-docs.ts-paas.com/books/payment-container/page/fatturazione "Fatturazione")</p>

Permette di creare una richiesta di pagamento

```
[POST] /paymentRequest ?
```

Nella **request** abbiamo:

- **`creditor`**: creditore della richiesta di pagamento  
    
    - `<strong>identifiers</strong>`: lista di possibili identificativi riguardanti il soggetto. Per il creditore è necessario fornire un **TS\_DIGITAL\_ID**
    - `<strong>name</strong>`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital
    - `<strong>holder</strong>`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital
    - `<strong>logourl</strong>`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital
    - `<strong>email</strong>`: compilare per utilizzare email custom di reply to inserita nella mail (vedere preferenze per capire le gerarchie)
- **`debtor`**: debitore della richiesta di pagamento 
    - `<strong>identifiers</strong>`: lista di possibili identificativi riguardanti il soggetto.
    - `<strong>name</strong>`: compilare in alternativa a holder (Persone giuridiche)
    - `<strong>holder</strong>`: compilare in alternativa a name (Persone fisiche)
    - `<strong>logourl</strong>`: non utilizzato per il debitore, non compilare
    - `<strong>email</strong>`: compilare se si vuole utilizzare la funzionalità di invio mail automatiche
- **`paymentReason`**: causale di pagamento
- **`totalAmount`**: ammontare totale della richiesta di pagamento
- **`availablePaymentPlans`**: piani di pagamento a disposizione 
    - `<strong>type</strong>`: tipologia di piano (singolo o multiplo)
    - `<strong>description</strong>`: descrizione del piano di pagamento
    - `<strong>installments</strong>`: rate che compongono il piano di pagamento 
        - `<strong>description</strong>`: descrizione della rata
        - `<strong>dueDate</strong>`: scadenza della singola rata
        - `<strong>amount</strong>`: importo della rata
        - **`metadata`**: dati aggiuntivi che è possibile utilizzare ai fini di riconciliazione (max 100 caratteri totali)
- **`availablePaymentMethods`**: metodi di pagamento a disposizione 
    - `<strong>name</strong>`: metodo di pagamento accettato
    - `<strong>constraints</strong>`: minimali e massimali del singolo metodo di pagamento 
        - `<strong>minimumAmount</strong>`: importo minimo per il metodo di pagamento
        - `<strong>maximumAmount</strong>`: importo massimo per il metodo di pagamento
- **`ownerId`**: ownerId con identificativo TS Digital del creditore
- **`transmitterId`**: transmitterId con identificativo TS Digital
- **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento 
    - `<strong>id</strong>`: identificativo del documento (hubId se fatture, o id se documento del document store)
    - `<strong>type</strong>`: tipo di documento
    - `<strong>description</strong>`: descrizione del documento
    - `<strong>allowDownloadBeforePayment</strong>`: booleano per inibire download prima che la richiesta sia completamente pagata (Default: true)
- **`dueDate`**: data di scadenza della richiesta di pagamento
- **`mailContent`**: contenuto della mail da fornire nel caso si voglia inviare del contenuto personalizzato (La mail può contenere i comuni tag html per i paragrafi e per la formattazione)
- **`storeMailContent`**: valore booleano che indica se è necessario conservare il contenuto della mail inviato

<p class="callout warning">I `constraints` hanno una priorità. Se vengono definiti sia nella request che nelle preferenze, avranno precedenza quelli della richiesta puntuale. Il `<span class="hljs-attr">minimumAmount</span>` può non essere definito ma in tal caso assumerà valore 0 con valuta EUR</p>

<p class="callout warning">Se un piano di pagamento è definito come SINGLE\_INSTALLMENT​ deve contenere una sola rata. Contrariamente se viene definito un MULTIPLE\_INSTALLMENTS deve contenere almeno due rate</p>

<p class="callout warning">Tutte le valute dei vari importi devono coincidere</p>

<p class="callout success">Per inviare automaticamente una mail al debitore, contenete il link di pagamento, bisogna fornire l'indirizzo email compilando l'attributo **email** del **debtor**</p>

Nella **response** l'API ritorna:

- **`id`**: identificativo univoco della richiesta di pagamento creata
- **`token`**: identificativo da utilizzare nelle altre chiamate API per fare riferimento alla richiesta di pagamento in oggetto
- **`url`**: link per visualizzare la richiesta di pagamento tramite UI Payment Container e successivamente effettuare dei pagamenti

---

#### Modifica richiesta di pagamento

Permette di modificare una richiesta di pagamento

```
[PATCH] /paymentRequest/{token} ?
```

Nella **request** abbiamo:

- **`debtor`**: debitore della richiesta di pagamento 
    - `<strong>identifiers</strong>`: lista di possibili identificativi riguardanti il soggetto. *Se non compilato viene utilizzato quello già presente*
    - `<strong>name</strong>`: compilare in alternativa a holder (Persone giuridiche). *Se non passato viene utilizzato quello già presente*
    - `<strong>holder</strong>`: compilare in alternativa a name (Persone fisiche). *Se non compilato viene utilizzato quello già presente*
    - `<strong>email</strong>`: compilare se si vuole utilizzare la funzionalità di invio mail automatiche. *Se non compilato viene utilizzata la mail impostata in precedenza. Per eventualmente rimuovere la mail, valorizzare a stringa vuota*
- **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento 
    - `<strong>id</strong>`: identificativo del documento (hubId se fatture, o id se documento del document store)
    - `<strong>type</strong>`: tipo di documento
    - `<strong>description</strong>`: descrizione del documento
    - `<strong>allowDownloadBeforePayment</strong>`: booleano per inibire download prima che la richiesta sia completamente pagata (Default: true)

<p class="callout warning">*Almeno un attributo deve essere valorizzato, altrimenti verrà restituito un errore. Per quanto riguarda **paymentDocuments**, è necessario fornire il nuovo elenco di documenti che andranno a sovrascrivere quelli precedentemente forniti*</p>

<p class="callout warning">*La modifica non è possibile se la richiesta di pagamento è nei seguenti stati: **PAID** \\ **EXTERNAL\_PAID***</p>

Nella **response** l'API ritorna:

- **`id`**: identificativo univoco della richiesta di pagamento modificata
- **`token`**: identificativo da utilizzare nelle altre chiamate API per fare riferimento alla richiesta di pagamento in oggetto
- **`url`**: link per visualizzare la richiesta di pagamento tramite UI Payment Container e successivamente effettuare dei pagamenti

---

#### Disabilitare richiesta di pagamento

Permette di disabilitare una richiesta di pagamento precedentemente creata

```
[PATCH] /paymentRequest/{token}/disable ?
```

Nella **response** l'API ritorna:

- **`id`**: identificativo univoco della richiesta di pagamento disabilitata
- `<strong>token</strong>`: identificativo token della richiesta di pagamento disabilitata
- **`url`**: link disabilitato

#### Visualizzare una singola richiesta di pagamento \[API Pubblica\]

Permette di visualizzare una richiesta di pagamento

```
[GET] /public/paymentRequest/{token}
```

Nella **response** l'API ritorna:

- **`token`**: token della richiesta di pagamento
- **`creditor`**: creditore della richiesta di pagamento
- **`debtor`**: debitore della richiesta di pagamento
- **`paymentReason`**: causale di pagamento
- **`totalAmount`**: ammontare totale della richiesta di pagamento
- **`availablePaymentPlans`**: piani di pagamento a disposizione 
    - **`id`**: identificativo del piano di pagamento
    - **`type`**: tipologia di piano (singolo o multiplo)
    - **`description`**: descrizione del piano di pagamento
    - **`installments`**: rate che compongono il piano di pagamento 
        - **`id`**: identificativo della rata
        - **`description`**: descrizione della rata
        - **`dueDate`**: scadenza della singola rata
        - **`amount`**: importo della rata
- **`availablePaymentMethods`**: metodi di pagamento a disposizione 
    - **`name`**: metodo di pagamento accettato
    - **`constraints`**: minimali e massimali del singolo metodo di pagamento 
        - **`<span class="hljs-attr">minimumAmount</span>`**: importo minimo per il metodo di pagamento
        - **`<span class="hljs-attr">maximumAmount</span>`**: importo massimo per il metodo di pagamento
- **`ownerId`**: ownerId con identificativo TS Digital del creditore
- **`transmitterId`**: transmitterId con identificativo TS Digital
- **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento 
    - **`documentId`**: identificativo del documento (interno a Payment Container non identificativo originale della fattura o documento su docstore)
    - **`type`**: tipo di documento
    - **`description`**: descrizione del documento
    - **`previewUrl`**: link per preview documento
    - **`downloadUrl`**: link per download documento
- **`dueDate`**: data di scadenza della richiesta di pagamento
- **`status`**: stato generale in cui si trova la richiesta di pagamento
- **`createdAt`**: data in cui è stata creata la richiesta
- **`payments`**: pagamenti effettuati per la richiesta di pagamento 
    - **`id`**: identificativo univoco del pagamento
    - **`amount`**: importo del pagamento
    - **`paymentMethodName`**: metodo di pagamento utilizzato
    - **`paymentPlanId`**: identificativo del piano di pagamento
    - **`installmentIds`**: rate del pagamento
    - **`status`**: stato del pagamento
    - **`link`**: link di pagamento

---

#### Visualizzare una singola richiesta di pagamento \[API Autenticata\]

Permette di visualizzare una richiesta di pagamento

```
[GET] /paymentRequest/{token} ?
```

Nella **response** l'API ritorna:

- **`token`**: token della richiesta di pagamento
- **`creditor`**: creditore della richiesta di pagamento
- **`debtor`**: debitore della richiesta di pagamento
- **`paymentReason`**: causale di pagamento
- **`totalAmount`**: ammontare totale della richiesta di pagamento
- **`availablePaymentPlans`**: piani di pagamento a disposizione 
    - **`id`**: identificativo del piano di pagamento
    - **`type`**: tipologia di piano (singolo o multiplo)
    - **`description`**: descrizione del piano di pagamento
    - **`installments`**: rate che compongono il piano di pagamento 
        - **`id`**: identificativo della rata
        - **`description`**: descrizione della rata
        - **`dueDate`**: scadenza della singola rata
        - **`amount`**: importo della rata
        - **`metadata`**: dati aggiuntivi che sono stati inseriti in creazione della richiesta
- **`availablePaymentMethods`**: metodi di pagamento a disposizione 
    - **`name`**: metodo di pagamento accettato
    - **`constraints`**: minimali e massimali del singolo metodo di pagamento 
        - **`<span class="hljs-attr">minimumAmount</span>`**: importo minimo per il metodo di pagamento
        - **`<span class="hljs-attr">maximumAmount</span>`**: importo massimo per il metodo di pagamento
- **`ownerId`**: ownerId con identificativo TS Digital del creditore
- **`transmitterId`**: transmitterId con identificativo TS Digital
- **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento 
    - **`documentId`**: identificativo del documento (interno a Payment Container non identificativo originale della fattura o documento su docstore)
    - **`type`**: tipo di documento
    - **`description`**: descrizione del documento
    - **`previewUrl`**: link per preview documento
    - **`downloadUrl`**: link per download documento
- **`originalDocumentIds`**: mapping tra gli identificativi interni PaymentContainer e gli identificativi originali caricati (hubId o id DocStore)
- **`dueDate`**: data di scadenza della richiesta di pagamento
- **`status`**: stato generale in cui si trova la richiesta di pagamento
- **`createdAt`**: data in cui è stata creata la richiesta
- **`enabled`**: stato della richiesta che indica se abilitata o disabilitata
- **`payments`**: pagamenti effettuati per la richiesta di pagamento 
    - **`id`**: identificativo univoco del pagamento
    - **`amount`**: importo del pagamento
    - **`paymentMethodName`**: metodo di pagamento utilizzato
    - **`paymentPlanId`**: identificativo del piano di pagamento
    - **`installmentIds`**: rate del pagamento
    - **`status`**: stato del pagamento
    - **`link`**: link di pagamento
- **`emailContent`**: contenuto della mail inviata al debitore al momento della creazione della richiesta

---

#### Visualizzare richieste di pagamento

Permette di visualizzare una lista di richieste di pagamento

```
[GET] /paymentRequest ?
```

Parametri **obbligatori**:

- **`ownerId`**: ownerId di cui si ha il permesso per operare e per cui si richiede la lista
- **`timestamp`**: unix timestamp in millisecondi (esempio: `1643361440000`)

Parametri *opzionali*:

- **`tokens`**: array di id di richieste di pagamento da visualizzare
- **`size`**: numero di risultati per richiesta (default: **20**)
- **`continuationToken`**: token per richiedere il blocco successivo (restituito nella risposta)
- **`sort`**: chiavi di sorting possibili -&gt; **createdAt**
- **`direction`**: desc | asc rispetto alla chiave di sorting

Nella **response** l'API ritorna:

- **`content`**: lista di risultati con singola struttura identica alla richiesta singola \[Profilo Privato\]
- **`continuationToken`**: token per richiedere altri risultati
- **`hasNext`**: booleano che indica se ci sono altri risultati da visualizzare
- **`size`**: massima dimensione dei risultati impostata nei filtri

---

#### Invio email

Permette l'invio manuale della mail di Creazione Richiesta.

```
[POST] /paymentRequest/{token}/sendMail ?
```

Nella request abbiamo:

- **`email`**: indirizzo email a cui inviare la notifica (opzionale)

Nella **response** l'API non torna nulla se non lo status code

<p class="callout info">Il campo `email` è opzionale. Se nella creazione della richiesta di pagamento era stato impostato il campo `email` del `debtor` verrà preso quel valore per inviare nuovamente una mail. Impostando `email` in questa API, questo valore avrà precedenza rispetto a quello del debtor, ma non lo sostituirà. Per modificare l'email del debtor per tutta la richiesta di pagamento, procedere utilizzando l'API dedicata di modifica della richiesta di pagamento </p>

<p class="callout info">Il testo della mail è fornito di default da TS Digital. Alternativamente, se impostato il parametro `bodyText` nelle preferenze, verrà utilizzato questo in alternativa a quello di default.</p>

<p class="callout warning">Questa mail è esattamente la stessa che viene inviata automaticamente dal sistema se impostato il campo `email` del `debtor` nella richiesta di pagamento</p>

# Pagamento

<p class="callout warning">Il path parameter `token` è l'identificativo univoco risultante dalla creazione di una Payment Request</p>

#### Creazione link di pagamento

Permette di creare un link di pagamento facendo riferimento ad una payment request precedentemente configurata

```
[POST] /public/paymentRequest/{token}/pay
```

Nella **request** abbiamo:

- `paymentMethodName`: metodo di pagamento da utilizzare
- `paymentPlanId`: identificativo del piano di pagamento da pagare
- `installmentIds`: identificativi delle rate del piano di pagamento da pagare
- `langLocale`: lingua da utilizzare
- `scheduled`: booleano per indicare se il pagamento dovrà essere immediato o schedulato (default: **false**)

Nella **response** l'API ritorna:

- `id`: identificativo univoco del pagamento creato
- `link`: link di pagamento verso la piattaforma di riferimento

####  

#### Modifica link di pagamento

Permette di modificare le configurazioni di un link di pagamento precedentemente configurato e non ancora pagato

```
[PATCH] /public/paymentRequest/{token}/payment
```

Nella **request** abbiamo:

- `paymentMethodName`: metodo di pagamento da utilizzare
- `paymentPlanId`: identificativo del piano di pagamento da pagare
- `installmentIds`: identificativi delle rate del piano di pagamento da pagare
- `langLocale`: lingua da utilizzare

Nella **response** l'API ritorna:

- `id`: identificativo univoco del pagamento creato
- `link`: link di pagamento verso la piattaforma di riferimento

####  

#### Richiesta pagamento manuale

Permette di segnalare un pagamento come effettuato anche senza passare attraverso un iter di pagamento di Payment Container

```
[POST] /paymentRequest/{token}/manualPayment ?
```

Nella **request** abbiamo:

- `paymentMethodName`: metodo di pagamento utilizzato per pagare
- `paymentPlanId`: identificativo del piano di pagamento pagato
- `installmentIds`: identificativi delle rate del piano di pagamento pagato

Nella **response** l'API ritorna:

- `id`: identificativo univoco del pagamento creato
- `amount`: ammontare del pagamento effettuato
- `paymentMethodName`: metodo di pagamento utilizzato
- `paymentPlanId`: identificativo del piano di pagamento pagato
- `installmentIds`: identificativi delle rate del piano di pagamento pagato
- `status`: stato per il pagamento effettuato
- `createdAt`: data di creazione del pagamento

---

# Documenti

<p class="callout warning">Il path parameter `token` è l'identificativo univoco risultante dalla creazione di una Payment Request</p>

#### Preview di un documento

Permette di ricevere la preview di uno specifico documento contenuto in una payment request precedentemente configurata

```
[GET] /public/paymentRequest/{token}/documents/{documentId}/preview
[GET] /paymentRequest/{token}/documents/{documentId}/preview ?
```

Possibili parametri:

- `type`: tipologia di visualizzazione voluta

Nella **response** l'API ritorna:

XML del documento, HTML o PDF in base alla preview richiesta

##### Formati disponibili per tipologia di file

<table border="1" id="bkmrk-%C2%A0-assosw-ade-assoswp" style="border-collapse: collapse; width: 100%; height: 137px;"><tbody><tr style="height: 29px;"><td style="width: 16.1377%; height: 29px;"> </td><td class="align-center" style="width: 13.2979%; height: 29px; background-color: #d0e0e3;">**ASSOSW**</td><td class="align-center" style="width: 14.0388%; height: 29px; background-color: #d0e0e3;">**ADE**</td><td class="align-center" style="width: 14.0387%; height: 29px; background-color: #d0e0e3;">**ASSOSWPDF**</td><td class="align-center" style="width: 14.7796%; height: 29px; background-color: #d0e0e3;">**ADEPDF**</td><td class="align-center" style="width: 14.0388%; height: 29px; background-color: #d0e0e3;">**RAW**</td><td class="align-center" style="width: 13.6684%; height: 29px; background-color: #d0e0e3;">**BASE64**</td></tr><tr style="height: 56px;"><td class="align-center" style="width: 16.1377%; height: 56px; background-color: #f4cccc;">**AGYO\_INVOICE**</td><td class="align-center" style="width: 13.2979%; height: 56px;">✅

Fallback

</td><td class="align-center" style="width: 14.0388%; height: 56px;">✅</td><td class="align-center" style="width: 14.0387%; height: 56px;">✅</td><td class="align-center" style="width: 14.7796%; height: 56px;">✅</td><td class="align-center" style="width: 14.0388%; height: 56px;">✅</td><td class="align-center" style="width: 13.6684%; height: 56px;">❌</td></tr><tr style="height: 52px;"><td class="align-center" style="width: 16.1377%; height: 52px; background-color: #f4cccc;">**DOC\_STORE\_DOCUMENT**</td><td class="align-center" style="width: 13.2979%; height: 52px;">❌</td><td class="align-center" style="width: 14.0388%; height: 52px;">❌</td><td class="align-center" style="width: 14.0387%; height: 52px;">❌</td><td class="align-center" style="width: 14.7796%; height: 52px;">❌</td><td class="align-center" style="width: 14.0388%; height: 52px;">✅

Fallback

</td><td class="align-center" style="width: 13.6684%; height: 52px;">✅</td></tr></tbody></table>

Se si richiede un formato non valido per la tipologia di documento richiesta, verrà applicato il formato di fallback

<p class="callout warning">Nel caso di Formato **BASE64**, ritorna esattamente la stessa struttura del Doc Store ovvero con anteposta la stringa `data:application/pdf;base64,`</p>

<p class="callout info">L'api **public** segue il comportamento del flag **allowDownloadBeforePayment.** Se impostato a **false** in fase di creazione richiesta, il documento non può essere mostrato prima che il pagamento sia completato. L'api **autenticata**, invece, permette di visionare in qualunque momento il documento in oggetto.</p>

#### Download di un documento

Permette di ricevere la preview di uno specifico documento contenuto in una payment request precedentemente configurata

```
[GET] /public/paymentRequest/{token}/documents/{documentId}/download
[GET] /paymentRequest/{token}/documents/{documentId}/download ?
```

Possibili parametri:

- `format`: tipologia di visualizzazione voluta

Nella **response** l'API ritorna:

**XML** del documento, **PDF** o **stringa base64** in base al formato richiesto

##### Formati disponibili per tipologia di file

<table border="1" id="bkmrk-%C2%A0-xml-pdf-assosw-bas" style="border-collapse: collapse; width: 100%; height: 99px;"><tbody><tr style="height: 29px;"><td style="width: 16.6667%; height: 29px; border-style: solid;"> </td><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #d0e0e3;">**XML**</td><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #d0e0e3;">**PDF**</td><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #d0e0e3;">**ASSOSW**</td><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #d0e0e3;">**BASE64**</td><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #d0e0e3;">**RAW**</td></tr><tr style="height: 41px;"><td class="align-center" style="width: 16.6667%; height: 41px; background-color: #f4cccc;">**AGYO\_INVOICE**</td><td class="align-center" style="width: 16.6667%; height: 41px;">✅</td><td class="align-center" style="width: 16.6667%; height: 41px;">✅</td><td class="align-center" style="width: 16.6667%; height: 41px;">✅

Fallback

</td><td class="align-center" style="width: 16.6667%; height: 41px;">❌</td><td class="align-center" style="width: 16.6667%; height: 41px;">❌</td></tr><tr style="height: 29px;"><td class="align-center" style="width: 16.6667%; height: 29px; background-color: #f4cccc;">**DOC\_STORE\_DOCUMENT**</td><td class="align-center" style="width: 16.6667%; height: 29px;">❌</td><td class="align-center" style="width: 16.6667%; height: 29px;">❌</td><td class="align-center" style="width: 16.6667%; height: 29px;">❌</td><td class="align-center" style="width: 16.6667%; height: 29px;">✅</td><td class="align-center" style="width: 16.6667%; height: 29px;">✅

Fallback

</td></tr></tbody></table>

Se si richiede un formato non valido per la tipologia di documento richiesta, verrà applicato il formato di fallback

<p class="callout warning">Nel caso di Formato **BASE64**, ritorna esattamente la stessa struttura del Doc Store ovvero in formato [DataURI](https://en.wikipedia.org/wiki/Data_URI_scheme) con anteposta la stringa `data:application/pdf;base64,` </p>

<p class="callout info">L'api **public** segue il comportamento del flag **allowDownloadBeforePayment.** Se impostato a **false** in fase di creazione richiesta, il documento non può essere scaricato prima che il pagamento sia completato. L'api **autenticata**, invece, permette di scaricare in qualunque momento il documento in oggetto.</p>

#### Upload documento Payment Container tramite TS Document Store

Proxy che permette di caricare un documento su **TS Document Store**, senza preoccuparsi di possedere un token tecnico dedicato

```
[POST] /documentStore ?
```

Request Body (multipart/form-data):

- `ownerId`: ownerId con identificativo TS Digital del creditore
- `transmitterId`: transmitterId con identificativo TS Digital
- `file`: binary del file da caricare (max 10mb)

#### Upload documento Payment Container tramite TS Document Store (Base64)

Proxy che permette di caricare un documento su **TS Document Store**, senza la necessità di possedere un token tecnico dedicato.

```
[POST] /documentStore/base64 ?
```

Nella **request** abbiamo:

- `ownerId`: ownerId con identificativo TS Digital del creditore
- `transmitterId`: transmitterId con identificativo TS Digital
- `file`: base64 con formato [DataURI](https://en.wikipedia.org/wiki/Data_URI_scheme) ---&gt; **data:application/pdf;base64,file\_content\_in\_base\_64**

# Preferenze

<p class="callout warning">Il path parameter `companyId` è l'identificativo TS Digital di un'azienda correttamente registrata</p>

<p class="callout warning">Le preferenze non vincono mai sui valori impostati in una singola richiesta di pagamento. Questo permette di sovrascrivere le preferenze per delle richieste di pagamento specifiche.</p>

<p class="callout warning">Se **daysDueDate** non viene impostato, o viene impostato a 0, verranno aggiunti **180gg** come valore di default alla data di scadenza dell'ultima rata (a meno di non aver impostato una due date specifica in richiesta)</p>

#### Creazione di una preferenza

Permette di creare una preferenza per una specifica azienda

```
[POST] /preferences/{companyId} ?
```

Nella **request** abbiamo:

- `daysDueDate`: giorni di scadenza che verranno aggiunti alla data di scadenza dell'ultima rata
- `emailSettings`: parametri di customizzazione per email 
    - `bodyText`: testo della mail
    - `name`: nome inserito nell'intestazione della mail
    - `email`: email custom di reply to inserita nella mail
- `paymentMethodSettings`: identificativi delle rate del piano di pagamento da pagare 
    - `name`: metodo di pagamento
    - `constraints`: minimali e massimali del singolo metodo di pagamento 
        - `<span class="hljs-attr">minimumAmount</span>`: importo minimo per il metodo di pagamento
        - `<span class="hljs-attr">maximumAmount</span>`: importo massimo per il metodo di pagamento

Nella **response** l'API ritorna:

- `companyId`: id azienda TS Digital
- `daysDueDate`: giorni di scadenza che verranno aggiunti alla data di scadenza dell'ultima rata
- `emailSettings`: parametri di customizzazione per email 
    - `bodyText`: testo della mail
    - `name`: nome inserito nell'intestazione della mail
    - `email`: email custom di reply to inserita nella mail
- `paymentMethodSettings`: identificativi delle rate del piano di pagamento da pagare 
    - `name`: metodo di pagamento
    - `constraints`: minimali e massimali del singolo metodo di pagamento 
        - `<span class="hljs-attr">minimumAmount</span>`: importo minimo per il metodo di pagamento
        - `<span class="hljs-attr">maximumAmount</span>`: importo massimo per il metodo di pagamento

#### Modifica di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

```
[PATCH] /preferences/{companyId} ?
```

Nella **request** abbiamo:

- `daysDueDate`: giorni di scadenza che verranno aggiunti alla data di scadenza dell'ultima rata
- `emailSettings`: parametri di customizzazione per email 
    - `bodyText`: testo della mail
    - `name`: nome inserito nell'intestazione della mail
    - `email`: email custom di reply to inserita nella mail
- `paymentMethodSettings`: identificativi delle rate del piano di pagamento da pagare 
    - `name`: metodo di pagamento
    - `constraints`: minimali e massimali del singolo metodo di pagamento 
        - `<span class="hljs-attr">minimumAmount</span>`: importo minimo per il metodo di pagamento
        - `<span class="hljs-attr">maximumAmount</span>`: importo massimo per il metodo di pagamento

Nella **response** l'API ritorna:

- `companyId`: id azienda TS Digital
- `daysDueDate`: giorni di scadenza che verranno aggiunti alla data di scadenza di una richiesta di pagamento
- `emailSettings`: parametri di customizzazione per email 
    - `bodyText`: testo della mail
    - `name`: nome inserito nell'intestazione della mail
    - `email`: email custom di reply to inserita nella mail
- `paymentMethodSettings`: identificativi delle rate del piano di pagamento da pagare 
    - `name`: metodo di pagamento
    - `constraints`: minimali e massimali del singolo metodo di pagamento 
        - `<span class="hljs-attr">minimumAmount</span>`: importo minimo per il metodo di pagamento
        - `<span class="hljs-attr">maximumAmount</span>`: importo massimo per il metodo di pagamento

#### Visualizzazione di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

```
[GET] /preferences/{companyId} ?
```

Nella **response** l'API ritorna:

- `companyId`: id azienda TS Digital
- `daysDueDate`: giorni di scadenza che verranno aggiunti alla data di scadenza di una richiesta di pagamento
- `emailSettings`: parametri di customizzazione per email 
    - `bodyText`: testo della mail
    - `name`: nome inserito nell'intestazione della mail
    - `email`: email custom di reply to inserita nella mail
- `paymentMethodSettings`: identificativi delle rate del piano di pagamento da pagare 
    - `name`: metodo di pagamento
    - `constraints`: minimali e massimali del singolo metodo di pagamento 
        - `<span class="hljs-attr">minimumAmount</span>`: importo minimo per il metodo di pagamento
        - `<span class="hljs-attr">maximumAmount</span>`: importo massimo per il metodo di pagamento

####  

#### Gerarchia priorità

**daysDueDate**

1. *dueDate inserita nella singola richiesta*
2. *dueDate maggiore negli installments + daysDueDate nelle preferenze*
3. *dueDate maggiore negli installments + 180gg*

---

**emailSettings.email**

1. *creditor.email nella singola richiesta*
2. *email preferenze*
3. *nessuna email di reply-to*

---

**emailSettings.name**:

1. *name nelle preferenze*
2. *nome azienda recuperato dall'Anagrafica Ts Digital*

---

***emailSettings.bodyText**:*

1. *testo nelle preferenze*
2. *testo standard fornito dalla piattaforma*

# Fatturazione

Per avvalersi le funzionalità di linking tra una fattura e una richiesta di pagamento, bisogna fare affidamento alla API dedicate disponibili [qui](https://b2bwrite-api-test.agyo.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config "Swagger")

#### Creazione richiesta di pagamento - [Swagger](https://b2bwrite-api-test.agyo.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/PaymentContainerV1/createPaymentRequest)

```
[POST] https://b2bwrite-api-test.agyo.io/api/v1/payment/create ?
```

Questa API si comporta come la classica Creazione richiesta di pagamento, ma permette di visualizzare sulla fattura l'identificativo della richiesta di pagamento appena creata.

Inoltre permette, a fronte di una richiesta di pagamento successiva, di disabilitare la precedente mantenendo univoco il rapporto Fattura/Richiesta di pagamento.

Il payload utilizzato è il medesimo che potete trovare nella classica creazione richiesta di pagamento disponibile [qui](https://digital-docs.ts-paas.com/link/190#bkmrk-richiesta-pagamento-)

#### Rimuovere richiesta di pagamento da una fattura - [Swagger](https://b2bwrite-api-test.agyo.io/api/swagger-ui/index.html?configUrl=/api/v3/api-docs/swagger-config#/InvoicesV2/removePaymentRequestFromInvoice)

```
[POST] https://b2bwrite-api-test.agyo.io/api/v2/invoices/{hubId}/removePaymentRequest ?
```

Questa API permette di rimuovere una richiesta di pagamento da una fattura e la disabilita automaticamente

# Overview

<p class="callout warning">Il path parameter `companyId` è l'identificativo TS Digital di un'azienda correttamente registrata.</p>

#### Richiesta informazioni di Overview

Permette di recuperate informazioni di overview utili a fini statistici

```
[GET] /overview/{companyId} ?
```

Nella **response** l'API ritorna:

- `enabledPaymentRequests`: numero di richieste abilitate per l'ownerId in oggetto

# Esempi Payload

### Creazione Richiesta di pagamento

```JSON
{
    "creditor": {
        "identifiers": [
            {
                "type": "TS_DIGITAL_ID",
                "country": "Italy",
                "value": "5841dc57-59e9-4b82-b751-a03799a21cf6"
            }
        ]
    },
    "debtor": {
        "identifiers": [
            {
                "type": "VAT_NUMBER",
                "country": "IT",
                "value": "23434565432"
            }
        ],
        "name": "Debitore fannullone",
        "email": "test.debitore@teamsystem.com"
    },
    "totalAmount": {
        "currency": "EUR",
        "amount": "3299.99"
    },
    "availablePaymentPlans": [
        {
            "type": "MULTIPLE_INSTALLMENTS",
            "description": "Piano rateale",
            "installments": [
                {
                    "description": "Prima rata",
                    "dueDate": "2022-02-19T16:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1000.00"
                    }
                },
                {
                    "description": "Seconda rata",
                    "dueDate": "2022-09-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1000.00"
                    }
                },
                {
                    "description": "Terza rata",
                    "dueDate": "2022-10-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1299.99"
                    }
                }
            ]
        },
        {
            "type": "SINGLE_INSTALLMENT",
            "description": "Pagamento totale",
            "installments": [
                {
                    "description": "Rata unica",
                    "dueDate": "2022-08-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "3299.99"
                    }
                }
            ]
        }
    ],
    "availablePaymentMethods": [
        {
            "name": "TS_PAY_BANK_TRANSFER"
        },
        {
            "name": "TS_PAY_CREDIT_CARD"
        }
    ],
    "paymentReason": "Fattura n.4 del 20 Luglio 2021",
    "ownerId": "5841dc57-59e9-4b82-b751-a03799a21cf6",
    "transmitterId": "5841dc57-59e9-4b82-b751-a03799a21cf6",
    "paymentDocuments": [
        {
            "type": "AGYO_INVOICE",
            "description": "test",
            "id": "8009cfb3-e7f1-43d1-a2a9-e1f263e5159c"
        },
        {
            "type": "DOC_STORE_DOCUMENT",
            "description": "file doc store test",
            "id": "d015f194-2609-4496-a7ec-6aba33a4b51c"
        }
    ]
}
```

### Creazione di un pagamento

```JSON
{
  "installmentIds": [
    "0.0",
    "0.1"
  ],
  "paymentMethodName": "TS_PAY_BANK_TRANSFER",
  "paymentPlanId": "0",
  "langLocale": "it-IT",
  "scheduled": true
}
```

### Creazione di una preferenza

```JSON
{
    "daysDueDate": 30,
    "emailSettings": {
        "bodyText": "Ciao benvenuto"
    }
}
```