Leggete il contratto prima di parlarci.

Il contratto parla da sé

Tutto ciò che riguarda richiesta e risposta — ogni campo, il suo tipo, se è obbligatorio, le strutture annidate, esempi completi, la politica di deprecazione e il limite di richieste — lo fornisce l’API stessa:

curl https://cerrax-portal-api-zenqusyaia-nw.a.run.app/v1

È generato dagli stessi modelli che validano la vostra richiesta, quindi non può disallinearsi da ciò che l’endpoint accetta. Per questo la pagina è corta: tutto ciò che ricopiassimo qui sarebbe una seconda copia, e le seconde copie invecchiano.

Calcolare il prezzo di un lavoro

La richiesta più piccola che restituisce un prezzo:

curl -X POST https://cerrax-portal-api-zenqusyaia-nw.a.run.app/v1/price \
  -H "X-Cerrax-Api-Key: <la vostra chiave>" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "it",
    "volumeM3": 32.0,
    "distance": { "value": 77, "unit": "km" }
  }'

Indicate distance (un valore e un’unità — qui chilometri) oppure entrambi i codici postali. Accesso, rettifiche, livello di imballaggio, date e il vostro riferimento sono tutti facoltativi — e la guida ai campi su /v1 li elenca tutti con il loro significato.

Cosa promettiamo, e cosa no

• Lo stesso lavoro restituisce lo stesso prezzo. Il motore è deterministico e versionato; un dato input e una data versione producono sempre la stessa cifra, e ogni modifica è pubblicata con la data su /kernel/changelog.
• Aggiungere un campo non è una modifica incompatibile; toglierne uno comporta una nuova versione. La politica di deprecazione completa, preavviso compreso, è nel contratto.
• La chiave identifica l’impresa. Non c’è nessun campo moverId da passare — non potete calcolare per errore un prezzo per conto di qualcun altro.
• Un campo che non accettiamo viene rifiutato, non ignorato. Un refuso restituisce un 422 che lo nomina, invece di un prezzo che ha ignorato in silenzio ciò che avete inviato.
• Quando non sa, lo dice. Con dati incerti la risposta può essere un rinvio a una persona invece di una cifra. Preferiamo darvi un rifiuto onesto che un’ipotesi sicura di sé.

Ottenere una chiave

Le chiavi si rilasciano per impresa, parlandone — siamo agli inizi e preferiamo capire cosa state integrando piuttosto che distribuire credenziali in massa. Raccontateci cosa state costruendo e vi risponderemo entro un giorno lavorativo.

Niente di quanto sopra ne richiede una. Se leggere il contratto basta a dirvi che non fa per voi, è un buon risultato, e vi è costato un curl.