Documentazione per sviluppatori

Panoramica

L'API REST consente di sincronizzare dati tra il tuo sistema e la piattaforma AML Guardian. Ogni richiesta è associata all'azienda (ente utilizzatore) tramite un token API dedicato. Le regole di validazione sono le stesse del portale web.

Le operazioni sui clienti usano application/json. Il caricamento documenti usa multipart/form-data. Tutte le richieste devono usare HTTPS.

Indice API

Riepilogo di tutti gli endpoint previsti nella versione 1.

Clienti

Documenti cliente

Autenticazione

Il token API viene fornito da AML Guardian in fase di attivazione dell'integrazione. Includilo nell'header HTTP Authorization su tutte le richieste:

Authorization: Bearer <API_TOKEN>

Formato alternativo equivalente:

Authorization: Token <API_TOKEN>

Endpoint

Campi dati

Obbligatori (creazione)

Opzionali — anagrafica e contatti

Titolari effettivi (fino a 4) e terzo pagatore

Per n da 1 a 4: titolare_effettivo_{n}_denominazione, titolare_effettivo_{n}_codice_fiscale. Terzo pagatore: terzo_pagatore_denominazione, terzo_pagatore_codice_fiscale.

Sola lettura (risposta)

id, data_creazione, data_modifica, attivo, livello_rischio, data_profilatura.

Validazioni

• Codice fiscale obbligatorio in creazione e univoco su tutta la piattaforma.
• Partita IVA univoca se valorizzata.
• Persona Giuridica (tipo=PG): legale_rappresentante obbligatorio.
• Ruolo committente/debitore solo per enti 115 TULPS; altrimenti default debitore.
• I valori testuali vengono normalizzati in maiuscolo.

Esempi

Creazione persona fisica

{
  "tipo": "PF",
  "denominazione": "Mario Rossi",
  "codice_fiscale": "RSSMRA80A01H501Z",
  "email": "mario.rossi@example.com",
  "telefono": "02 1234567",
  "indirizzo": "Via Roma 1, 20100 Milano",
  "tipo_rapporto": "occasionale",
  "is_pep": false
}

Aggiornamento parziale

{
  "email": "nuova.email@example.com",
  "telefono": "3331234567"
}

Endpoint

I documenti sono sempre collegati a un cliente esistente. Dopo il caricamento sono visibili nella scheda cliente del portale web (identità, visure, procure, allegati).

Campi e tipologie

Campi upload (POST multipart)

Valori tipo

Valori soggetto_collegato (documento d'identità)

Per enti 115 TULPS sono ammessi anche persona_fisica_debitore e persona_fisica_committente. Per le altre tipologie di soggetto obbligato si usa persona_fisica al posto delle varianti debitore/committente.

Risposta (metadati documento)

id, tipo, tipo_display, descrizione, denominazione, soggetto_collegato, data_emissione, data_scadenza, nome_file, url_download, data_caricamento, is_scaduto, in_scadenza.

Validazioni

• Il cliente {id} deve esistere e appartenere all'azienda del token.
• Il campo file è obbligatorio in creazione; dimensione massima concordata in fase di attivazione.
• Formati accettati tipici: application/pdf, image/jpeg, image/png.
• soggetto_collegato e denominazione sono rilevanti principalmente per tipo=identita.
• Valori soggetto_collegato non ammessi per la tipologia di ente vengono ignorati.
• La PATCH non sostituisce il file: per aggiornare l'allegato eliminare e ricaricare il documento.

Esempi

Caricamento documento d'identità

POST /api/v1/clienti/42/documenti/ HTTP/1.1
Authorization: Bearer <API_TOKEN>
Content-Type: multipart/form-data; boundary=----boundary

------boundary
Content-Disposition: form-data; name="tipo"

identita
------boundary
Content-Disposition: form-data; name="denominazione"

Mario Rossi
------boundary
Content-Disposition: form-data; name="soggetto_collegato"

persona_fisica
------boundary
Content-Disposition: form-data; name="data_scadenza"

2030-12-31
------boundary
Content-Disposition: form-data; name="file"; filename="carta_identita.pdf"
Content-Type: application/pdf

(binary content)
------boundary--

Esempio con cURL

curl -X POST "https://amlguardian.it/api/v1/clienti/42/documenti/" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F "tipo=visura" \
  -F "descrizione=Visura camerale ordinaria" \
  -F "file=@visura_acme.pdf"

Risposta elenco documenti (200)

{
  "count": 2,
  "results": [
    {
      "id": 101,
      "tipo": "identita",
      "tipo_display": "Documento d'identità",
      "denominazione": "Mario Rossi",
      "soggetto_collegato": "persona_fisica",
      "data_scadenza": "2030-12-31",
      "nome_file": "carta_identita.pdf",
      "url_download": "https://amlguardian.it/api/v1/clienti/42/documenti/101/download/",
      "data_caricamento": "2026-06-11T14:20:00Z",
      "is_scaduto": false,
      "in_scadenza": false
    },
    {
      "id": 102,
      "tipo": "visura",
      "tipo_display": "Visura Camerale",
      "nome_file": "visura_acme.pdf",
      "data_caricamento": "2026-06-11T14:25:00Z"
    }
  ]
}

Aggiornamento scadenza documento

{
  "data_scadenza": "2035-06-30",
  "descrizione": "Carta d'identità elettronica — rinnovata"
}

Codici di risposta HTTP

Note operative

• Flusso consigliato: crea il cliente via API, poi carica i documenti sul relativo id.
• Adeguata verifica, profilatura del rischio e monitoraggio restano gestiti dal portale web.
• I documenti caricati via API compaiono immediatamente nella scheda cliente del portale.
• Per ambienti di test è disponibile un token dedicato (da concordare con il supporto).
• Ogni integrazione richiede accordo su volumi, dimensioni file e responsabilità del trattamento dati.

Supporto e attivazione

Per richiedere il token API, l'ambiente di test o la rigenerazione delle credenziali, contattaci indicando la denominazione dell'ente e il sistema da integrare.