Riferimento tecnico

API per sviluppatori

Quattro endpoint REST, errori strutturati con codici stabili, contratto OpenAPI 3.1 scaricabile. Autenticazione con header x-api-key (la crei dalla dashboard).

Endpoint	Auth	Cosa fa
`POST /v1/validate`	opzionale	Verifica un xFIR e restituisce il report
`POST /v1/generate`	API key	Genera l'XML conforme dal tuo JSON
`POST /v1/convert`	API key	Converte un lotto CSV in xFIR, riga per riga
`GET /v1/errors`	nessuna	Catalogo dei codici errore in JSON

1. Valida un documento

Accetta XML grezzo o JSON {"xml": "..."}. Funziona anche senza API key, con limiti anti-abuso.

Richiesta

curl -X POST https://api.collabfor.it/v1/validate \
  -H "content-type: application/xml" \
  --data-binary @formulario.xml

Risposta

{
  "valid": false,
  "errors": [{
    "code": "BIZ-PIVA-001",
    "message": "Partita IVA non valida: cifra di controllo errata",
    "path": "produttore.codice_fiscale"
  }],
  "warnings": [],
  "meta": { "schema": "xfir-internal-1.0", "engine_version": "0.1.0" }
}

2. Genera l'XML dal tuo JSON

Mandi i dati del formulario come JSON pulito, ricevi l'xFIR conforme al tracciato. Se una regola di business è violata ricevi 422 con l'elenco degli errori.

Richiesta

curl -X POST https://api.collabfor.it/v1/generate \
  -H "x-api-key: $XFIR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "numero_fir": "FIR-2026-000123",
    "data_emissione": "2026-09-15",
    "produttore": {
      "denominazione": "Officina Rossi Srl",
      "codice_fiscale": "12345678903",
      "indirizzo": {"via": "Via Roma", "comune": "Milano",
                    "provincia": "MI", "cap": "20100"}
    },
    "trasportatore": { "...": "..." },
    "destinatario": { "...": "..." },
    "rifiuto": {
      "codice_eer": "13 02 08*",
      "stato_fisico": "L",
      "pericoloso": true,
      "caratteristiche_pericolo": ["HP14"],
      "quantita": {"valore": 120.5, "unita": "kg"}
    },
    "trasporto": {"targa_automezzo": "AB123CD",
                  "data_inizio": "2026-09-15"},
    "destinazione": {"operazione": "R13"}
  }'

3. Converti un lotto CSV

POST /v1/convert con {"csv": "..."}: una riga per formulario, esito e XML per ogni riga. Le colonne richieste sono documentate nel contratto OpenAPI.

Esempio Python

validate.py

import requests

resp = requests.post(
    "https://api.collabfor.it/v1/validate",
    headers={"content-type": "application/xml"},
    data=open("formulario.xml", "rb"),
)
report = resp.json()
if not report["valid"]:
    for err in report["errors"]:
        print(f"{err['code']}: {err['message']} ({err.get('path', '-')})")

Codici errore

Ogni problema ha un codice stabile (es. BIZ-EER-001) che puoi gestire programmaticamente: catalogo completo, disponibile anche via GET /v1/errors.

Limiti e fair use

Piano	Documenti/mese
Free	100
Developer	1.000
Business	10.000

Payload massimo: 2 MB per documento XML, 5 MB per CSV. Oltre il limite mensile l'API risponde 429.

Privacy dei dati

I documenti sono elaborati in memoria nella regione AWS di Milano (eu-south-1) e non vengono conservati. Per i piani a pagamento è incluso il DPA ex art. 28 GDPR.