API Docs

Documentazione API SempiX

Documentazione completa delle API REST di SempiX. Autentica, emetti fatture, accedi ai movimenti bancari, usa ARYA e configura webhook. Esempi in curl, JavaScript e Python.

15 min Developer guide REST + JSON
Base URLhttps://api.sempix.org/v1REST · JSON · HTTPS

Autenticazione

SempiX utilizza OAuth 2.0 Client Credentials. Genera le credenziali da Impostazioni → API.

curl -X POST https://api.sempix.org/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

# Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Endpoint Principali

POST/v1/auth/token
GET/v1/invoices
POST/v1/invoices
GET/v1/invoices/:id
GET/v1/bank/transactions
GET/v1/customers
POST/v1/aria/ask
POST/v1/webhooks

Creare una Fattura

curl -X POST https://api.sempix.org/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EMESSA",
    "customer_vat": "01234567890",
    "items": [
      {
        "description": "Consulenza software",
        "quantity": 1,
        "unit_price": 1000.00,
        "vat_rate": 22
      }
    ],
    "send_via_sdi": true
  }'

# Response: 201 Created
{
  "id": "inv_abc123",
  "sdi_protocol": "IT01234567890_ABC01.xml",
  "status": "INVIATA",
  "total_amount": 1220.00
}

Webhooks

SempiX invia eventi in tempo reale al tuo endpoint. Eventi supportati: invoice.sdi_accepted, invoice.sdi_rejected, bank.transaction_synced, payment.received.

// Webhook payload example (POST to your endpoint)
{
  "event": "invoice.sdi_accepted",
  "timestamp": "2025-03-15T10:30:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "sdi_protocol": "IT01234567890_ABC01.xml",
    "sdi_status": "ACCETTATA",
    "accepted_at": "2025-03-15T10:28:00Z"
  }
}

// Verify webhook signature (HMAC-SHA256)
const crypto = require('crypto');
const signature = req.headers['x-sempix-signature'];
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(req.body)).digest('hex');
const isValid = crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(expected)
);

Rate Limiting

Impresa BASE

100 req/min

10K req/day

Impresa PRO/PREMIUM

500 req/min

50K req/day

Commercialisti

1000 req/min

100K req/day

Guide Correlate

Inizia a Integrare SempiX

✓ API disponibili dal piano Impresa BASE · Documentazione completa · Supporto sviluppatori