API cofferweb — versione 1

1Cosa puoi fare

Le API v1 coprono il ciclo della fattura di vendita: crearla, trasmetterla al Sistema di Interscambio, seguirne l’esito e scaricarne l’XML. Sono pensate per casi come questi:

• un e-commerce che fattura in automatico ogni ordine pagato;
• un gestionale di magazzino o di produzione che emette la fattura a fine lavoro;
• un software di prenotazioni che fattura il servizio erogato;
• un’automazione (Zapier, Make, n8n, script interni) che chiude il ciclo.

2Prima di iniziare

Serve che nel gestionale sia già a posto quello che servirebbe comunque per fatturare a mano. Se manca qualcosa qui, l’API se ne accorge e risponde con un errore 422.

3La chiave API

Generarla

Impostazioni › Chiavi API → Genera chiave. Dai un nome che dica quale sistema è collegato (“E-commerce”, “Gestionale magazzino”, “Zapier”): serve a te il giorno in cui devi revocarne una sola senza fermare le altre.

Che aspetto ha

La parte centrale dice alle API su quale azienda lavorare: per questo non devi indicare l’azienda da nessun’altra parte. Il formato accettato è cw_ + da 1 a 32 caratteri alfanumerici + _ + da 32 a 128 caratteri alfanumerici; qualsiasi altra forma viene rifiutata prima ancora di interrogare il database.

Tenerla al sicuro

• Va messa solo nell’intestazione della richiesta, mai nell’indirizzo: gli indirizzi finiscono nei log dei server e nella cronologia dei browser.
• Conservala tra i segreti del sistema che la usa (variabile d’ambiente, vault), non dentro il codice sorgente versionato.
• Una chiave per ogni integrazione: revocarne una non ferma le altre.
• Se un fornitore esterno smette di lavorare con te, revoca la sua chiave: da quel momento le sue richieste ricevono 403 e non serve fare altro.

Ogni chiamata andata a buon fine aggiorna la colonna Ultimo utilizzo nella pagina delle chiavi: è il modo più rapido per capire se un’integrazione è ancora viva — o se una chiave che credevi ferma sta ancora lavorando.

4Il primo test

Prima di scrivere qualsiasi cosa, verifica che la chiave apra la porta giusta:

curl https://app.cofferweb.com/api/v1/ping \
  -H "X-API-Key: cw_a43b5_LA_TUA_CHIAVE"

{
  "ok": true,
  "versione": "v1",
  "azienda": "Rossi S.r.l.",
  "chiave": "E-commerce"
}

5Anatomia di una richiesta

Se gli indirizzi “puliti” non sono attivi

Le stesse chiamate funzionano anche senza riscrittura degli indirizzi, in due forme equivalenti:

https://app.cofferweb.com/api/v1/index.php/fatture/812/sdi
https://app.cofferweb.com/api/v1/index.php?percorso=fatture/812/sdi

6Elenco dei comandi

{
  "servizio": "cofferweb API",
  "versione": "v1",
  "percorsi": ["ping", "anagrafiche", "fatture", "fatture/{id}",
               "fatture/{id}/sdi", "fatture/{id}/xml", "fatture/{id}/notifica"]
}

{
  "aliquote_iva": [
    { "id": 3, "nome": "IVA 22%", "percentuale": 22 },
    { "id": 5, "nome": "IVA 10%", "percentuale": 10 }
  ],
  "clienti": [
    { "id": 42, "codice": "CL0042", "nome": "Rossi S.r.l." }
  ],
  "pagamenti_fe": {
    "MP01": "contanti",            "MP02": "assegno",
    "MP05": "bonifico",            "MP08": "carta di pagamento",
    "MP12": "RIBA",                "MP19": "SEPA Direct Debit"
  }
}

curl -X POST https://app.cofferweb.com/api/v1/fatture \
  -H "X-API-Key: cw_a43b5_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 42,
    "data": "26/07/2026",
    "elettronica": true,
    "pagamento_fe": "MP05",
    "note": "Ordine web #10245",
    "righe": [
      { "descrizione": "Abbonamento annuale", "quantita": 1, "prezzo": 250.00, "iva": 22 },
      { "descrizione": "Installazione", "quantita": 2, "prezzo": 80.00, "iva": 22, "sconto": 10 }
    ]
  }'

{ "fattura": {
    "id": 812, "numero": 137, "codice": "FT137", "data": "26/07/2026",
    "cliente": "Rossi S.r.l.",
    "imponibile": 394.00, "iva": 86.68, "totale": 480.68,
    "stato": "da_inviare", "inviata_al_sdi": false,
    "data_invio_sdi": null, "notifica_sdi": null,
    "notifica_descrizione": null, "file_xml": null
} }

