Vai al contenuto

Guida di integrazione — OS Sinistri Partner Integration v2

Versione

Ambiente UAT — contratto OpenAPI 3.1.0, versione "UAT 2026-09-21". Documento sorgente v4.0 del 21 settembre 2026. Riservato, esclusivamente per uso del partner.

Voce Valore
Ambiente UAT
Base URL https://testoverx-sinistri-api.elbassicurazioni.it/api/v1/integration
Perimetro Esclusivamente gli endpoint sotto /partnerIntegration
Autenticazione Bearer JWT (via ext-sicurezza/login)
Contratto di riferimento REVO OverX Sinistri — Partner Integration API (v2), OpenAPI 3.1.0, versione "UAT 2026-09-21"

Perimetro

Questo documento descrive soltanto la superficie /partnerIntegration (Partner Integration v2). La superficie storica /claims, descritta nelle edizioni precedenti della documentazione, non fa parte del perimetro del partner e non è trattata qui: espone identificativi tecnici interni REVO (identificativo del titolo amministrativo, identificativi dei beni assicurati) che il layer v2 esiste proprio per non far maneggiare al chiamante.

1. Introduzione e overview

Questo documento descrive le API di integrazione destinate ai partner esterni di OverX Sinistri, esposte sotto il dominio /api/v1/integration e, al suo interno, sotto il prefisso /partnerIntegration.

Il contratto è orientato al dominio: il partner indica sinistro, danneggiato e garanzia per riferimento di business, e il back-end deduce dal contesto di polizza i parametri tecnici (titolo amministrativo, garanzia colpita, processo, riserva di apertura). Nessun identificativo interno REVO è richiesto in ingresso.

1.1 Le due famiglie di comportamento

  • Operazioni di lettura (GET): sincrone. Restituiscono la risposta direttamente nel body HTTP.
  • Operazioni di scrittura (POST/PUT): asincrone. Richiedono l'header requestId e rispondono 201 con una ricevuta di presa in carico. Per sei di esse l'esito effettivo si legge in pull su GET /partnerIntegration/claim/status?requestId=.
  • Una sola operazione restituisce l'esito nella risposta HTTP: POST /partnerIntegration/claim/email, che risponde 200 con l'esito dell'invio. Il core non espone un endpoint di invio email: l'invio non attraversa il listener del core, va direttamente a cContact e non produce un requestId interrogabile.
  • Due operazioni sono asincrone ma cieche: PUT /partnerIntegration/claim/injured-party e POST /partnerIntegration/claim/documents rispondono 201 con un requestId che non è interrogabile su /claim/status. Non sono sincrone — il lavoro lo fa un worker dopo la risposta — ma il loro esito non è leggibile per requestId. Si veda 4.1: è il punto più importante di questo documento.

Differenza rispetto alla documentazione v3.3

Le edizioni precedenti indicavano che l'esito delle operazioni asincrone "può essere notificato via WebHook". Per i partner esterni non è così. Non esiste alcuna notifica push verso il chiamante e non va implementato alcun endpoint di callback: l'esito si recupera esclusivamente in pull, interrogando GET /partnerIntegration/claim/status. Si veda il capitolo 4.

1.2 Che cosa copre il perimetro v2

Il contratto espone 13 path e 14 operazioni, raggruppate per area funzionale:

Area Operazioni
Apertura e stato Creazione sinistro, lettura dell'esito asincrono, dati economici del sinistro
Danneggiato Inserimento o aggiornamento del danneggiato sul sinistro
Riserve Aggiornamento delle riserve delle garanzie aperte
Pagamenti Registrazione del pagamento e suo annullamento
Riapertura Riapertura di un sinistro chiuso
Chiusura Chiusura senza seguito e lettura dei motivi ammessi
Documenti ed email Elenco, caricamento e download degli allegati; invio email per conto del sinistro

2. Autenticazione

Tutte le operazioni richiedono l'header Authorization: Bearer <ACCESS_TOKEN_JWT>. Il contratto dichiara un unico schema di sicurezza, bearerToken (HTTP bearer, formato JWT), applicato a tutte e 14 le operazioni.

L'access token è un JWT firmato che rappresenta l'identità dell'utente e i suoi ruoli; si ottiene fuori dal dominio /integration, tramite il servizio di sicurezza dedicato.

2.1 Ottenere il token (login)

POST https://testoverx-api.elbassicurazioni.it/api/v1/ext-sicurezza/login
Content-Type: application/json

{
  "username": "<USERNAME>",
  "password": "<PASSWORD>"
}

Risposta:

{
  "access_token": "<ACCESS_TOKEN_JWT>",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "<REFRESH_TOKEN_JWT>",
  "token_type": "Bearer",
  "session_state": "00000000-0000-0000-0000-000000000000",
  "scope": "email profile"
}

Endpoint fuori contratto

L'endpoint di login non fa parte del contratto Partner Integration v2 e non è descritto nel relativo file OpenAPI: host, payload e forma della risposta sono quelli già in uso e invariati rispetto alla v3.3.

2.2 Utilizzo

In ogni richiesta aggiungere:

Authorization: Bearer <ACCESS_TOKEN_JWT>

2.3 Scadenza e refresh

Il token scade dopo l'intervallo indicato in expires_in (tipicamente 1800 secondi). In caso di token scaduto il sistema risponde con 401 Unauthorized. È possibile ottenere un nuovo access_token ripetendo il login oppure usando il refresh_token se previsto dall'integrazione. Si raccomanda di rinnovare il token prima della scadenza per evitare interruzioni di flusso.

2.4 Troubleshooting

Codice Causa
401 Token mancante, scaduto o con formato non valido
403 Token valido ma ruolo/ambito insufficiente per l'endpoint richiesto

Non desumibile dal contratto

Il file OpenAPI v2 dichiara lo schema di sicurezza ma non elenca le risposte 401 e 403 fra quelle delle singole operazioni. La tabella qui sopra riporta il comportamento già documentato nella v3.3 e non è verificabile sul contratto attuale.

3. Pattern cross-cutting

3.1 requestId e comportamento asincrono

Tutte le operazioni di scrittura richiedono l'header requestId: <UUID>, generato dal client per ogni chiamata (il contratto lo dichiara obbligatorio, di tipo stringa in formato UUID). Questo identificativo abilita:

  • Correlazione: associare l'esito letto su /claim/status alla chiamata REST originante — per le sei operazioni per cui quell'esito è leggibile (si veda 4.1).
  • Tracciamento: collegare log lato client e lato server tramite il correlationId restituito dal back-end.
  • Chiave di annullamento: per i pagamenti è il requestId usato in creazione a identificare il pagamento da stornare (si veda 6.8).

La risposta immediata delle operazioni di scrittura è sempre una ricevuta di presa in carico (PartnerOperationResponseDTO):

{
  "requestId":     "<UUID inviato dal client nell'header>",
  "correlationId": "<UUID generato dal back-end>",
  "entityId":      "<UUID dell'entita' creata o modificata>"
}

L'unica operazione di scrittura con risposta diversa è POST /partnerIntegration/claim, che restituisce la stessa ricevuta arricchita dal blocco riservaApplicata (si veda 6.1).

Attenzione

Il requestId è la sola chiave con cui si legge l'esito dell'operazione. Va generato nuovo per ogni chiamata, persistito lato partner e mai riutilizzato: riutilizzarlo rende ambigua la correlazione fra richiesta ed esito.

3.2 Come si indica il sinistro

Tutte le operazioni successive all'apertura identificano il sinistro con il blocco sinistro (ClaimReferenceDTO), che espone tre riferimenti di business alternativi. Il contratto prescrive che ne sia valorizzato esattamente uno:

Campo Significato Esempio
numeroSinistro Numero sinistro pubblico REVO ELB.26.1234567.0
numeroSinistroEsterno Numero sinistro nel sistema del partner —
numeroSinistroBroker Riferimento sinistro del broker —
  • Nessun riferimento valorizzato, oppure più di uno: 422.
  • Riferimento che individua più di un sinistro: 409, con i candidati elencati nel messaggio di errore.
  • Riferimento che non individua alcun sinistro: 404.

Eccezioni

