Salta ai contenuti
Escriba Suite Escriba Suite

Documentazione di Arcanum

Arcanum trasforma il lavoro sporco dei web service SOAP di ARCA — costruire il TRA, firmarlo, accedere a WSAA, mettere in cache, avvolgere l’envelope SOAP, analizzare l’XML — in una chiamata REST pulita. Tu chiedi in JSON; Arcanum si occupa del resto.

Terminal window
curl -X POST https://your-arcanum/api/ws/padron_a5/getPersona_v2 \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "cuit": "20111111112", "params": { "idPersona": "20999999993" } }'

Come funziona

Sezione intitolata “Come funziona”

100% local WSAA signing

Il TRA viene firmato in CMS/PKCS#7 in memoria, dentro il tuo container, con node-forge — nessun SDK che chiama una terza parte. La chiave privata è memorizzata cifrata con AES-256-GCM in Postgres; la master key risiede solo nell’ambiente.

Cached token, self-healing

Il ticket di accesso (Token + Sign) viene messo in cache per CUIT + servizio + ambiente, con lock consultivi così che due richieste simultanee non scatenino mai due login. Un daemon lo rinnova prima della scadenza e, se ARCA dovesse rifiutare un token scaduto, Arcanum riprova in modo trasparente.

Editable catalog + generic engine

Ogni servizio di ARCA risiede in un catalogo dichiarativo. POST /api/ws/{service}/{operation} chiama qualsiasi operazione di qualsiasi servizio con un corpo JSON. ARCA cambia spesso gli endpoint — il superadmin li modifica dall’interfaccia, salvati e auditati, senza un nuovo deploy.

Multi-client, multi-environment

Gestisci diversi CUIT da una sola istanza e passa da omologazione a produzione dall’interfaccia — a caldo e persistito, senza toccare variabili né ridistribuire.

La superficie REST

Sezione intitolata “La superficie REST”
  • Motore generico — POST /api/ws/{service}/{operation} raggiunge qualsiasi operazione del catalogo. Arcanum costruisce l’envelope e risolve l’autenticazione per te.
  • Moduli ricchi — i servizi più usati (fatturazione, consultazioni dei registri e altro) espongono anche endpoint REST ergonomici con validazione e risposte JSON pulite.
  • API key — ogni chiamata porta X-API-Key. Arcanum è pensato per stare sulla tua rete o dietro un reverse proxy con TLS.

Fatturazione

Sezione intitolata “Fatturazione”

Il modulo di fatturazione emette e ottiene il CAE con numerazione automatica, gestisce note di credito e debito con i documenti associati, valida gli importi in anticipo, applica l’idempotenza (niente doppio CAE) e produce un PDF legale con il QR di ARCA. Ristampe e consultazioni sono a una chiamata di distanza.

Ciclo di vita del certificato

Sezione intitolata “Ciclo di vita del certificato”

Arcanum genera il CSR; tu lo carichi su ARCA e incolli di nuovo il .crt. Da quel momento la chiave privata resta cifrata a riposo, e il pannello ti avvisa dei certificati che stanno per scadere.

Automatizza da n8n

Sezione intitolata “Automatizza da n8n”

Poiché la superficie è semplice REST con una API key, collegare ARCA a un flusso n8n (o a qualsiasi sistema) è una singola richiesta HTTP — niente SOAP, niente SDK.