Interfaccia per software e agenti

Questa piattaforma serve a pubblicare annunci, e anche un software deve poterlo fare: un gestionale di magazzino, uno script o un agente IA. L’interfaccia web è una rappresentazione; l’API è la seconda via, di pari valore.

L’accesso

La chiave viene creata dall’utente stesso, sotto «Accessi» nel suo conto, e comunicata al software. Noi non creiamo chiavi e non possiamo rimostrare una chiave già emessa: viene salvata sotto forma di hash.

Vai agli accessi

Si invia come una normale intestazione Bearer:

Authorization: Bearer ia_…

Per la macchina: lo schema

Questa pagina spiega a una persona che cosa può fare un agente. L’agente stesso preferisce uno schema: è disponibile come OpenAPI all’indirizzo qui sotto e non richiede una chiave, perché chi costruisce un client non ne ha ancora una.

GET https://inserate-anzeigen.ch/api/schnittstelle.json

Cosa può fare una chiave

Esattamente tre cose. Tutto il resto risponde 403 — anche una via aggiunta in seguito: è permesso ciò che figura nella tabella, non tutto ciò che non è vietato.

Le vie

POST	`/api/inserate`	Creare un annuncio
POST	`/api/inserate/:id/pausieren`	Ritirarlo: la durata residua si ferma
POST	`/api/inserate/:id/fortsetzen`	Ripubblicarlo, con la durata residua congelata
GET	`/api/inserate/meine`	Leggere gli annunci, fin dove arriva la chiave

Per compilare i campi: queste vie sono aperte anche senza chiave.

GET	`/api/grenzen`
GET	`/api/kategorien`
GET	`/api/kategorien/:pfad/merkmale`
GET	`/api/orte/:plz`

Cosa non può fare

Eliminare, modificare, segnalare come venduto, prolungare, cambiare il profilo, scrivere messaggi, creare altre chiavi. Per questo serve un accesso con e-mail e password. E una chiave può ripubblicare solo ciò che ha sospeso essa stessa: ciò che sospende lei nel browser, lo rimette online soltanto lei.

Fin dove arriva una chiave

Lo decide la persona al momento della creazione, e la scelta predefinita è la più stretta: una chiave normale vede e tocca solo gli annunci che ha pubblicato lei stessa. Chi sceglie «tutti gli annunci di questo conto» ottiene una chiave che tocca anche quelli dal browser. Fuori dalla sua portata un percorso risponde 403 con felder.grund = ausserhalb-des-schluessels — si legge esattamente fin dove si può agire.

Un esempio completo

Questo è il corpo minimo con cui un annuncio diventa pubblico: ogni campo è obbligatorio, nessuno manca. Una bozza (status: entwurf) può avere lacune; un annuncio pubblico richiede titolo, almeno 20 caratteri di descrizione, categoria, tipo di prezzo con il prezzo e l’indicazione completa del luogo.

POST /api/inserate
Authorization: Bearer ia_…
Idempotenz-Schluessel: VH-1009
Content-Type: application/json

{
  "titel": "Cube Aim Pro Mountainbike",
  "beschreibung": "Occasion, geprüft und fahrbereit. Abholung in Zürich.",
  "kategorieId": 4,
  "preisart": "fix",
  "preis": 780,
  "plz": "8004",
  "ort": "Zürich",
  "kanton": "ZH"
}

Ed ecco cosa torna indietro, ridotto a ciò che un chiamante legge davvero:

201 Created

{
  "inserat": {
    "id": 418,
    "slug": "cube-aim-pro-mountainbike-418",
    "status": "aktiv", …
  },
  "marktlage": {
    "spiegel": {
      "anzahl": 14,
      "vonRappen": 196500,
      "bisRappen": 335000,
      "dazwischen": 6
    },
    "ungewoehnlichHoch": false
  }
}

La stessa richiesta due volte

Un’interruzione di rete non deve creare un secondo annuncio. Alla creazione invii un valore suo — il numero di magazzino è il candidato naturale. Se lo stesso valore torna entro 24 ore, rispondiamo 200, con lo stesso identificativo e wiederholung: true, invece di creare. Il valore vale per conto; i numeri brevi sono espressamente ammessi.

Idempotenz-Schluessel: VH-1009

Con quale frequenza

Per chiave: 20 creazioni all’ora, 100 al giorno. Per i conti commerciali sono 50 all’ora: un magazzino si inserisce in un colpo solo, non a gocce; il limite giornaliero resta lo stesso. Oltre, rispondiamo 429 e indichiamo nell’intestazione Retry-After i secondi da attendere: li aspetti invece di indovinare. Le richieste dall’interfaccia web non contano qui.

Cosa può andare storto

Ogni errore ha la stessa forma: una frase in fehler e, dove c’è qualcosa da distinguere, un campo in felder. I tre 401 sono volutamente distinguibili: richiedono da lei cose opposte.

401	`grund: unbekannt`	Il valore non è corretto
401	`grund: widerrufen`	L’accesso è stato revocato
401	`grund: konto-gesperrt`	Il conto è bloccato o chiuso
403	`grund: ausserhalb-des-umfangs`	Questa via non è aperta alle chiavi
403	`—`	L’annuncio appartiene a un altro
404	`—`	Questo identificativo non esiste
409	`—`	Lo stato non lo consente
422	`felder: { … }`	Un dato manca o non è valido
429	`Retry-After`	Troppe richieste: attenda i secondi indicati

Cosa torna indietro

Alla creazione riceve l’annuncio e due informazioni che non impediscono nulla: marktlage indica la fascia della categoria e se il suo prezzo la supera; hinweis compare se non conosciamo il suo codice postale — l’annuncio non comparirà allora in nessuna ricerca per raggio. Alla messa in pausa le diciamo quante conversazioni e quante proposte di prezzo aperte sta lasciando in sospeso.

A cosa ci impegniamo

Verifichiamo la correttezza degli annunci. Un annuncio contrario alle regole viene bloccato, anche se lo ha inserito un software.
Ogni annuncio creato tramite l’API sa da dove viene. Il venditore e l’amministrazione lo vedono; gli acquirenti no.
Una revoca ha effetto immediato. Il blocco e la chiusura di un conto revocano tutte le chiavi del conto.
Il valore della chiave è salvato sotto forma di hash. Non possiamo ripristinarlo e non glielo chiederemo mai.

Un’avvertenza finale

Questa interfaccia è fatta per pubblicare, non per estrarre. Chi preleva dati in massa viola le regole d’uso, e il limite è calibrato su ciò che un venditore fa con il proprio magazzino.