Due operazioni non usano questo blocco: GET /partnerIntegration/claim/financials prende un query param sinistroId (numero sinistro REVO, accettato anche nella forma con il suffisso del liquidatore), e le due operazioni sui documenti usano i tre riferimenti come query param piatti (si vedano 6.12 e 6.13).

3.3 Convenzione sui codici di garanzia

È l'errore più facile da commettere. La garanzia si indica come coppia in due campi distinti: codiceGaranzia senza il punto (es. 00001) e codicePrestazione (es. 1699). Il codice puntato 00001.1699 è la forma con cui la garanzia è memorizzata e in ingresso viene rifiutato con 422.

Il blocco garanzia (GaranziaReferenceDTO) ha tre campi:

Campo Descrizione
codiceGaranzia Codice garanzia, senza la parte di prestazione e senza punto
codicePrestazione Codice prestazione (sotto-garanzia)
chiaveGaranzia Chiave di garanzia: disambigua due coperture che condividono la stessa coppia (codice, prestazione)

Gli attributi tecnici della garanzia (productCoverCode, chiaveRischio, keyCondizione) non sono input: li risolve il back-end sulla garanzia già aperta.

Eccezione sulla riapertura

Su POST /partnerIntegration/claim/reopen la garanzia si indica con il solo codiceGaranzia: codicePrestazione e chiaveGaranzia non sono ammessi e producono 400. La ragione dichiarata dal contratto è che la risoluzione della riapertura non discrimina su quei campi, e accettarli senza usarli farebbe credere al chiamante di aver disambiguato.

3.4 esecutorePagamento

Sul pagamento il campo esecutorePagamento dichiara chi esegue materialmente il pagamento. I valori ammessi sono REVO e PARTNER. Se il campo è assente vale REVO.

3.5 Semantica degli errori

Il layer v2 usa i codici HTTP in modo uniforme su tutte le operazioni:

HTTP Significato Che cosa deve fare il partner
422 Violazione di schema: il payload non rispetta il contratto (riferimento al sinistro assente o multiplo, blocchi obbligatori mancanti, importo non positivo, codiceGaranzia indicato in forma puntata) Correggere il payload. Ripetere la stessa richiesta non cambia l'esito.
400 Fallimento in fase di risoluzione: la richiesta è sintatticamente accettabile ma non interpretabile (dati di business non validi, campi non ammessi su quell'operazione) Correggere i dati di business indicati nel messaggio.
404 Non trovato: sinistro, danneggiato, garanzia, allegato o pagamento inesistenti in base ai riferimenti forniti Verificare i riferimenti prima di riprovare.
409 Riferimento ambiguo: i riferimenti forniti individuano più di un candidato. I candidati sono elencati nel messaggio Restringere il riferimento scegliendo fra i candidati indicati.
500 Il core non ha confermato la presa in carico: nulla è stato accettato e non esiste un requestId da interrogare Ripetere la richiesta.

Il 500 non è un esito incerto

Sulle operazioni di scrittura il contratto dichiara esplicitamente che un 500 significa che l'operazione NON è stata accettata e che non esiste un requestId da interrogare su /claim/status. Non va quindi avviato alcun polling: la richiesta va semplicemente ripetuta.

Differenza di formulazione

Su POST /partnerIntegration/claim il contratto formula il 500 in modo generico ("errore interno inatteso del servizio") anziché con la formula "il core non ha confermato la presa in carico" usata sulle altre operazioni di scrittura. La conseguenza operativa per il partner è la stessa — ripetere la richiesta — ma il contratto non le formula in modo identico.

Struttura del body di errore. Tutte le risposte di errore seguono la struttura ExceptionObject:

{
  "status": 5422,
  "error": "NoValidEntity",
  "message": "<descrizione>"
}

Non desumibile dal contratto

Il campo status è dichiarato dal contratto come intero. Nella v3.3 usava una codifica applicativa a quattro cifre (5400, 5404, 5422) distinta dallo status HTTP: il contratto v2 non dichiara quali valori assuma, quindi la corrispondenza fra status interno e codice HTTP non è desumibile dal contratto. Il partner deve in ogni caso gestire lo status HTTP, e registrare error e message per la diagnostica.

3.6 Campi accettati ma non propagati

Alcuni campi del pagamento sono dichiarati dal contratto come accettati per parità con il v1 ma NON propagati al core. Il partner può valorizzarli — la richiesta non viene rifiutata — ma non produrranno alcun effetto a valle:

Campo Operazione Comportamento dichiarato
causale POST /claim/payment Accettato, non propagato al core
quietanza POST /claim/payment Accettato, non propagato al core
recuperi POST /claim/payment Accettato, non propagato al core
chiaveRiconciliazioneAssistenza POST /claim/payment e POST /claim/payment/{requestIdPagamento}/cancel Accettato, non propagato al core

valuta si comporta diversamente

Il campo valuta del pagamento non è semplicemente ignorato: se valorizzato deve coincidere con la valuta del sinistro, altrimenti la richiesta viene rifiutata. Quando coincide non viene comunque propagato al core, che usa la valuta del sinistro.

3.7 Formato dati

  • Date: formato ISO-8601 yyyy-MM-dd per tutti i campi dichiarati date (es. 2026-05-10).
  • Date-time: formato ISO-8601 completo per i campi dichiarati date-time (metadati degli allegati).
  • Mese di estratto conto: formato MM-AAAA (es. 09-2026) per mmAaaaEstrattoConto.
  • UUID: per requestId, correlationId, entityId e allegatoId.
  • Enumerazioni: rispettare i valori esatti dichiarati dal contratto (elencati nel dettaglio di ciascuna operazione).

Non desumibile dal contratto

Il contratto v2 non dichiara alcun parametro di paginazione: nessuna delle operazioni di lettura espone page o size.

4. Esito delle operazioni asincrone

Le operazioni di scrittura rispondono 201 con la sola ricevuta di presa in carico: la risposta HTTP non dice se l'operazione è andata a buon fine. L'esito effettivo si recupera in pull, interrogando:

GET /partnerIntegration/claim/status?requestId=<UUID inviato in creazione>

La risposta 200 ha la forma (ClaimStatusDTO):

{
  "status":      "SUCCESS | FAILED | PENDING",
  "code":        "<codice di errore, valorizzato a esito FAILED>",
  "description": "<descrizione dell'esito>",
  "sinistroId":  "<identificativo interno del sinistro (UUID), valorizzato a esito SUCCESS>"
}
status Significato Comportamento atteso del partner
SUCCESS L'operazione è stata completata. Il campo sinistroId è valorizzato Interrompere il polling e procedere.
FAILED L'operazione è fallita. I campi code e description descrivono la causa Interrompere il polling, registrare code e description, correggere e ripetere con un nuovo requestId.
PENDING L'operazione è ancora in lavorazione. Lo stesso valore viene restituito anche per un requestId non ancora noto al sistema Continuare il polling.

PENDING non distingue \"in corso\" da \"mai ricevuto\"

Il contratto dichiara esplicitamente che PENDING viene restituito anche per un requestId non ancora noto. Un polling che riceve sempre PENDING non prova che la richiesta sia stata acquisita: va previsto un numero massimo di tentativi lato partner. Il contratto non dichiara né un intervallo di polling raccomandato né un tempo massimo di elaborazione.

4.1 Che cosa copre /claim/status, e le due operazioni che non copre

Il polling per requestId copre sei delle otto operazioni di scrittura:

# Operazione Che cosa se ne legge
1 POST /partnerIntegration/claim Apertura sinistro
2 POST /partnerIntegration/claim/payment Registrazione del pagamento
3 POST /partnerIntegration/claim/payment/{requestIdPagamento}/cancel Annullamento del pagamento
4 PUT /partnerIntegration/claim/reserves Aggiornamento delle riserve
5 POST /partnerIntegration/claim/reopen Riapertura del sinistro
6 POST /partnerIntegration/claim/closure Chiusura senza seguito

Verificato sull'ambiente di test:

# Operazione Esito su /claim/status
1 Apertura sinistro Risolve in SUCCESS pochi secondi dopo il 201; sinistroId è l'identificativo interno del sinistro (coincide con l'entityId della ricevuta)
6 Chiusura senza seguito Risolve in SUCCESS; il sinistro passa allo stato SENZA SEGUITO
5 Riapertura Risolve (non resta PENDING): in caso di rifiuto restituisce FAILED con code 7500 e il motivo in description
2 Registrazione pagamento Risolve in SUCCESS; il pagamento è registrato con stato EMESSO
3 Annullamento pagamento Risolve ma può restituire FAILED con code 7500 (es. Errore in Esitazione Pagamento Istantaneo: Nessun Esito trovato per Pagamento Istantaneo) anche quando la data e la motivazione di storno risultano registrate sul pagamento: l'esito FAILED non va letto come "annullamento non eseguito"
4 Riserve Non verificata con successo sull'ambiente di test (la garanzia A001 non viene risolta, 404)