curl -X POST https://app.cofferweb.com/api/v1/fatture/812/sdi \
  -H "X-API-Key: cw_a43b5_LA_TUA_CHIAVE"

{ "fattura": {
    "id": 812, "numero": 137, "codice": "FT137", "data": "26/07/2026",
    "cliente": "Rossi S.r.l.",
    "imponibile": 394.00, "iva": 86.68, "totale": 480.68,
    "stato": "notificata", "inviata_al_sdi": true,
    "data_invio_sdi": "26/07/2026 11:04",
    "notifica_sdi": "RC",
    "notifica_descrizione": "Ricevuta di consegna: la fattura e' stata consegnata al destinatario.",
    "file_xml": "IT01234567890_00001.xml",
    "righe": [
      { "descrizione": "Abbonamento annuale", "quantita": 1, "prezzo": 250,
        "imponibile": 250, "iva": 55, "totale": 305 }
    ]
} }

{ "notifica": {
    "tipo": "RC",
    "descrizione": "Ricevuta di consegna: la fattura e' stata consegnata al destinatario.",
    "contenuto": "PD94bWwg…" },
  "fattura": { "id": 812, "stato": "notificata", … } }

{ "nome_file": "IT01234567890_00001.xml",
  "contenuto": "PD94bWwgdmVyc2lvbj0i…" }

7L’oggetto fattura

È la stessa struttura in tutte le risposte che riguardano un documento.

8Stati e notifiche SDI

Il campo stato

Le sigle delle notifiche

9Errori

Tutti gli errori hanno la stessa forma, e sono sempre JSON:

{ "errore": {
    "codice": "aliquota_non_trovata",
    "messaggio": "Riga 1: aliquota IVA 4% non configurata in azienda.",
    "dettagli": [ { "id": 3, "nome": "IVA 22%", "percentuale": 22 } ] } }

codice è stabile ed è quello su cui scrivere la logica; messaggio è per gli umani; dettagli compare quando c’è qualcosa di utile da mostrare — per esempio l’elenco delle aliquote effettivamente configurate.

10Il flusso completo

Un e-commerce che fattura un ordine pagato, passo per passo:

1. (una volta)    GET  /anagrafiche          -> memorizza id cliente e id aliquote
2. ordine pagato  POST /fatture              -> ottieni id = 812, stato "da_inviare"
3. subito dopo    POST /fatture/812/sdi      -> stato "inviata"
4. ogni 15 min    GET  /fatture/812/notifica -> finche' arriva una notifica
5. se RC/DT/MC    archivia l'XML e chiudi l'ordine
   se NS          segnala all'amministrazione: va corretta e riemessa

11Esempi di codice

PHP

<?php
function cofferweb($percorso, $metodo = 'GET', $dati = null) {
    $ch = curl_init('https://app.cofferweb.com/api/v1/' . $percorso);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $metodo);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'X-API-Key: ' . getenv('COFFERWEB_API_KEY'),
        'Content-Type: application/json'
    ));
    if ($dati !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dati));
    }
    $risposta = curl_exec($ch);
    $stato = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $corpo = json_decode($risposta, true);
    if ($stato >= 400) {
        throw new Exception($corpo['errore']['messaggio'] . ' (' . $corpo['errore']['codice'] . ')');
    }
    return $corpo;
}

// crea e invia
$creata = cofferweb('fatture', 'POST', array(
    'cliente_id' => 42,
    'righe' => array(
        array('descrizione' => 'Abbonamento annuale', 'quantita' => 1, 'prezzo' => 250, 'iva' => 22)
    )
));

$id = $creata['fattura']['id'];
$inviata = cofferweb('fatture/' . $id . '/sdi', 'POST');

echo 'Fattura ' . $inviata['fattura']['codice'] . ' - stato: ' . $inviata['fattura']['stato'];

JavaScript (Node)

const BASE = 'https://app.cofferweb.com/api/v1/';

async function cofferweb(percorso, metodo = 'GET', dati) {
  const risposta = await fetch(BASE + percorso, {
    method: metodo,
    headers: {
      'X-API-Key': process.env.COFFERWEB_API_KEY,
      'Content-Type': 'application/json'
    },
    body: dati ? JSON.stringify(dati) : undefined
  });

  const corpo = await risposta.json();
  if (!risposta.ok) {
    throw new Error(`${corpo.errore.messaggio} (${corpo.errore.codice})`);
  }
  return corpo;
}

const { fattura } = await cofferweb('fatture', 'POST', {
  cliente_id: 42,
  righe: [{ descrizione: 'Abbonamento annuale', quantita: 1, prezzo: 250, iva: 22 }]
});

await cofferweb(`fatture/${fattura.id}/sdi`, 'POST');

12Buone pratiche

13Domande frequenti