Pagamenti e Fatture

L'API relativa ai dati contabili permette di visualizzare e gestire i pagamenti, le fatture e il credito del Registrar. Per tutti i metodi è richiesta la presenza dello scope billing nel token.

Credito del Registrar

Ottenere il credito

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit

Il Registrar può ottenere l'attuale credito disponibile per le varie operazioni come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/credit HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

curl https://api.nic.it/v1/credit \
    -H "Accept: application/json" \
    -H "Authorization: Bearer token..."

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

http https://api.nic.it/v1/credit "Authorization: Bearer token..."

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

Ottenere il credito storico

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit/untilDate?date={date}

E' possibile richiedere quale fosse il credito ad una specificata data utilizzando nella richiesta il parametro date.

Info

Da notare che la data specificata è inclusa nel calcolo, pertanto verranno considerate tutte le variazioni di credito fino alle 23:59:59 del giorno indicato.

Nell'esempio seguente viene richiesto il valore del credito al termine del 2023.

HTTPcURLHTTPie

GET /v1/credit/untilDate?date=2023-12-31 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "credit" : 245.5,
}

curl "https://api.nic.it/v1/credit/untilDate?date=2023-12-31" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "credit" : 245.5,
}

http https://api.nic.it/v1/credit/untilDate \
    "Authorization: Bearer token..." \
    date==2023-12-31

{
  "credit" : 245.5,
}

Warning

A seconda del numero delle variazioni di credito, il calcolo del credito storico potrebbe richiedere del tempo.

Ottenere la soglia di credito

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit/warnThreshold

Il Registrar può impostare una soglia di credito al di sotto della quale verrà inviato un avviso (via messaggio EPP). Si possono ottenere i dati della soglia attuale come nell'esempio che segue:

HTTPcURLHTTPie

GET /v1/credit/warnThreshold HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "threshold" : 100.0
}

curl "https://api.nic.it/v1/credit/warnThreshold \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "threshold" : 100.0
}

http "https://api.nic.it/v1/credit/warnThreshold \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "threshold" : 100.0
}

Modificare la soglia di credito

1.0 | billing | admin / billing |

PUT https://api.nic.it/v1/credit/warnThreshold

Il Registrar può impostare una soglia di credito al di sotto della quale verrà inviato un avviso (via messaggio EPP). Si può modificare il valore della soglia come nell'esempio seguente:

HTTPcURLHTTPie

PUT /v1/credit/warnThreshold HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

{
  "threshold" : 200
}

HTTP/1.1 204 No Content

curl -X PUT  "https://api.nic.it/v1/credit/warnThreshold" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token...." \
-d '
{
    "threshold" : 200
}'

http PUT https://api.nic.it/v1/credit/warnThreshold  \
    "Authorization: Bearer token...." \
    threshold=200

Pagamenti

I pagamenti sono il metodo utilizzato dai Registrar per ricaricare il credito necessario per le operazioni da compiere su domini. Le metodologie per la ricarica del credito da parte del Registrar (creazione di un pagamento) sono:

• Pagamento tramite bonifico bancario
• Pagamento tramite carta di credito

Creare un pagamento bancario

1.0 | billing | admin / billing |

POST https://api.nic.it/v1/payments/bank

Permette di creare un pagamento bancario a seguito di un bonifico effettuato dal Registrar. Esempio:

HTTPcURLHTTPie

POST /v1/payments/bank HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "amount" : 200.0,
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

curl -X POST https://api.nic.it/v1/payments/bank \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
    "amount" : 200.0,
    "bankPayment" : {
        "european" : true,
        "applicant" : "Giulio Cesare",
        "applicantRole" : "admin",
        "bankName" : "Una Banca Spa",
        "branchName" : "Test",
        "paymentDate" : "2024-02-26",
        "valueDate" : "2024-02-27",
        "transactionId" : "ABC12345"
    }
}'

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

http https://api.nic.it/v1/payments/bank  \
    "Authorization: Bearer token...." \
    --raw \
'{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}'

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

Ottenere un pagamento tramite id

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}

E' possibile ottenere i dati di un pagamento tramite l'id numerico assegnato dal Registro. I dati del pagamento possono variare in funzione del tipo di pagamento.

Esempio relativo ad un pagamento bancario:

HTTPcURLHTTPie

GET /v1/payments/4 HTTP/1.1
Accept: application/json
Host: api.nic.it

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

curl https://api.nic.it/v1/payments/4 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

http https://api.nic.it/v1/payments/4 "Authorization: Bearer token..."

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