Le due operazioni il cui esito NON è interrogabile — da leggere prima di implementare

PUT /partnerIntegration/claim/injured-party e POST /partnerIntegration/claim/documents rispondono 201 con un requestId, ma per queste due operazioni l'esito non è interrogabile su /claim/status: quel requestId resta PENDING per sempre. Un polling su di esso non terminerà mai con SUCCESS né con FAILED.

Non si tratta di operazioni sincrone. Entrambe sono realmente asincrone: il lavoro vero — la scrittura del danneggiato, lo spostamento dell'allegato nella cartella definitiva — lo esegue un worker dopo aver consumato il messaggio. Il partner riceve il 201 quando quel lavoro non è ancora stato fatto, e non ha modo di sapere dal requestId se poi è andato a buon fine.

Verificato: il danneggiato e l'allegato vengono scritti regolarmente, ma il loro requestId non risolve mai in SUCCESS.

Come si verifica l'esito di queste due operazioni, finché il difetto non è risolto:

Operazione Come si verifica che sia andata a buon fine
PUT /partnerIntegration/claim/injured-party Rileggendo il sinistro e verificando la presenza del danneggiato con la chiave naturale (tipo danneggiato + codice fiscale o partita IVA) usata nella richiesta
POST /partnerIntegration/claim/documents Con GET /partnerIntegration/claim/documents: l'allegato è stato acquisito quando compare nell'elenco restituito, con il proprio allegatoId

Avvertenza sul contratto pubblicato

La descrizione di POST /partnerIntegration/claim/documents nel file OpenAPI afferma che "l'esito si legge su GET /partnerIntegration/claim/status?requestId=". Quell'affermazione non corrisponde al comportamento reale e non va usata come base di implementazione: vale quanto documentato in questo paragrafo.

4.2 Nessuna notifica push

Il contratto v2 non prevede webhook, callback o altra forma di notifica push verso il partner: non è dichiarato alcun endpoint di callback, alcun payload di notifica, alcuna politica di retry di consegna. Il partner non deve implementare alcun endpoint di ricezione. Il modello è esclusivamente in pull.

5. Tabella riepilogativa degli endpoint

Tutti i path sono relativi alla base URL https://testoverx-sinistri-api.elbassicurazioni.it/api/v1/integration. La colonna ReqID indica se l'header requestId è obbligatorio.

# Metodo Endpoint Descrizione ReqID Pattern
1 POST /partnerIntegration/claim Apertura sinistro da partner esterno Sì Asincrono
2 GET /partnerIntegration/claim/status Esito dell'operazione asincrona per requestId No Sincrono
3 GET /partnerIntegration/claim/financials Dati economici del sinistro No Sincrono
4 PUT /partnerIntegration/claim/reserves Aggiornamento delle riserve Sì Asincrono
5 PUT /partnerIntegration/claim/injured-party Upsert del danneggiato Sì Asincrono, esito NON interrogabile*
6 POST /partnerIntegration/claim/reopen Riapertura di un sinistro chiuso Sì Asincrono
7 POST /partnerIntegration/claim/payment Registrazione di un pagamento Sì Asincrono
8 POST /partnerIntegration/claim/payment/{requestIdPagamento}/cancel Annullamento di un pagamento Sì Asincrono
9 POST /partnerIntegration/claim/closure Chiusura senza seguito Sì Asincrono
10 GET /partnerIntegration/claim/closure/reasons Motivi di chiusura senza seguito ammessi No Sincrono
11 POST /partnerIntegration/claim/email Invio email per conto del sinistro No Esito nella risposta HTTP
12 GET /partnerIntegration/claim/documents Elenco degli allegati del sinistro No Sincrono
13 POST /partnerIntegration/claim/documents Caricamento di un allegato Sì Asincrono, esito NON interrogabile*
14 GET /partnerIntegration/claim/documents/{allegatoId} Download di un allegato No Sincrono

* Operazione asincrona che risponde 201 con un requestId, ma il cui esito NON è interrogabile su /claim/status: quel requestId resta PENDING per sempre. L'esito va verificato rileggendo lo stato del sinistro — si veda 4.1, che indica la via che funziona per ciascuna delle due.

6. Dettaglio delle operazioni

Le sezioni seguenti documentano ciascuna operazione con descrizione, parametri, corpo della richiesta, corpo della risposta e codici di esito dichiarati dal contratto.

6.1 POST /partnerIntegration/claim — Apertura sinistro

A cosa serve. Crea un nuovo sinistro a partire da un payload normalizzato e orientato al dominio: polizza, evento, danneggiato, comunicazioni. I parametri tecnici (garanzia colpita, processo, riserva di apertura) vengono dedotti dal contesto di polizza e dalle regole di business.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim
  • Header obbligatori: Authorization: Bearer <ACCESS_TOKEN_JWT>, requestId: <UUID>
  • Body: ClaimCreatePartnerDTO (application/json)

Richiesta. Blocchi obbligatori dichiarati dal contratto: polizza ed evento.

Campo Obbl. Descrizione
numeroSinistroEsterno No Riferimento sinistro nel sistema esterno/delegataria
numeroSinistroBroker No Riferimento sinistro nel sistema del broker
polizza Sì Blocco di riferimento polizza (PolizzaDTO)
evento Sì Blocco dati evento (EventoDTO)
danneggiato No Blocco dati soggetto danneggiato (DanneggiatoDTO)
comunicazioni No Indirizzi email che riceveranno la conferma di apertura

Blocco polizza (PolizzaDTO):

Campo Descrizione
numeroPolizza Numero polizza REVO. Obbligatorio in alternativa a idPolizzaEsterna
idPolizzaEsterna Identificativo polizza esterno fornito dal chiamante. Obbligatorio in alternativa a numeroPolizza
ramo Codice ramo di polizza. Facoltativo; può diventare obbligatorio se la polizza presenta più rami
chiaveGaranzia Chiave garanzia (facoltativa)
codiceGaranzia Codice garanzia/copertura (facoltativo)
codicePrestazione Codice prestazione/servizio (facoltativo)
riservaApertura Importo della riserva in apertura (facoltativo). Se valorizzato prevale sul default profilato per l'utenza chiamante

Se nessuno dei campi di garanzia è valorizzato, il sistema seleziona la prima garanzia disponibile.

Blocco evento (EventoDTO) — obbligatori dataEvento e descrizione:

Campo Obbl. Descrizione
dataEvento Sì Data dell'evento che ha generato il sinistro (yyyy-MM-dd)
descrizione Sì Descrizione completa dell'evento
dataDenuncia No Data di denuncia. Se assente, il sistema utilizza la data di ricezione
dataRichiestaRisarcimento No Data richiesta risarcimento (Claims Made)
dataNotificaCircostanza No Data notifica circostanza (Claims Made). Può coesistere con dataRichiestaRisarcimento
luogoEvento No Luogo strutturato (indirizzo, comune, provincia, nazione, cap). L'eventuale obbligatorietà dipende da ramo/prodotto/processo

Claims Made

Se è valorizzata almeno una fra dataRichiestaRisarcimento e dataNotificaCircostanza — anche una sola — il sinistro è trattato come Claims Made.

Blocco danneggiato (DanneggiatoDTO) — obbligatorio tipoDanneggiato:

