API per sviluppatori

L'API REST pubblica di EUFactura (piano Scale) consente ai tuoi strumenti — un CRM, un negozio e-commerce, uno script personalizzato — di creare clienti, redigere ed emettere fatture e preventivi, registrare pagamenti e ricevere notifiche sugli eventi principali tramite webhook. Ogni endpoint utilizza esattamente la stessa logica dell'applicazione EUFactura stessa, quindi nulla si comporta diversamente tramite l'API rispetto all'interfaccia.

Documentazione completa

L'API completa è descritta come specifica OpenAPI 3.1 — importala direttamente in Postman, Insomnia o qualsiasi strumento compatibile con OpenAPI.

Autenticazione

Crea una chiave dalla pagina Impostazioni → Sviluppatori della tua organizzazione (solo proprietario/amministratore). Ogni chiave è limitata a un'organizzazione e ha un ruolo — member (lettura e scrittura) o accountant (sola lettura). Il segreto completo viene mostrato una sola volta alla creazione; conservalo in modo sicuro.

curl https://app.eufactura.eu/api/v1/customers?companyId=<company-id> \
  -H "Authorization: Bearer eufk_..."

Creare un cliente ed emettere una fattura

curl -X POST https://app.eufactura.eu/api/v1/customers \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company-id>",
    "type": "business",
    "legalName": "Acme GmbH",
    "countryCode": "DE"
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a UUID you generate>" \
  -d '{
    "companyId": "<company-id>",
    "customerId": "<customer-id>",
    "currency": "EUR",
    "issueDate": "2026-01-01",
    "lines": [{ "description": "Consulting", "quantity": "1", "unitPriceNet": "500" }]
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices/<invoice-id>/issue \
  -H "Authorization: Bearer eufk_..."

Le fatture vengono sempre create come bozze ed emesse come passaggio separato ed esplicito — l'emissione assegna il numero legale della fattura e la rende immutabile, coerentemente con il funzionamento dell'app stessa.

Idempotenza

Invia un'intestazione Idempotency-Key (una stringa a tua scelta, tipicamente un UUID) su una richiesta che modifica dati. Ripetere la stessa richiesta con la stessa chiave restituisce la risposta originale invece di eseguire nuovamente l'azione — sicuro contro i nuovi tentativi di rete e i doppi clic.

Limiti di frequenza

Le richieste sono limitate per chiave API. Una risposta oltre il limite restituisce 429 con un campo equivalente a Retry-After, retryAfter, nel corpo dell'errore.

Errori

Ogni errore viene restituito come {"error": {"code": "...", "message": "..."}}. L'ID di una risorsa appartenente a un'altra organizzazione restituisce sempre 404, mai 403 — EUFactura non conferma mai che una risorsa esiste prima di confermare che puoi accedervi.

Webhook

Registra un URL di endpoint e scegli quali eventi ricevere da Impostazioni → Sviluppatori: invoice.issued, invoice.payment_recorded, quote.converted e credit_note.issued. Ogni consegna è un POST HTTPS firmato:

POST <your endpoint>
Content-Type: application/json
X-EUFactura-Signature: t=1700000000,v1=<hex-encoded HMAC-SHA256>

{"id": "...", "type": "invoice.issued", "data": { ... }}

Verificalo calcolando un HMAC-SHA256 del timestamp, di un punto letterale e del corpo grezzo della richiesta usando il segreto del tuo endpoint, e confrontando il risultato con il valore v1 — lo stesso formato t=...,v1=... utilizzato da Stripe per i propri webhook, quindi qualsiasi codice di verifica dei webhook Stripe che già possiedi è un buon punto di partenza. Le consegne vengono ripetute con backoff in caso di errore (fino a cinque tentativi in circa 12 ore); il tuo endpoint dovrebbe essere idempotente rispetto all<id>id</id> del payload.

Domande

Contattaci all'indirizzo hello@eufactura.eu.