API

Descrizione API del servizio Payment Container

Informazioni Generali

Swagger

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.

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

In questa guida tutti gli endpoint sono descritti senza il prefisso /api/vX che va dunque anteposto

URLs UI

 

 

Richiesta di pagamento

Il path parameter token è l'identificativo univoco risultante dalla creazione di una Payment Request

Creazione richiesta di pagamento

Se si intende sfruttare questa api per avere un match univoco tra una fattura e una richiesta di pagamento, guardare la pagina Fatturazione

Permette di creare una richiesta di pagamento 

[POST] /paymentRequest ?

Nella request abbiamo:

I constraints hanno una priorità. Se vengono definiti sia nella request che nelle preferenze, avranno precedenza quelli della richiesta puntuale. Il minimumAmount può non essere definito ma in tal caso assumerà valore 0 con valuta EUR

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

Tutte le valute dei vari importi devono coincidere

Per inviare automaticamente una mail al debitore, contenete il link di pagamento, bisogna fornire l'indirizzo email compilando l'attributo email del debtor

Nella response l'API ritorna:

Modifica richiesta di pagamento

Permette di modificare una richiesta di pagamento 

[PATCH] /paymentRequest/{token} ?

Nella request abbiamo:

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

La modifica non è possibile se la richiesta di pagamento è nei seguenti stati: PAID \ EXTERNAL_PAID

Nella response l'API ritorna:

Disabilitare richiesta di pagamento

Permette di disabilitare una richiesta di pagamento precedentemente creata

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

Nella response l'API ritorna:

Visualizzare una singola richiesta di pagamento [API Pubblica]

Permette di visualizzare una richiesta di pagamento

[GET] /public/paymentRequest/{token}

Nella response l'API ritorna:

Visualizzare una singola richiesta di pagamento [API Autenticata]

Permette di visualizzare una richiesta di pagamento

[GET] /paymentRequest/{token} ?

Nella response l'API ritorna:

Visualizzare richieste di pagamento

Permette di visualizzare una lista di richieste di pagamento

[GET] /paymentRequest ?

Parametri obbligatori:

Parametri opzionali:

Nella response l'API ritorna:

Invio email

Permette l'invio manuale della mail di Creazione Richiesta.

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

Nella request abbiamo:

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

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 

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.

Questa mail è esattamente la stessa che viene inviata automaticamente dal sistema se impostato il campo email del debtor nella richiesta di pagamento

Pagamento

Il path parameter token è l'identificativo univoco risultante dalla creazione di una Payment Request

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:

Nella response l'API ritorna:

 

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

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

Nella request abbiamo:

Nella response l'API ritorna:

 

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:

Nella response l'API ritorna:

 

 

Documenti

Il path parameter token è l'identificativo univoco risultante dalla creazione di una Payment Request

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:

Nella response l'API ritorna:

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

Formati disponibili per tipologia di file
  ASSOSW ADE ASSOSWPDF ADEPDF RAW BASE64
AGYO_INVOICE

✅

Fallback

 ✅ ✅ ✅ ✅ ❌
DOC_STORE_DOCUMENT ❌ ❌ ❌ ❌

✅

Fallback

 ✅

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

Nel caso di Formato BASE64, ritorna esattamente la stessa struttura del Doc Store ovvero con anteposta la stringa data:application/pdf;base64,

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.

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:

Nella response l'API ritorna:

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

Formati disponibili per tipologia di file
  XML PDF ASSOSW BASE64 RAW
AGYO_INVOICE ✅ ✅

✅

Fallback

 ❌ ❌
DOC_STORE_DOCUMENT ❌ ❌ ❌ ✅

✅

Fallback

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

Nel caso di Formato BASE64, ritorna esattamente la stessa struttura del Doc Store ovvero in formato DataURI con anteposta la stringa data:application/pdf;base64, 

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.

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

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:

 

 

Preferenze

Il path parameter companyId è l'identificativo TS Digital di un'azienda correttamente registrata

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.

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)

Creazione di una preferenza

Permette di creare una preferenza per una specifica azienda

[POST] /preferences/{companyId} ?

Nella request abbiamo:

Nella response l'API ritorna:

 

Modifica di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

[PATCH] /preferences/{companyId} ?

Nella request abbiamo:

Nella response l'API ritorna:

 

Visualizzazione di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

[GET] /preferences/{companyId} ?

Nella response l'API ritorna:

 

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

Creazione richiesta di pagamento - Swagger

[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

Rimuovere richiesta di pagamento da una fattura - Swagger

[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

Il path parameter companyId è l'identificativo TS Digital di un'azienda correttamente registrata.

Richiesta informazioni di Overview

Permette di recuperate informazioni di overview utili a fini statistici

[GET] /overview/{companyId} ?

Nella response l'API ritorna:

Esempi Payload

Creazione Richiesta di pagamento

{
    "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

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

Creazione di una preferenza

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