Campo Descrizione
tipoDanneggiato Enum: CONTRAENTE | ASSICURATO | CONTROPARTE. Se CONTRAENTE, gli altri campi vengono recuperati dalla polizza
nome / cognome Persona fisica
ragioneSociale Persona giuridica
codiceFiscale / partitaIva Se disponibili
contatti telefono, email, pec (tutti facoltativi)
indirizzo via, numeroCivico, comune, provincia, nazione, cap

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
{
  "numeroSinistroEsterno": "EXT-2026-445566",
  "numeroSinistroBroker": "BROKER-CLM-2026-000123",
  "polizza": {
    "numeroPolizza": "OX00001",
    "ramo": "13",
    "codiceGaranzia": "13401",
    "codicePrestazione": "1314",
    "riservaApertura": 2600.0
  },
  "evento": {
    "dataEvento": "2026-05-10",
    "dataDenuncia": "2026-05-11",
    "dataRichiestaRisarcimento": "2026-05-15",
    "descrizione": "Danno a terzi durante lavori di ristrutturazione.",
    "luogoEvento": {
      "indirizzo": "Via Roma 1",
      "comune": "Milano",
      "provincia": "MI",
      "nazione": "IT",
      "cap": "20100"
    }
  },
  "danneggiato": {
    "tipoDanneggiato": "CONTROPARTE",
    "nome": "Mario",
    "cognome": "Rossi",
    "codiceFiscale": "RSSMRA80A01F205X",
    "contatti": { "email": "mario.rossi@example.com" },
    "indirizzo": {
      "via": "Via Roma", "numeroCivico": "10",
      "comune": "Roma", "provincia": "RM",
      "nazione": "IT", "cap": "00100"
    }
  },
  "comunicazioni": {
    "emailConferma": ["sinistri@partner.it", "ufficio.claims@broker.it"]
  }
}

Risposta 201 (ClaimPartnerResponseDTO)

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "5beb0117-26d5-4b6e-8b4b-43fba478cbfe",
  "entityId": "4e837ac2-ee7f-45f8-adfc-b368e4b3e8e2",
  "riservaApplicata": {
    "importo": 2599.99,
    "fonte": "PARACADUTE"
  }
}

Rispetto alle altre operazioni di scrittura, la ricevuta è arricchita dal blocco riservaApplicata, che dichiara l'importo di riserva effettivamente applicato in EUR e la sua fonte: INPUT (fornita dal chiamante), PRODOTTO, LOB o PARACADUTE (default tabellato).

Il 201 non significa \"sinistro aperto\"

Significa "richiesta presa in carico". L'esito si legge su GET /partnerIntegration/claim/status?requestId=.

Codici di esito

HTTP Significato dichiarato dal contratto
201 Sinistro creato correttamente. La risposta contiene l'identificativo asincrono per tracciare l'elaborazione e la riserva di apertura applicata
400 Richiesta non leggibile o non coerente: errore di parsing JSON o dati non validi (es. formato data o enum non valido, riservaApertura <= 0, idPolizzaEsterna non coerente)
422 Errore di validazione del payload: blocchi obbligatori mancanti o combinazioni di campi non coerenti. I dettagli sono nel campo message
404 Risorsa non trovata: polizza, titolo o garanzia non individuata in base ai riferimenti forniti
409 Conflitto: esiste già un sinistro coerente con i riferimenti esterni indicati (duplicato)
500 Errore interno inatteso del servizio

6.2 GET /partnerIntegration/claim/status — Esito dell'operazione asincrona

A cosa serve. Restituisce lo stato di elaborazione di un'operazione asincrona a partire dal requestId con cui è stata inviata. È il meccanismo con cui il partner legge l'esito: non esiste notifica push.

Endpoint

  • Metodo: GET
  • URL: /partnerIntegration/claim/status
  • Query param obbligatorio: requestId (UUID)
  • Header obbligatori: Authorization: Bearer <ACCESS_TOKEN_JWT>

Esempio di richiesta

GET /api/v1/integration/partnerIntegration/claim/status?requestId=3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>

Risposta 200 (ClaimStatusDTO)

{
  "status": "SUCCESS",
  "code": null,
  "description": "Sinistro aperto",
  "sinistroId": "4e837ac2-ee7f-45f8-adfc-b368e4b3e8e2"
}

Il campo sinistroId è valorizzato solo a esito SUCCESS. A esito FAILED la causa è in code e description.

Codici di esito

HTTP Significato dichiarato dal contratto
200 Esito recuperato correttamente
500 Errore interno inatteso del servizio o del core sinistri

Non desumibile dal contratto

Lo schema ClaimStatusDTO dichiara i quattro campi come stringhe senza enumerazione: i valori SUCCESS, FAILED e PENDING provengono dalla descrizione dell'operazione, non da un enum formale. Il contratto non dichiara l'elenco dei valori possibili di code, e non dichiara alcuna risposta 404: un requestId sconosciuto restituisce PENDING, non un errore.

6.3 GET /partnerIntegration/claim/financials — Dati economici del sinistro

Operazione non ancora utilizzabile dal partner

Questa operazione richiede il numero sinistro REVO, che al momento le API di integrazione non restituiscono (né la ricevuta di apertura né /claim/status) e che non può essere sostituito dal numeroSinistroEsterno. Sarà resa utilizzabile in un rilascio successivo, con aggiornamento di questa guida. Nel frattempo non va integrata. Per tutte le altre operazioni il sinistro si indica con numeroSinistroEsterno.

A cosa serve. Restituisce quanto REVO ha liquidato sul sinistro (pagamenti indennizzo e spese) e la riserva ancora residua, con la valuta di riferimento. Gli importi sono quelli calcolati dal core sinistri: nessuna rielaborazione lato integrazione.

Endpoint

  • Metodo: GET
  • URL: /partnerIntegration/claim/financials
  • Query param obbligatorio: sinistroId — numero sinistro REVO (es. ELB.26.9097.0/PPE). Accettato anche nella forma con il suffisso del liquidatore. L'identificativo interno UUID restituito da /claim/status e il numeroSinistroEsterno inviato in apertura vengono rifiutati con 422 (Formato sinistroId non valido). Nessuna risposta delle API partner restituisce il numero sinistro REVO (la ricevuta e /claim/status espongono solo l'UUID interno): va acquisito fuori dalle API e concordato con REVO

Esempio di richiesta

GET /api/v1/integration/partnerIntegration/claim/financials?sinistroId=ELB.25.001234.0 HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>

Risposta 200 (SinistroFinancialsDTO)

{
  "numeroSinistro": "ELB.25.001234.0",
  "valuta": "EUR",
  "totalePagamenti": {
    "indennizzo": 12500.0,
    "spese": 350.0,
    "totale": 12850.0,
    "valuta": "EUR"
  },
  "riservaResidua": {
    "indennizzo": 7500.0,
    "spese": 150.0,
    "totale": 7650.0,
    "valuta": "EUR"
  }
}

null non è zero

Il contratto dichiara esplicitamente che un totale valorizzato a null significa "non disponibile", non "zero". Il partner non deve trattare i due casi allo stesso modo.

Codici di esito

HTTP Significato dichiarato dal contratto
200 Dati economici recuperati correttamente
404 Sinistro non trovato a partire dal numero indicato
500 Errore interno inatteso del servizio o del core sinistri

6.4 PUT /partnerIntegration/claim/reserves — Aggiornamento delle riserve

A cosa serve. Aggiorna le riserve di una o più garanzie già aperte sul sinistro. Sinistro, danneggiato e garanzia si indicano con riferimenti di business: nessun identificativo tecnico in ingresso.

Endpoint

  • Metodo: PUT
  • URL: /partnerIntegration/claim/reserves
  • Header obbligatori: Authorization, requestId: <UUID>
  • Body: PartnerReserveRequestDTO (application/json)

Richiesta

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro (esattamente uno dei tre riferimenti — si veda 3.2)
aggiornamenti Sì Aggiornamenti da applicare, almeno uno
aggiornamenti[].danneggiato No Danneggiato su cui insiste la garanzia. Facoltativo se il sinistro ha un solo danneggiato
aggiornamenti[].garanzia Sì Garanzia aperta da aggiornare, per codici di prodotto (coppia codiceGaranzia + codicePrestazione)
aggiornamenti[].importoRiserva Sì Nuovo importo della riserva, maggiore di zero

