← Home

API Reference

Finca REST API v1

Autenticazione

Tutte le API protette richiedono un JWT Bearer token.

POST/auth/registerRegistra un nuovo utente

Request Body

{
  "email": "[email protected]",
  "password": "minimo8caratteri"
}

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "role": "base",
    "visureConsumed": 0,
    "visureLimit": 100000
  }
}
POST/auth/loginLogin — ritorna JWT

Request Body

{
  "email": "[email protected]",
  "password": "password123"
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci...",
    "expiresIn": 3600
  }
}
POST/auth/googleLogin/registrazione via Google

Request Body

{
  "email": "[email protected]"
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}
GET/auth/meJWTProfilo utente corrente

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "role": "premium",
    "visureConsumed": 1250,
    "visureLimit": 100000
  }
}

Catasto

GET/catasto/provinceJWTLista province spagnole

Response

{
  "success": true,
  "data": [
    { "codice": "28", "nome": "MADRID" },
    { "codice": "08", "nome": "BARCELONA" }
  ]
}
GET/catasto/province/MADRID/comuniJWTComuni per provincia

Response

{
  "success": true,
  "data": [
    { "codiceProvincia": "28", "codiceMunicipio": "79", "nome": "MADRID" },
    { "codiceProvincia": "28", "codiceMunicipio": "5", "nome": "ALCALA DE HENARES" }
  ]
}
GET/catasto/scan?provincia=MADRID&municipio=MADRIDJWTScansiona comune — trova reference catastali reali

Response

{
  "success": true,
  "data": [
    { "numero": "45", "referenzaCatastale": "1047206VK4714G", "tipoVia": "CL", "nomeVia": "ALCALA" },
    { "numero": "48", "referenzaCatastale": "1146801VK4714E", "tipoVia": "CL", "nomeVia": "ALCALA" }
  ]
}
GET/catasto/reference/1047206VK4714G?provincia=MADRID&municipio=MADRIDJWTDettaglio reference catastale

Response

{
  "success": true,
  "data": [
    { "referenzaCatastale": "1047206VK4714G0001ZH", "uso": "Oficinas", "superficie": "15786" }
  ]
}
POST/favoritesJWTSalva nei preferiti

Request Body

{
  "referenceId": "1047206VK4714G",
  "label": "CL ALCALA 45",
  "provincia": "MADRID",
  "municipio": "MADRID"
}

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "referenceId": "1047206VK4714G",
    "label": "CL ALCALA 45"
  }
}

Acquisizione Visure

POST/crawler/startJWTAvvia acquisizione batch

Request Body

{
  "references": [
    { "idReference": "1047206VK4714G", "codiceProvincia": "MADRID", "codiceMunicipio": "MADRID" },
    { "idReference": "1146801VK4714E", "codiceProvincia": "MADRID", "codiceMunicipio": "MADRID" }
  ]
}

Response

{
  "success": true,
  "data": {
    "totalJobs": 2,
    "visureIds": ["uuid-1", "uuid-2"]
  }
}
GET/crawler/progressJWTStato avanzamento

Response

{
  "success": true,
  "data": {
    "total": 150,
    "completed": 142,
    "errors": 3,
    "pending": 5
  }
}
GET/crawler/visure/{id}JWTDettaglio visura

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "idReference": "1047206VK4714G",
    "stato": "completed",
    "r2Key": "visure/user-id/1047206VK4714G.json",
    "createdAt": "2026-04-15T17:34:06Z",
    "completedAt": "2026-04-15T17:34:08Z"
  }
}
GET/crawler/visure/{id}/dataJWTJSON completo della visura

Response

{
  "success": true,
  "data": "{"consulta_dnprcResult":{"bico":{"bi":{...}}}}"
}

Abbonamento

GET/billing/subscriptionJWTStato abbonamento

Response

{
  "success": true,
  "data": {
    "userId": "uuid",
    "role": "premium",
    "visureConsumed": 1250,
    "visureLimit": 100000,
    "visureRemaining": 98750
  }
}
POST/billing/checkout/premiumJWTUpgrade a Premium via Stripe

Request Body

{
  "successUrl": "https://finca.elevenhats.it/dashboard/billing?success=premium",
  "cancelUrl": "https://finca.elevenhats.it/dashboard/billing"
}

Response

{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "url": "https://checkout.stripe.com/..."
  }
}
POST/billing/checkout/visureJWTAcquista ricarica visure

Request Body

{
  "quantity": 10000,
  "successUrl": "https://finca.elevenhats.it/dashboard/billing?success=visure",
  "cancelUrl": "https://finca.elevenhats.it/dashboard/billing"
}

Response

{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "url": "https://checkout.stripe.com/..."
  }
}

Rate Limiting e Cache

  • Base: 1 richiesta/secondo verso il Catasto
  • Premium: 1.200 visure/minuto
  • Cache: province e comuni cachati 7 giorni, vie e reference 24 ore

Contatti

Per supporto API: [email protected]