Ricerca i pagamenti

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments

E' possibile effettuare una ricerca dei pagamenti effettuati dal Registrar utilizzando vari parametri di ricerca e diversi operatori (ricerca avanzata).

Di seguito sono riportati i parametri e gli operatori disponibili per la ricerca dei pagamenti:

Parametro	Tipo	Cardinalità	Descrizione	Operatori supportati	Operatore default
amount	Number	Singolo	Ammontare del pagamento	eq, ne, gt, lt, ge, le, in, notIn, between	eq
type	String	Singolo	Tipologia del pagamento (bank, creditCard, registry, contractTransfer)	eq, ne, in, notIn	eq
status	String	Singolo	Stato del pagamento (submitted, approved, suspended, rejected)	eq, ne, in, notIn	eq
created	DateTime	Multiplo	Data di creazione	eq, ne, gt, lt, ge, le, between	eq

Esempio di ricerca di pagamenti effettuati tramite bonifico bancario o carta di credito (type=in:bank,creditCard) con ammontare di almeno 500 Euro (amount=ge:500):

HTTPcURLHTTPie

GET /v1/payments?type=in%3Abank%2CcreditCard&amount=ge%3A200 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

curl "https://api.nic.it/v1/payments?type=?type=in:bank,creditCard&amount=ge:200" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..." 

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

http https://api.nic.it/v1/payments \
    "Authorization: Bearer token..." \
    type==in:bank,creditCard \
    amount==ge:200

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

I risultati della ricerca sono paginati.

Ottenere il report di un pagamento

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}/report

Questo metodo permette di ottenere un report aggregato delle operazioni (domini, bulk-transfer e penali) addebitate su un pagamento.

Esempio:

HTTPcURLHTTPie

GET /v1/payments/4/report HTTP/1.1
Accept: application/json
Host: api.nic.it

HTTP/1.1 200 OK
Content-Type: application/json

{
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}

curl https://api.nic.it/v1/payments/4/report \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

 {
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}

http https://api.nic.it/v1/payments/4/report "Authorization: Bearer token..."

 {
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}

Ottenere la fattura collegata al pagamento

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}/invoice

E' possibile ottenere i dati della fattura collegata a un pagamento (se disponibile) come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/payments/1111/invoice HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 2789,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

curl https://api.nic.it/v1/payments/1111/invoice \
-H "Accept: application/json" \
-H "Authorization: Bearer token..." 

{
    "id" : 2789,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
}

http https://api.nic.it/v1/payments/1111/invoice "Authorization: Bearer token..."

{
    "id" : 2789,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
}

Iniziare un pagamento con carta di credito

1.0 | billing | admin / billing |

POST https://api.nic.it/v1/payments/creditCard/transactions

Questo metodo serve per avviare un pagamento con carta di credito da completare successivamente sul portale della banca. Esempio:

HTTPcURLHTTPie

POST /v1/payments/creditCard/transactions HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api.nic.it
Authorization: Bearer token....

{
  "language" : "it",
  "amount" : 500,
  "redirectSuccessUrl" : "http://success.url",
  "redirectFailureUrl" : "http://failure.url"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

curl -X POST https://api.nic.it/v1/payments/creditCard/transactions \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
  "language" : "it",
  "amount" : 500,
  "redirectSuccessUrl" : "http://success.url",
  "redirectFailureUrl" : "http://failure.url"
}`

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

http POST https://api.nic.it/v1/payments/creditCard/transactions \
    "Authorization: Bearer token..." \
    --raw \
    '{
      "language" : "it",
      "amount" : 500,
      "redirectSuccessUrl" : "http://success.url",
      "redirectFailureUrl" : "http://failure.url"
    }`

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

Ottenere i dati pagamento con carta di credito

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/creditCard/transactions/{transactionId}

E' possibile ottenere i dati di una transazione con carta di credito tramite id come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : "cdc8555b-2cca-4f7f-ae80 ",
  "gatewayId" : "trn-2",
  "amount" : "500.00",
  "language" : "it",
  "status" : "approved",
  "paymentId": 1234,
  "response" : {
    "description" : "TRANSAZIONE OK",
    "creditCard" : {
      "brand" : "ANY",
      "number" : "4111********1111",
      "expire" : "04/27",
      "name" : "Giulio Cesare"
    }
  },
  "created" : "2024-05-09T09:41:17+02:00"
}