Gli attributi tecnici della garanzia (productCoverCode, chiaveRischio, keyCondizione) non sono input: li risolve il back-end sulla garanzia già aperta.

Esempio di richiesta

PUT /api/v1/integration/partnerIntegration/claim/reserves HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
{
  "sinistro": { "numeroSinistro": "ELB.26.1234567.0" },
  "aggiornamenti": [
    {
      "danneggiato": {
        "tipoDanneggiato": "CONTROPARTE",
        "codiceFiscale": "RSSMRA80A01F205X"
      },
      "garanzia": {
        "codiceGaranzia": "00001",
        "codicePrestazione": "1699"
      },
      "importoRiserva": 12500.0
    }
  ]
}

Risposta 201 (PartnerOperationResponseDTO)

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "2e3bd39a-c521-4f5b-936b-863ad36f39f7",
  "entityId": "65dbc2bb-01c9-4816-bb97-70e58d02fcd7"
}

Codici di esito

HTTP Significato dichiarato dal contratto
201 Richiesta presa in carico
400 Richiesta non interpretabile in fase di risoluzione
422 Violazione del contratto: riferimento al sinistro assente o multiplo, importo non positivo, codiceGaranzia indicato con il punto invece della coppia
404 Sinistro, danneggiato o garanzia inesistenti
409 Riferimento ambiguo: più candidati, elencati nel messaggio
500 Il core non ha confermato la presa in carico: l'aggiornamento NON è stato accettato e non esiste un requestId da interrogare. La richiesta va ripetuta

Garanzia non risolta sui sinistri A001

Sull'ambiente di test l'aggiornamento riserve su un sinistro A001 risponde 404 (Garanzia non trovata per campi specificati) con codiceGaranzia 16032 e codicePrestazione 1699, con il solo codice e con il numero sinistro esterno. La stessa garanzia viene invece risolta dal pagamento. L'operazione verrà corretta in un rilascio successivo.

6.5 PUT /partnerIntegration/claim/injured-party — Upsert danneggiato

L'esito di questa operazione NON è interrogabile su /claim/status

La risposta è 201 con un requestId, ma quel requestId resta PENDING per sempre: non diventerà mai SUCCESS né FAILED. L'operazione è comunque asincrona — la scrittura del danneggiato la esegue un worker dopo la risposta — quindi il 201 non è una conferma che il danneggiato sia stato scritto. L'esito si verifica rileggendo il sinistro e controllando la presenza del danneggiato con la chiave naturale usata nella richiesta. Si veda 4.1.

A cosa serve. Inserisce o aggiorna il danneggiato sul sinistro. La scelta fra inserimento e aggiornamento si basa sulla chiave naturale (tipo danneggiato + codice fiscale o partita IVA), non su un id tecnico.

Endpoint

  • Metodo: PUT
  • URL: /partnerIntegration/claim/injured-party
  • Header obbligatori: Authorization, requestId: <UUID>
  • Body: PartnerInjuredPartyRequestDTO (application/json)

Richiesta

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro (esattamente uno dei tre riferimenti)
danneggiato Sì Danneggiato da inserire o aggiornare (DanneggiatoDTOCreate)
danneggiato.tipoDanneggiato — Enum: CONTRAENTE | ASSICURATO | CONTROPARTE
danneggiato.descrizioneBene — Descrizione del bene
danneggiato.valutaDanneggiato — Valuta del danneggiato
danneggiato.soggetto — Anagrafica: tipoSoggetto, nome, cognome, denominazione, telefono, indirizzo, email, codiceFiscale, partitaIva, pec, iban, sesso, nazione, provincia, comune, cap, via, nCivico

Non desumibile dal contratto

Lo schema DanneggiatoDTOCreate e il suo blocco SoggettoDTOCreate non dichiarano alcun campo obbligatorio né alcuna descrizione per i singoli campi; il campo tipoSoggetto è dichiarato come stringa libera, senza enumerazione. Quali combinazioni di anagrafica siano sufficienti per l'upsert non è desumibile dal contratto e va concordato con REVO.

Esempio di richiesta

PUT /api/v1/integration/partnerIntegration/claim/injured-party HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
{
  "sinistro": { "numeroSinistroEsterno": "EXT-2026-445566" },
  "danneggiato": {
    "tipoDanneggiato": "CONTROPARTE",
    "soggetto": {
      "tipoSoggetto": "PERSONA_GIURIDICA",
      "denominazione": "Beta S.p.A.",
      "partitaIva": "12345678901",
      "email": "amministrazione@beta.example.it",
      "pec": "beta@pec.example.it",
      "nazione": "IT", "provincia": "MI", "comune": "Milano",
      "cap": "20100", "via": "Via Roma", "nCivico": "1"
    }
  }
}

Risposta 201 (PartnerOperationResponseDTO). Ricevuta di presa in carico; entityId è l'identificativo del danneggiato inserito o aggiornato. Il requestId restituito non è utilizzabile su /claim/status (si veda il riquadro a inizio paragrafo).

Codici di esito

HTTP Significato dichiarato dal contratto
201 Danneggiato inserito o aggiornato
400 Bad Request
404 Sinistro non trovato
409 Chiave del danneggiato non discriminante
500 Il core non ha confermato la presa in carico

Non desumibile dal contratto

Il contratto non dichiara una risposta 422 per questa operazione, a differenza di riserve, riapertura, email e documenti, e formula 400 senza descrizione.

6.6 POST /partnerIntegration/claim/reopen — Riapertura di un sinistro chiuso

A cosa serve. Riapre un sinistro chiuso su uno o più danneggiati e sulle rispettive garanzie, costituendo per ciascuna la riserva indicata. Il danneggiato si indica per chiave naturale se è già sul sinistro, con la sua anagrafica completa se è nuovo. La garanzia può non essere mai stata aperta sul sinistro: viene cercata sul riepilogo garanzie della polizza.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim/reopen
  • Header obbligatori: Authorization, requestId: <UUID>
  • Body: PartnerReopenRequestDTO (application/json)

Richiesta

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro da riaprire
danneggiati Sì Danneggiati coinvolti nella riapertura, almeno uno
danneggiati[].danneggiato No Riferimento a un danneggiato già presente sul sinistro (chiave naturale)
danneggiati[].anagrafica No Anagrafica completa, da valorizzare solo se il danneggiato non è ancora sul sinistro
danneggiati[].garanzie Sì Garanzie da riaprire, almeno una
…garanzie[].garanzia Sì Garanzia, indicata dal SOLO codiceGaranzia (forma di polizza, senza punto)
…garanzie[].importoRiserva Sì Riserva da costituire alla riapertura

Su questa operazione la garanzia si indica diversamente

codicePrestazione e chiaveGaranzia NON sono ammessi e producono 400. Il contratto ne dichiara la ragione: la risoluzione della riapertura non discrimina su quei campi, e accettarli senza usarli farebbe credere di aver disambiguato.

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/reopen HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
{
  "sinistro": { "numeroSinistro": "ELB.26.1234567.0" },
  "danneggiati": [
    {
      "danneggiato": {
        "tipoDanneggiato": "CONTROPARTE",
        "codiceFiscale": "RSSMRA80A01F205X"
      },
      "garanzie": [
        { "garanzia": { "codiceGaranzia": "00001" },
          "importoRiserva": 3000.0 }
      ]
    }
  ]
}

Risposta 201 (PartnerOperationResponseDTO). Ricevuta di presa in carico. L'esito si legge su /claim/status per requestId.

Codici di esito

HTTP Significato dichiarato dal contratto
201 Richiesta presa in carico
400 Richiesta non interpretabile in fase di risoluzione, o garanzia indicata con codicePrestazione/chiaveGaranzia, che questa operazione non sa usare
422 Violazione del contratto: riferimento al sinistro assente o multiplo, danneggiato né riferito né descritto, importo non positivo, codiceGaranzia con il punto
404 Sinistro inesistente; danneggiato inesistente e senza anagrafica; garanzia assente dal riepilogo di polizza
409 Riferimento ambiguo
500 Il core non ha confermato la presa in carico: la riapertura NON è stata accettata e non esiste un requestId da interrogare. La richiesta va ripetuta

