API Reference

Benvenuto nella documentazione ufficiale di StrumentiDev. La nostra API REST ti permette di integrare i calcoli fiscali e il database dei comuni direttamente nelle tue applicazioni.

Autenticazione

Tutte le richieste devono includere la tua chiave nell'header x-api-key.

# Header richiesto
x-api-key: sd_live_xxxxxxxxxxxxxxxx

POST

Strumenti Codice Fiscale

ENDPOINT: /v1/cf-api

1. Calcolo (Singolo o Lote)

Permette di calcolare il codice fiscale passando i dati anagrafici. Supporta anche array di oggetti per calcoli multipli.

Proprietà	Tipo	Descrizione
action	string	Deve essere `"calculate"`.
data	object \| array	Dati anagrafici. Può essere un singolo oggetto o un array (max 20).
↳ nome	string	Nome della persona.
↳ cognome	string	Cognome della persona.
↳ dataNascita	string	Formato ISO `YYYY-MM-DD`.
↳ sesso	string	`M` o `F`.
↳ belfiore	string	Codice catastale del comune o nazione (es: H501).

Request Body

                    
{
  "action": "calculate",
  "data": [
    { "nome": "Mario",
     "cognome": "Rossi",
      "dataNascita": "1980-01-01",
       "sesso": "M",
        "belfiore": "H501" }
  ]
}

Response 200

                  
                    {
  "success": true,
  "action": "calculate",
  "results": [
      {
          "input": {
              "nome": "Mario",
              "cognome": "Rossi",
              "dataNascita": "1980-01-01",
              "sesso": "M",
              "belfiore": "H501"
          },
          "codiceFiscale": "RSSMRA80A01H501U"
      }
  ],
  "usage": {
      "consumed": 1,
      "remaining": 99
  }
}

2. Generazione Casuale

Genera dati realistici e codici fiscali validi per test. Massimo 20 per richiesta.

Proprietà	Tipo	Descrizione
action	string	Deve essere `"generate"`.
count	number	Numero di CF da generare (Min: 1, Max: 20). Default: 1.
fullData	boolean	Se `true`, restituisce l'anagrafica completa.

Request Body

                    
{
  "action": "generate",
  "count": 2,
  "fullData": true
}

Response 200

                  
{
    "success": true,
    "action": "generate",
    "results": [
        {
            "nome": "MARIA FIORELLA",
            "cognome": "TURETTA",
            "sesso": "F",
            "dataNascita": "1991-10-14",
            "luogoDiNascita": "Agrate Brianza (MB)",
            "belfiore": "A087",
            "codiceFiscale": "TRTMFR91R54A087B"
        },
        {
            "nome": "JONE",
            "cognome": "SKENDERI",
            "sesso": "F",
            "dataNascita": "1990-02-25",
            "luogoDiNascita": "Altilia (CS)",
            "belfiore": "A234",
            "codiceFiscale": "SKNJNO90B65A234M"
        }
    ],
    "usage": {
        "consumed": 2,
        "remaining": 98
    }
}

Codici di Errore

Codice	Descrizione
401	API Key mancante o non valida.
429	Quota mensile esaurita. Fai upgrade.
400	Azione non valida o dati mancanti.

POST

Strumenti Partita IVA

ENDPOINT: /v1/piva-api

1. Validazione (Singola o Lote)

Verifica se una o più Partite IVA sono formalmente corrette secondo l'algoritmo di controllo italiano.

Proprietà	Tipo	Descrizione
action	string	Deve essere `"validate"`.
data	string \| array	P.IVA singola o array di stringhe (max 50).

Request Body

{
  "action": "validate",
  "data": [
    "23905139079",
    "12733292473"
  ]
}

Response 200

{
  "success": true,
  "results": [
    { "partitaIva": "23905139079", "valid": true },
    { "partitaIva": "12733292473", "valid": true }
  ],
  "usage": { "consumed": 2, "remaining": 98 }
}

2. Generazione Casuale

Genera numeri di Partita IVA sintatticamente corretti per scopi di test.

Proprietà	Tipo	Descrizione
action	string	Deve essere `"generate"`.
count	number	Numero di P.IVA da generare (Max: 20).

Request Body

{
  "action": "generate",
  "count": 2
}

Response 200

{
  "success": true,
  "results": [
    "62431163674",
    "83128597685"
  ],
  "usage": { "consumed": 2, "remaining": 96 }
}

POSTREAL-TIME

VIES Check (Live Verification)

Verifica in tempo reale se una Partita IVA è attiva e registrata nel sistema europeo VIES. Essenziale per operazioni intracomunitarie e per ottenere i dati anagrafici ufficiali di un'azienda.

Endpoint & Parametri

ENDPOINT: /v1/vies-api

Campo	Tipo	Descrizione
countryCode	string	Codice ISO del paese (es: "IT", "DE", "FR").
vatNumber	string	Numero di Partita IVA senza prefisso internazionale.

Request Body

{
  "countryCode": "IT",
  "vatNumber": "07231500963"
}

Response 200 (Success)

{
  "success": true,
  "result": {
    "countryCode": "IT",
    "vatNumber": "07231500963",
    "valid": true,
    "businessName": "STELLANTIS EUROPA S.P.A.",
    "businessAddress": "CORSO AGNELLI 200 10135 TORINO TO",
    "requestDate": "2026-02-04T22:45:00Z"
  },
  "usage": {
    "consumed": 1,
    "remaining": 99
  }
}

* Nota: businessName e businessAddress potrebbero essere nulli se il paese membro non ne autorizza la pubblicazione.

Hai bisogno di più potenza?

Il piano gratuito permette test limitati. Passa al piano Pro per volumi elevati.