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
requestIde rispondono201con una ricevuta di presa in carico. Per sei di esse l'esito effettivo si legge in pull suGET /partnerIntegration/claim/status?requestId=. - Una sola operazione restituisce l'esito nella risposta HTTP:
POST /partnerIntegration/claim/email, che risponde200con 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 unrequestIdinterrogabile. - Due operazioni sono asincrone ma cieche:
PUT /partnerIntegration/claim/injured-partyePOST /partnerIntegration/claim/documentsrispondono201con unrequestIdche non è interrogabile su/claim/status. Non sono sincrone — il lavoro lo fa un worker dopo la risposta — ma il loro esito non è leggibile perrequestId. 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/statusalla 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
correlationIdrestituito dal back-end. - Chiave di annullamento: per i pagamenti è il
requestIdusato 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-ddper 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) permmAaaaEstrattoConto. - UUID: per
requestId,correlationId,entityIdeallegatoId. - 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/statuse ilnumeroSinistroEsternoinviato in apertura vengono rifiutati con 422 (Formato sinistroId non valido). Nessuna risposta delle API partner restituisce il numero sinistro REVO (la ricevuta e/claim/statusespongono 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— ilrequestIdcon 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 headerrequestId - 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-datacon una parte di nomefilecontenente 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
requestIdnuovo 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, solocodiceGaranzia. - Esattamente un riferimento al sinistro per chiamata: zero o due riferimenti valorizzati producono 422.
- Il 201 non è un successo funzionale: senza polling su
/claim/statusnon si sa se l'operazione è andata a buon fine. - Upsert danneggiato e caricamento allegato non si verificano con il polling: il loro
requestIdresta PENDING per sempre. Si verificano rileggendo il sinistro e, per l'allegato, conGET /partnerIntegration/claim/documents(si veda 4.1). - Il 500 sulle scritture si ripete, non si interroga: non esiste un
requestIdda 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 |