Esito della riapertura

Verificato sull'ambiente di test: l'esito risolve su /claim/status (non resta PENDING). Un rifiuto è restituito come FAILED con code 7500 e il motivo in description (es. Nessun Esito trovato per Sinistro riaperto): in tal caso il sinistro resta nello stato precedente. Va quindi gestito sia SUCCESS sia FAILED.

6.7 POST /partnerIntegration/claim/payment — Registrazione di un pagamento

A cosa serve. Registra un pagamento sul sinistro indicando sinistro, danneggiato e garanzie con i riferimenti di business, e chi esegue materialmente il pagamento.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim/payment
  • Header obbligatori: Authorization, requestId: <UUID>
  • Body: PartnerPaymentRequestDTO (application/json)

Richiesta. Campi obbligatori dichiarati: sinistro, beneficiario, dataPagamento, garanzie.

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro
garanzie Sì Importi per garanzia: garanzia (obbl.), importo (obbl.), riservaResidua, calcoloResiduo (se il residuo va ricalcolato dal back-end, default true)
dataPagamento Sì Data del pagamento (yyyy-MM-dd)
beneficiario Sì Beneficiario del pagamento (obbligatori al suo interno: indirizzo e metodoDiPagamento)
esecutorePagamento No REVO | PARTNER. Chi esegue materialmente il pagamento; assente vale REVO
danneggiato No Riferimento al danneggiato; facoltativo se il sinistro ne ha uno solo
importoTotale No Importo totale del pagamento
valuta No Se valorizzata deve coincidere con quella del sinistro, altrimenti la richiesta è rifiutata. Non propagata al core
mmAaaaEstrattoConto No Mese e anno dell'estratto conto, formato MM-AAAA
causale No Accettata per parità con il v1, NON propagata al core
quietanza No necessaria, tipoQuietanza. Accettata per parità con il v1, NON propagata al core
recuperi No franchigia, rivalsa. Accettati per parità con il v1, NON propagati al core
chiaveRiconciliazioneAssistenza No Accettata per parità con il v1, NON propagata al core

Blocco beneficiario (PartnerBeneficiarioDTO):

Campo Obbl. Valori / descrizione
metodoDiPagamento Sì SEPA | BONIFICO_MANUALE | PAGAMENTO_ANTICIPATO_INTERMED | AD | AZ | BE
indirizzo Sì via, comune, cap, provincia, ncivico e nazione (nazione obbligatoria, ISO a due lettere)
tipoPagamento No PAGAMENTO_INDENNIZZO | PAGAMENTO_SPESA | PAGAMENTO_AS
iban / bic No Coordinate bancarie del beneficiario
nome / cognome No Persona fisica
ragioneSociale No Persona giuridica
codiceFiscale / partitaIva Uno dei due Identificativi fiscali: almeno uno è necessario (altrimenti 422)
email / telefono No Recapiti del beneficiario

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/payment HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 78c54a9d-1174-466c-9f03-8b15e7e19266
Content-Type: application/json
{
  "sinistro": { "numeroSinistro": "ELB.26.1234567.0" },
  "esecutorePagamento": "PARTNER",
  "danneggiato": {
    "tipoDanneggiato": "CONTROPARTE",
    "codiceFiscale": "RSSMRA80A01F205X"
  },
  "garanzie": [
    {
      "garanzia": { "codiceGaranzia": "00001", "codicePrestazione": "1699" },
      "importo": 5000.0,
      "riservaResidua": 2000.0,
      "calcoloResiduo": true
    }
  ],
  "importoTotale": 5000.0,
  "valuta": "EUR",
  "dataPagamento": "2026-09-16",
  "mmAaaaEstrattoConto": "09-2026",
  "beneficiario": {
    "tipoPagamento": "PAGAMENTO_INDENNIZZO",
    "metodoDiPagamento": "SEPA",
    "iban": "IT60X0542811101000000123456",
    "nome": "Mario",
    "cognome": "Rossi",
    "codiceFiscale": "RSSMRA80A01F205X",
    "indirizzo": {
      "via": "Via Roma", "ncivico": "10", "comune": "Roma",
      "cap": "00100", "provincia": "RM", "nazione": "IT"
    },
    "email": "mario.rossi@example.com"
  }
}

Risposta 201 (PartnerOperationResponseDTO). Ricevuta di presa in carico. Il requestId usato qui è la chiave con cui il pagamento potrà essere annullato (si veda 6.8): va persistito lato partner.

Codici di esito

HTTP Significato dichiarato dal contratto
201 Pagamento accettato
400 Bad Request
404 Not Found
409 Riferimento ambiguo
500 Il core non ha confermato la presa in carico

Non desumibile dal contratto

Per questa operazione il contratto non dichiara una risposta 422 e formula 400 e 404 senza descrizione ("Bad Request", "Not Found"). Le condizioni precise che li generano non sono desumibili dal contratto: valgono le regole generali del capitolo 3.5.

Esito del pagamento

Verificato sull'ambiente di test: l'esito risolve in SUCCESS e il pagamento è registrato con stato EMESSO (con esecutorePagamento PARTNER).

Codice fiscale o partita IVA del beneficiario

Il contratto li dichiara facoltativi, ma senza almeno uno dei due la richiesta è rifiutata con 422 (Indicare il codice fiscale oppure la partita IVA del beneficiario).

6.8 POST /partnerIntegration/claim/payment/{requestIdPagamento}/cancel — Annullamento di un pagamento

A cosa serve. Annulla il pagamento creato con il requestId indicato nel path — la stessa chiave con cui il partner lo ha creato, non l'identificativo del task di cContact.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim/payment/{requestIdPagamento}/cancel
  • Path param obbligatorio: requestIdPagamento — il requestId con cui il pagamento da annullare è stato creato (es. 78c54a9d-1174-466c-9f03-8b15e7e19266)
  • Header obbligatori: Authorization, requestId: <UUID> — nuovo, identifica questa richiesta di annullamento
  • Body: PartnerPaymentCancelRequestDTO (application/json)

Due requestId diversi

Il requestId nel path è quello del pagamento da annullare; il requestId nell'header è quello nuovo dell'operazione di annullamento, ed è con quest'ultimo che se ne legge l'esito su /claim/status.

Richiesta

Campo Obbl. Descrizione
motivazione Sì Motivazione dell'annullamento
dataAnnullamento No Data di annullamento (yyyy-MM-dd)
mmAaaaEstrattoConto No Mese e anno dell'estratto conto, formato MM-AAAA
chiaveRiconciliazioneAssistenza No Accettata per parità con il v1, NON propagata al core

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/payment/78c54a9d-1174-466c-9f03-8b15e7e19266/cancel HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: c1a7f2d6-9b34-4a55-8e01-2f6b0d4c7e11
Content-Type: application/json
{
  "motivazione": "Errore di importo sul beneficiario",
  "dataAnnullamento": "2026-09-17",
  "mmAaaaEstrattoConto": "09-2026"
}

Codici di esito

HTTP Significato dichiarato dal contratto
201 Annullamento accettato
400 Bad Request
404 Nessun pagamento creato con quel requestId
409 Il pagamento è già stornato o ha lo storno in corso
500 Il core non ha confermato la presa in carico

Un pagamento già stornato risponde 409, non 200

Il contratto è esplicito: l'annullamento non è idempotente. Ripetere l'annullamento di un pagamento già stornato, o il cui storno è in corso, restituisce 409 e non un esito positivo.

Esito dell'annullamento

Verificato sull'ambiente di test: la richiesta risponde 201 e /claim/status risolve in FAILED con code 7500 (Nessun Esito trovato per Pagamento Istantaneo), mentre sul pagamento risultano registrate data e motivazione di storno. Una seconda richiesta di annullamento sullo stesso pagamento ha risposto di nuovo 201 (non 409 come dichiarato dal contratto). Non basare la riconciliazione sul solo esito FAILED: concordare con REVO lo stato finale del pagamento.

