Cooabit Service Level Agreements¶
Il documento descrive i livelli di servizio che Cooabit garantisce sull'API documentale: disponibilità, tempi di risposta ed elaborazione, gestione degli incidenti.
Versione 1.0
Definizioni¶
- Pratica: il contenitore dei documenti di un richiedente, creato con
POST /applications/. - File: ciò che il cliente carica tramite
external_url. - Documento: ogni singolo documento contenuto in un file. Un PDF con una busta paga e un documento d'identità sono due documenti, ciascuno con il proprio esito.
- Esito: lo stato finale del documento (
DONE,REJECTEDoERROR), comunicato via webhook. - 95% dei documenti: su 100 documenti, almeno 95 rispettano il tempo indicato; al massimo 5 possono superarlo.
- Mese: il mese solare, su cui si calcolano tutti gli impegni.
Ambito¶
Lo SLA copre l'API su https://dashboard.cooabit.com, autenticata con header Api-Key:
POST /api/prod/v1/applications/– creazione della praticaPOST /api/prod/v1/applications/{application_id}/documents/– caricamento del documento tramiteexternal_urlGET /api/prod/v1/applications/{application_id}/– stato e dettagli della pratica- l'elaborazione asincrona del documento e l'invio dell'esito al webhook configurato
Sono esclusi i documenti scartati per i criteri indicati sotto, gli endpoint webhook del cliente che non rispondono con HTTP 200 e la correttezza dei singoli campi estratti.
Documenti accettati¶
Tipi di documento estratti, come compaiono nel campo document_type del webhook: busta_paga, busta_paga_statale, certificato_di_stipendio, certificazione_unica, documento_identita, estratto_conto, estratto_conto_contributivo_inps, quota_cedibile, stato_di_famiglia e, per le pensioni, cedolino_inps, cedolino_inpdap, cedolino_enasarco, obis_m_inps.
File PDF, JPG o PNG fino a 50 MB, scaricabili dall'external_url entro 10 secondi. Un PDF che contiene più documenti viene diviso e ogni documento ha il proprio esito.
Un documento viene scartato con esito REJECTED, che non conta come errore del servizio, quando:
- il formato non è PDF, JPG o PNG (
unsupported_format) - il PDF è protetto da password di apertura (
password_protected) - il tipo non è tra quelli elencati o la classificazione non è affidabile (
classificazione_non_affidabile) - l'immagine è troppo sfocata (
too_blurry); il controllo non si applica ai PDF digitali né ai documenti di identità
Stati ed eventi¶
| Evento webhook | status |
Quando |
|---|---|---|
document.processed |
DONE |
estrazione riuscita |
document.processed |
ERROR |
estrazione non riuscita |
document.rejected |
REJECTED |
documento scartato, con il motivo in stage |
document.error |
error |
errore prima dell'estrazione (download, conversione, classificazione) |
La pratica passa da OPEN a PROCESSING e si chiude in COMPLETED (almeno un documento estratto), REJECTED (tutti scartati) o ERROR.
Livelli di servizio¶
| Indicatore | Impegno mensile |
|---|---|
| Disponibilità dell'API | 99,5% (massimo circa 3 h 36 min di fermo) |
| Documenti elaborati fino a un esito | almeno il 97% dei documenti accettati |
| Risposta di creazione e stato della pratica | entro 2 s nel 95% delle chiamate |
| Risposta al caricamento del documento | entro 5 s nel 95% delle chiamate, escluso il tempo di risposta dell'external_url |
| Esito del documento via webhook | entro 3 minuti per il 95% dei documenti |
Tempo dal caricamento all'esito, per tipo di documento:
| Documento | Tempo tipico (mediana) | Tempo massimo |
|---|---|---|
busta_paga |
45 s | 3 min |
busta_paga_statale |
1 min | 4 min |
certificato_di_stipendio |
1 min | 4 min |
certificazione_unica |
15 s | 3 min |
documento_identita |
25 s | 4 min |
estratto_conto |
15 s | 4 min |
estratto_conto_contributivo_inps |
1 min 30 s | 6 min |
quota_cedibile |
10 s | 2 min |
stato_di_famiglia |
20 s | 3 min |
cedolino_inps, cedolino_inpdap, cedolino_enasarco, obis_m_inps |
15-20 s | 3 min |
documento scartato (REJECTED) |
1 s | 1 min |
Un minuto conta come indisponibile quando un controllo esterno riceve un errore 5xx o nessuna risposta entro 10 secondi. Non contano la manutenzione programmata annunciata, i guasti dei fornitori cloud su tutte le regioni di ripiego e il traffico oltre i limiti d'uso.
Limiti d'uso e consegna dell'esito¶
Il volume mensile è quello previsto dal contratto di ciascun cliente. Consigliamo di non superare 2 chiamate al secondo all'API e 10 documenti al minuto da elaborare; un PDF che contiene più documenti conta come un documento per ciascuno. Oltre queste frequenze le richieste vengono comunque accettate, ma possono restare in coda e i tempi indicati sopra non sono garantiti.
Consegna del webhook¶
L'esito di ogni documento viene inviato con una POST all'URL configurato, che deve rispondere con un codice 2xx entro 25 secondi.
- Se l'endpoint risponde con un errore 5xx, non risponde entro 25 secondi o non è raggiungibile, ripetiamo l'invio dopo 1 secondo: i tentativi sono 2 in tutto.
- Se l'endpoint risponde con un errore 4xx, l'invio non viene ripetuto.
- Se entrambi i tentativi falliscono, l'esito resta consultabile con
GET /applications/{application_id}/fino alla cancellazione dei dati, 30 minuti dopo la chiusura della pratica.
Consigliamo di rispondere subito con HTTP 200 e di elaborare l'esito in un secondo momento.
Supporto e incidenti¶
Gli incidenti sono classificati per gravità:
| Gravità | Esempio | Presa in carico | Ripristino o soluzione temporanea |
|---|---|---|---|
| 1 – Critica | API ferma o nessun documento elaborato | 3 ore lavorative | 8 ore lavorative |
| 2 – Alta | oltre il 10% dei documenti in errore, tempi triplicati | 5 ore lavorative | 2 giorni lavorativi |
| 3 – Media | un tipo di documento non elaborato, webhook in ritardo | 1 giorno lavorativo | 5 giorni lavorativi |
| 4 – Bassa | domande, errori su singoli campi | 2 giorni lavorativi | prossimo rilascio pianificato |
Manutenzione programmata¶
La manutenzione programmata si annuncia con almeno 3 giorni lavorativi di anticipo e si fa nei giorni feriali dalle 20 alle 7, oppure nel weekend.
Gli interventi urgenti di sicurezza si possono fare senza preavviso: in quel caso contano come indisponibilità e si comunicano appena possibile. I cambi che rompono la compatibilità dell'API si annunciano con 30 giorni di anticipo.
Report¶
Su richiesta forniamo un report mensile per cliente con i dati del mese:
- documenti elaborati, per tipo ed esito (
DONE,REJECTED,ERROR), con i motivi degli scarti - tempo tipico e tempo del 95% dei documenti, dal caricamento all'esito, per tipo di documento
- webhook consegnati e non consegnati
- disponibilità dell'API e incidenti del mese, con il resoconto di quelli di gravità 1 e 2
Dati e sicurezza¶
Tutte le chiamate avvengono in HTTPS e sono autenticate con Api-Key. I documenti sono elaborati su infrastruttura AWS e Google Cloud in regioni dell'Unione Europea. File e dati estratti vengono cancellati automaticamente 30 minuti dopo la chiusura della pratica.
Cooabit Service Level AgreementsDefinizioniAmbitoDocumenti accettatiStati ed eventiLivelli di servizioLimiti d'uso e consegna dell'esitoConsegna del webhookSupporto e incidentiManutenzione programmataReportDati e sicurezza