curl https://api.nic.it/v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
    "id" : "cdc8555b-2cca-4f7f-ae80 ",
    "gatewayId" : "trn-2",
    "amount" : "500.00",
    "language" : "it",
    "status" : "approved",
    "paymentId": 1234,
    "response" : {
        "description" : "TRANSAZIONE OK",
        "creditCard" : {
            "brand" : "ANY",
            "number" : "4111********1111",
            "expire" : "04/27",
            "name" : "Giulio Cesare"
        }
    },
    "created" : "2024-05-09T09:41:17+02:00"
}

http https://api.nic.it/v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 \
    "Authorization: Bearer token..."

{
    "id" : "cdc8555b-2cca-4f7f-ae80 ",
    "gatewayId" : "trn-2",
    "amount" : "500.00",
    "language" : "it",
    "status" : "approved",
    "paymentId": 1234,
    "response" : {
        "description" : "TRANSAZIONE OK",
        "creditCard" : {
            "brand" : "ANY",
            "number" : "4111********1111",
            "expire" : "04/27",
            "name" : "Giulio Cesare"
        }
    },
    "created" : "2024-05-09T09:41:17+02:00"
}

Info

L'esempio sopra fa riferimento a una transazione con carta di credito completata con successo. Per le transazioni non completate non è presente la sezione response

Fatture

Ottenere una fattura tramite id

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}

E' possibile ottenere i dati di una fattura tramite l'id numerico assegnato dal Registro come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/invoices/1 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

curl https://api.nic.it/v1/invoices/1 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

http https://api.nic.it/v1/invoices/1 \
    "Authorization: Bearer token..."

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

Info

Da notare che l'id della fattura utilizzato per prelevare i dati non è il numero di fattura generato dal sistema di contabilità.

Ricercare le fatture

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices

E' possibile effettuare una ricerca delle fatture emesse per il Registrar utilizzando vari parametri di ricerca e diversi operatori (ricerca avanzata).

Di seguito sono riportati i parametri e gli operatori disponibili per la ricerca delle fatture:

Parametro	Tipo	Cardinalità	Descrizione	Operatori supportati	Operatore default
invoiceNumber	Number	Singolo	Numero della fattura	eq, ne, in, notIn	eq
totalAmount	Number	Singolo	Ammontare totale della fattura	eq, ne, gt, lt, ge, le, between, in, notIn	eq
invoiceDate	DateTime	Multiplo	Data della fattura	eq, ne, gt, lt, ge, le, between	eq
paymentId	Number	Singolo	Id del pagamento	eq, ne, in, notIn	eq

Esempio di ricerca di fatture con importo totale di almeno 500 Euro (totalAmount=ge:500):

HTTPcURLHTTPie

GET /v1/invoices?totalAmount=ge:500 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/invoices?totalAmount=ge:500" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

http https://api.nic.it/v1/invoices \
    "Authorization: Bearer token..." \
    totalAmount==ge:500

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

I risultati della ricerca sono paginati.

Ottenere il PDF della fattura

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}/pdf

E' possibile ottenere il PDF (se disponibile) di una fattura come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/invoices/1/pdf HTTP/1.1
Accept: application/pdf
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/pdf

<PDF CONTENT>

curl --output invoice.pdf "https://api.nic.it/v1/invoices/1/pdf" \
-H "Accept: application/pdf" \
-H "Authorization: Bearer token..."

http --download https://api.nic.it/v1/invoices/1/pdf \
    "Accept: application/pdf" \
    "Authorization: Bearer token..."

Verifica presenza del PDF della fattura

1.0 | billing | admin / billing |

HEAD https://api.nic.it/v1/invoices/{invoiceId}/pdf

E' possibile verificare se il PDF di una fattura è disponibile o meno. Se il PDF è disponibile, il codice HTTP risposta sarà 200, altrimenti il codice http della risposta sarà 400.

HTTPcURLHTTPie

HEAD /v1/invoices/1/pdf HTTP/1.1
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK

curl --head https://api.nic.it/v1/invoices/1/pdf \
    -H "Authorization: Bearer token..."

http HEAD https://api.nic.it/v1/invoices/1/pdf "Authorization: Bearer token..."

Ottenere il pagamento collegato alla fattura

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}/payment

E' possibile ottenere il pagamento associato a una fattura come nell'esempio seguente:

HTTPcURLHTTPie

GET /v1/invoices/1212/payment HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}

curl "https://api.nic.it/v1/invoices/1212/payment" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}

http https://api.nic.it/v1/invoices/1212/payment \
    "Authorization: Bearer token..."

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}