6.9 POST /partnerIntegration/claim/closure — Chiusura senza seguito

A cosa serve. Chiude senza seguito il sinistro indicato, con un codice di motivo scelto fra quelli ammessi.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim/closure
  • Header obbligatori: Authorization, requestId: <UUID>
  • Body: PartnerClosureRequestDTO (application/json)

Richiesta

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro
codiceMotivoSenzaSeguito Sì Codice del motivo di chiusura senza seguito, fra quelli restituiti da GET /partnerIntegration/claim/closure/reasons
note No Note libere; se assenti vale la descrizione del motivo

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/closure HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
{
  "sinistro": { "numeroSinistro": "ELB.26.1234567.0" },
  "codiceMotivoSenzaSeguito": "<codice da /claim/closure/reasons>",
  "note": "Chiusura richiesta dal partner"
}

Codici di esito

HTTP Significato dichiarato dal contratto
201 Chiusura accettata
400 Bad Request
404 Not Found
409 Il sinistro ha pagamenti in corso
500 Il core non ha confermato la presa in carico

Esito della chiusura

Verificato sull'ambiente di test: la chiusura risolve in SUCCESS su /claim/status pochi secondi dopo il 201 e il sinistro passa allo stato SENZA SEGUITO, con codiceMotivoSenzaSeguito e note registrati.

6.10 GET /partnerIntegration/claim/closure/reasons — Motivi di chiusura senza seguito

A cosa serve. Restituisce i motivi di chiusura senza seguito attivi, serviti dal core. È la sorgente dei valori ammessi per il campo codiceMotivoSenzaSeguito della chiusura.

Endpoint

  • Metodo: GET
  • URL: /partnerIntegration/claim/closure/reasons
  • Parametri: nessuno

Esempio di richiesta

GET /api/v1/integration/partnerIntegration/claim/closure/reasons HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>

Risposta 200 (array di MotivoSenzaSeguitoDTO)

[
  {
    "codice": "<codice del motivo>",
    "descrizioneIt": "<descrizione in italiano>",
    "descrizioneEs": "<descrizione in spagnolo>"
  }
]

Elenco dinamico

Il contratto lo descrive come i motivi attivi serviti dal core, e non ne dichiara i valori. Va letto a runtime, non cablato lato partner.

Codici di esito

HTTP Significato dichiarato dal contratto
200 Elenco dei motivi
500 Errore interno del server

6.11 POST /partnerIntegration/claim/email — Invio email per conto del sinistro

L'esito arriva nella risposta HTTP

Il core non espone un endpoint di invio email: l'invio non attraversa il listener del core, va direttamente a cContact e risponde 200 con l'esito. Di conseguenza questa operazione non richiede l'header requestId e non produce nulla da interrogare su /claim/status. È l'unica operazione di scrittura il cui esito è già nella risposta HTTP — il che non significa che tutte le altre siano interrogabili: due non lo sono (si veda 4.1).

A cosa serve. Invia un'email per conto del sinistro. Il mittente e il ticket cContact li risolve il back-end a partire dal sinistro: identificativo del task e mittente non sono input.

Endpoint

  • Metodo: POST
  • URL: /partnerIntegration/claim/email
  • Header obbligatori: Authorization: Bearer <ACCESS_TOKEN_JWT> — nessun header requestId
  • Body: PartnerEmailRequestDTO (application/json)

Richiesta

Campo Obbl. Descrizione
sinistro Sì Riferimento al sinistro
to Sì Destinatari (array di indirizzi email)
oggetto Sì Oggetto. Viene troncato al limite accettato da cContact
corpo Sì Corpo del messaggio. Viene troncato al limite accettato da cContact
cc No Destinatari in copia
ccn No Destinatari in copia nascosta
allegati No Array di allegatoId restituiti da GET /partnerIntegration/claim/documents

Oggetto e corpo vengono troncati

Il contratto dichiara che oggetto e corpo vengono troncati al limite che cContact accetta — non che vengano rifiutati se troppo lunghi. Il valore di quel limite non è dichiarato dal contratto: un testo lungo può quindi arrivare tagliato senza che la risposta lo segnali.

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/email HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
Content-Type: application/json
{
  "sinistro": { "numeroSinistro": "ELB.26.1234567.0" },
  "to": ["liquidatore@example.it"],
  "cc": ["ufficio.claims@broker.it"],
  "oggetto": "Documentazione integrativa sinistro ELB.26.1234567.0",
  "corpo": "In allegato la perizia richiesta.",
  "allegati": ["4a303e37-9ed4-41ae-bbfc-0a518556e3c7"]
}

Risposta 200 (PartnerEmailResponseDTO)

{
  "esito": true,
  "descrizione": "<descrizione dell'esito>"
}

esito vale true quando cContact ha accettato l'invio. Non è richiesto alcun polling successivo: la risposta HTTP porta già l'esito.

Codici di esito

HTTP Significato dichiarato dal contratto
200 Esito dell'invio (il campo esito dice se cContact ha accettato)
422 Violazione del contratto: riferimento al sinistro assente o multiplo, destinatari assenti o non validi, oggetto o corpo mancanti
404 Sinistro inesistente, o nessun mittente configurato sulla coda cContact
409 Riferimento ambiguo

Non desumibile dal contratto

Per questa operazione il contratto non dichiara risposte 400 né 500. Il partner deve comunque gestire difensivamente un 5xx di trasporto.

6.12 GET /partnerIntegration/claim/documents — Elenco degli allegati

Lo swagger non descrive la forma reale della richiesta

Il file OpenAPI dichiara un unico query param sinistro di tipo oggetto (ClaimReferenceDTO). La forma reale, verificata sul codice, sono tre query param piatti: numeroSinistro, numeroSinistroEsterno, numeroSinistroBroker — con esattamente uno valorizzato. Vale la forma reale documentata qui, non quella generata.

A cosa serve. Restituisce i metadati degli allegati del sinistro. L'allegatoId restituito qui è il riferimento da usare per il download (6.14) e per gli allegati delle email (6.11).

Endpoint — forma reale

  • Metodo: GET
  • URL: /partnerIntegration/claim/documents
  • Header obbligatori: Authorization: Bearer <ACCESS_TOKEN_JWT>
  • Query param — esattamente uno fra: numeroSinistro, numeroSinistroEsterno, numeroSinistroBroker

Esempio di richiesta

GET /api/v1/integration/partnerIntegration/claim/documents?numeroSinistro=ELB.26.1234567.0 HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>

Varianti con gli altri due riferimenti (sempre uno solo per chiamata):

GET /api/v1/integration/partnerIntegration/claim/documents?numeroSinistroEsterno=EXT-2026-445566
GET /api/v1/integration/partnerIntegration/claim/documents?numeroSinistroBroker=BROKER-CLM-2026-000123

Risposta 200 (array di PartnerAllegatoDTO)

[
  {
    "allegatoId": "4a303e37-9ed4-41ae-bbfc-0a518556e3c7",
    "nome": "perizia.pdf",
    "tipo": "<tipo di allegato>",
    "dimensione": 1270645,
    "data": "2026-09-20T14:56:28.657Z"
  }
]

Codici di esito

HTTP Significato dichiarato dal contratto
200 Elenco degli allegati
422 Riferimento al sinistro assente o multiplo
404 Sinistro inesistente
409 Riferimento ambiguo

6.13 POST /partnerIntegration/claim/documents — Caricamento di un allegato

Lo swagger non dichiara la parte file

Il file OpenAPI dichiara il corpo multipart/form-data con il solo schema ClaimReferenceDTO e non dichiara la parte file. La forma reale, verificata sul codice, è: header requestId + il riferimento al sinistro come query param (uno solo fra i tre) + una parte multipart di nome file. Vale la forma reale documentata qui, non quella generata.

A cosa serve. Carica un allegato sul sinistro. L'identificativo del task e l'entityId usati dalla superficie precedente non sono input.

Endpoint — forma reale

  • Metodo: POST
  • URL: /partnerIntegration/claim/documents
  • Header obbligatori: Authorization: Bearer <ACCESS_TOKEN_JWT>, requestId: <UUID>
  • Query param — esattamente uno fra: numeroSinistro, numeroSinistroEsterno, numeroSinistroBroker
  • Body: multipart/form-data con una parte di nome file contenente il documento

Esempio di richiesta

POST /api/v1/integration/partnerIntegration/claim/documents?numeroSinistro=ELB.26.1234567.0 HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>
requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: multipart/form-data; boundary=----BOUNDARY

------BOUNDARY
Content-Disposition: form-data; name="file"; filename="perizia.pdf"
Content-Type: application/pdf

<contenuto binario del file>
------BOUNDARY--

Lo stesso con curl:

curl -X POST \
  "https://testoverx-sinistri-api.elbassicurazioni.it/api/v1/integration/partnerIntegration/claim/documents?numeroSinistroEsterno=EXT-2026-445566" \
  -H "Authorization: Bearer <ACCESS_TOKEN_JWT>" \
  -H "requestId: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -F "file=@perizia.pdf;type=application/pdf"

Risposta 201 (PartnerOperationResponseDTO). Ricevuta di presa in carico dell'allegato. Il requestId restituito non è utilizzabile su /claim/status (si veda il riquadro seguente).

Codici di esito

HTTP Significato dichiarato dal contratto
201 Allegato preso in carico
400 Richiesta non interpretabile in fase di risoluzione
422 Violazione del contratto: riferimento al sinistro assente o multiplo, file mancante
404 Sinistro inesistente
409 Riferimento ambiguo
500 Il core non ha confermato l'acquisizione: l'allegato NON è stato acquisito e non esiste un requestId da interrogare. La richiesta va ripetuta

L'esito di questa operazione NON è interrogabile su /claim/status

La risposta è 201 con un requestId, ma quel requestId resta PENDING per sempre. L'operazione è asincrona — lo spostamento dell'allegato nella cartella definitiva lo esegue un worker dopo la risposta — quindi il 201 non conferma che l'allegato sia stato acquisito. La verifica si fa con GET /partnerIntegration/claim/documents: l'allegato è acquisito quando compare nell'elenco con il proprio allegatoId. La descrizione dell'operazione nel file OpenAPI afferma il contrario ("l'esito si legge su GET /partnerIntegration/claim/status?requestId="): quell'affermazione è errata e non va seguita. Si veda 4.1.

6.14 GET /partnerIntegration/claim/documents/{allegatoId} — Download di un allegato

A cosa serve. Scarica il contenuto di un allegato. L'allegatoId è quello restituito da GET /partnerIntegration/claim/documents.

Endpoint

  • Metodo: GET
  • URL: /partnerIntegration/claim/documents/{allegatoId}
  • Path param obbligatorio: allegatoId (UUID)
  • Risposta: application/octet-stream

Esempio di richiesta

GET /api/v1/integration/partnerIntegration/claim/documents/4a303e37-9ed4-41ae-bbfc-0a518556e3c7 HTTP/1.1
Host: testoverx-sinistri-api.elbassicurazioni.it
Authorization: Bearer <ACCESS_TOKEN_JWT>

Codici di esito

HTTP Significato dichiarato dal contratto
200 Contenuto del file
404 Allegato inesistente
413 Allegato troppo grande

Non desumibile dal contratto

Il contratto dichiara un 413 ("allegato troppo grande") ma non dichiara la soglia di dimensione oltre la quale scatta, né una via alternativa per recuperare un allegato che la superi. Anche il Content-Type effettivo del file scaricato non è dichiarato: la risposta è descritta genericamente come application/octet-stream.

7. Linee guida operative

7.1 Header

Ogni richiesta deve includere:

Authorization: Bearer <ACCESS_TOKEN_JWT>   <- sempre
Content-Type: application/json            <- operazioni con body JSON
Content-Type: multipart/form-data         <- caricamento allegato
requestId: <UUID>                         <- operazioni di scrittura,
                                             tranne POST /claim/email

7.2 Sequenza tipica di integrazione

Passo Operazione Esito atteso
1 Login su ext-sicurezza/login access_token valido 1800 secondi
2 POST /partnerIntegration/claim con un requestId nuovo 201 + ricevuta + riservaApplicata
3 GET /partnerIntegration/claim/status?requestId=… in polling SUCCESS con sinistroId, oppure FAILED con code e description
4 Operazioni successive (riserve, pagamenti, riapertura) usando il riferimento di business del sinistro ciascuna con il proprio requestId e il proprio polling
5 Upsert danneggiato e caricamento allegato 201, ma NIENTE polling: si verificano rileggendo il sinistro e l'elenco allegati (4.1)
6 POST /partnerIntegration/claim/email 200 con l'esito nella risposta: nessun polling
7 GET /partnerIntegration/claim/financials non ancora utilizzabile (si veda 6.3)
8 Chiusura: GET /claim/closure/reasons, poi POST /claim/closure 201 + polling dell'esito

7.3 Regole da rispettare per non perdere tempo

  • Un requestId nuovo per ogni chiamata di scrittura, persistito lato partner: è l'unica chiave per leggere l'esito, e per i pagamenti è anche la chiave di annullamento.
  • Il codice di garanzia si manda in due campi, mai puntato: "codiceGaranzia": "00001" + "codicePrestazione": "1699", non "00001.1699". Sulla riapertura, solo codiceGaranzia.
  • Esattamente un riferimento al sinistro per chiamata: zero o due riferimenti valorizzati producono 422.
  • Il 201 non è un successo funzionale: senza polling su /claim/status non si sa se l'operazione è andata a buon fine.
  • Upsert danneggiato e caricamento allegato non si verificano con il polling: il loro requestId resta PENDING per sempre. Si verificano rileggendo il sinistro e, per l'allegato, con GET /partnerIntegration/claim/documents (si veda 4.1).
  • Il 500 sulle scritture si ripete, non si interroga: non esiste un requestId da leggere.
  • Nessun endpoint di callback da implementare: il modello è esclusivamente in pull.
  • Sui documenti si segue la forma reale documentata in 6.12 e 6.13, non quella generata dallo swagger.
  • Le enumerazioni si rispettano alla lettera: CONTRAENTE | ASSICURATO | CONTROPARTE; REVO | PARTNER; PAGAMENTO_INDENNIZZO | PAGAMENTO_SPESA | PAGAMENTO_AS; SEPA | BONIFICO_MANUALE | PAGAMENTO_ANTICIPATO_INTERMED | AD | AZ | BE.

7.4 Sicurezza

  • Usare sempre HTTPS.
  • Rinnovare il token prima della scadenza (expires_in: 1800 secondi) per evitare interruzioni di flusso.
  • Non registrare in chiaro token, credenziali o coordinate bancarie dei beneficiari nei log applicativi.

7.5 Difetti noti e punti aperti

I punti seguenti sono noti o non desumibili dal contratto, e vanno tenuti presenti in fase di integrazione:

Punto Stato
Il requestId di PUT /claim/injured-party e POST /claim/documents resta PENDING per sempre su /claim/status Comportamento verificato sull'ambiente di test. Aggiramento in 4.1
La descrizione OpenAPI di POST /claim/documents afferma che l'esito si legge su /claim/status Affermazione errata: non va seguita
Intervallo di polling raccomandato e tempo massimo di elaborazione di un'operazione asincrona Non dichiarato dal contratto. In test apertura e chiusura risolvono entro pochi secondi
Codifica del campo status interno di ExceptionObject e catalogo dei valori di code su esito FAILED Non dichiarato dal contratto
Limite di lunghezza di oggetto e corpo dell'email (oltre il quale si tronca in silenzio) Non dichiarato dal contratto
GET /claim/financials Non ancora utilizzabile: richiede il numero sinistro REVO, non restituito dalle API. Sarà integrata in un rilascio successivo
Soglia di dimensione che produce il 413 in download allegato Non dichiarato dal contratto
Campi minimi dell'anagrafica danneggiato per un upsert valido Non dichiarato dal contratto
Risposte 401 e 403 sulle singole operazioni Non dichiarate dal contratto (comportamento ripreso dalla v3.3)
Elenco dei motivi di chiusura senza seguito Dinamico: da leggere a runtime da /claim/closure/reasons