Audin Docs
API REST (partner)

Documenti

Prodotti, categorie, clausole, template documento, preventivi e contratti — genera e traccia i documenti commerciali con l'API REST partner.

Versione Markdown di questa pagina

Scarica o copia il contenuto di questa pagina in formato .md — utile per fornirlo a un agente AI che integra questa specifica feature.

Scarica .md

Il gruppo Documenti copre il ciclo dei documenti commerciali: il catalogo prodotti e le sue categorie, le clausole riutilizzabili, i template documento da cui generare preventivi (quote) e contratti, con il tracking del loro stato di invio e firma.

Le risorse

PathDescrizione
/productsCatalogo prodotti / servizi
/product-categoriesCategorie di prodotto
/clausesClausole riutilizzabili per i documenti
/document-templatesTemplate per preventivi e contratti (type QUOTE o CONTRACT)
/quotesPreventivi — crea, invia, traccia stato
/contractsContratti — crea, invia per firma, traccia stato

Tutte le rotte richiedono l'header X-API-Key. Lo schema completo resta sullo Swagger.

Catalogo: prodotti, categorie, clausole

Il prodotto (name obbligatorio, più categoryId, sku, oneTimePrice, recurringPrice, billingPeriod, currency, …) alimenta sia le righe prodotto delle deal sia i documenti. Le categorie (/product-categories) li raggruppano; le clausole (/clauses, con name e content) sono blocchi di testo riutilizzabili nei documenti.

curl -X POST https://api.audin.ai/products \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Licenza Pro",
    "recurringPrice": 49,
    "billingPeriod": "MONTH",
    "currency": "EUR"
  }'
const res = await fetch("https://api.audin.ai/products", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AUDIN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Licenza Pro",
    recurringPrice: 49,
    billingPeriod: "MONTH",
    currency: "EUR",
  }),
});
const product = await res.json();

Ognuna di queste risorse offre le operazioni CRUD standard (GET/POST sulla collezione, GET/PUT/DELETE sul singolo id).

Template documento

Un template documento (/document-templates) ha un type (QUOTE o CONTRACT), un htmlContent e, opzionalmente, defaultClauseIds. È il punto di partenza per generare preventivi e contratti. Filtra per tipo con ?type=QUOTE:

curl "https://api.audin.ai/document-templates?type=QUOTE" \
  -H "X-API-Key: $API_KEY"
const res = await fetch(
  "https://api.audin.ai/document-templates?type=QUOTE",
  { headers: { "X-API-Key": process.env.AUDIN_API_KEY } },
);
// la lista è paginata: { templates, total, currentPage, totalPages, pageSize }
const { templates } = await res.json();

Preventivi (quote)

Un preventivo si crea a partire da una deal e da un template. I campi chiave alla creazione:

CampoTipoObbligatorioNote
dealIdstringsìDeal di riferimento (eredita le righe prodotto)
templateIdstringsìTemplate QUOTE da cui generare il documento
clauseIdsstring[]noClausole da includere
expiresAtstringnoScadenza del preventivo (ISO-8601)

Il ciclo di vita di un preventivo passa per gli stati DRAFT, SENT, VIEWED, ACCEPTED, REJECTED, EXPIRED.

Crea un preventivo da template e invialo

Recupera il template QUOTE desiderato (GET /document-templates?type=QUOTE).

Crea il preventivo con POST /quotes passando dealId e templateId.

Invialo con POST /quotes/{id}/send (genera il documento e lo recapita al contatto della deal).

Traccia lo stato con GET /quotes/{id} ed eventualmente GET /quotes/{id}/events.

# 1. Crea il preventivo dalla deal
QUOTE_ID=$(curl -sX POST https://api.audin.ai/quotes \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dealId":"<deal-id>","templateId":"<template-id>"}' \
  | jq -r '.id')

# 2. Invialo al cliente
curl -X POST "https://api.audin.ai/quotes/$QUOTE_ID/send" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
const headers = {
  "X-API-Key": process.env.AUDIN_API_KEY,
  "Content-Type": "application/json",
};

// 1. Crea il preventivo dalla deal
const quote = await (
  await fetch("https://api.audin.ai/quotes", {
    method: "POST",
    headers,
    body: JSON.stringify({ dealId, templateId }),
  })
).json();

// 2. Invialo al cliente
await fetch(`https://api.audin.ai/quotes/${quote.id}/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});

Contratti

Un contratto si crea come un preventivo (dealId + templateId, opzionalmente quoteId per derivarlo da un preventivo accettato, clauseIds, expiresAt) e si invia per la firma con POST /contracts/{id}/send.

Lo stato del contratto evolve nel tempo e si segue con polling di GET /contracts/{id} (campo status) — non esistono webhook. Gli stati possibili:

StatoSignificato
DRAFTBozza, non ancora inviato
SENTInviato al firmatario
VIEWEDVisualizzato dal firmatario
SIGNEDFirmato (stato finale positivo)
REJECTEDRifiutato dal firmatario
EXPIREDScaduto senza firma

Lo storico degli eventi del documento è disponibile su GET /contracts/{id}/events. Altre operazioni: POST /contracts/{id}/generate-pdf e POST /contracts/{id}/revoke-link.

# Crea e invia un contratto per la firma
CONTRACT_ID=$(curl -sX POST https://api.audin.ai/contracts \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dealId":"<deal-id>","templateId":"<contract-template-id>"}' \
  | jq -r '.id')

curl -X POST "https://api.audin.ai/contracts/$CONTRACT_ID/send" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Polling dello stato
curl "https://api.audin.ai/contracts/$CONTRACT_ID" \
  -H "X-API-Key: $API_KEY" | jq -r '.status'
const headers = {
  "X-API-Key": process.env.AUDIN_API_KEY,
  "Content-Type": "application/json",
};

const contract = await (
  await fetch("https://api.audin.ai/contracts", {
    method: "POST",
    headers,
    body: JSON.stringify({ dealId, templateId: contractTemplateId }),
  })
).json();

await fetch(`https://api.audin.ai/contracts/${contract.id}/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});

// Polling dello stato (no webhook)
const current = await (
  await fetch(`https://api.audin.ai/contracts/${contract.id}`, {
    headers: { "X-API-Key": process.env.AUDIN_API_KEY },
  })
).json();
console.log(current.status); // DRAFT | SENT | VIEWED | SIGNED | REJECTED | EXPIRED

Gli stati che evolvono nel tempo (preventivo aperto/accettato, contratto firmato) si seguono con polling periodico della risorsa: l'API è polling-only, senza webhook. Vedi Flussi operativi.

Schema completo (tutti i campi e parametri): Swagger.

Prossimo passo

Flussi operativi

Invio preventivo e tracking firma contratto end-to-end.

Messaging & email

Notifica il cliente via WhatsApp/SMS o controlla lo stato delle email.

Outbound Webhooks

Ricevi notifiche in tempo reale quando un lead viene creato, aggiornato o eliminato in Audin — eventi firmati HMAC, consegnati con retry durabile verso i tuoi endpoint HTTPS.

Messaging & email

Conversazioni, template WhatsApp, invio messaggi WhatsApp/SMS e lettura dello stato di messaggi ed email Audin Mail con l'API REST partner.

On this page

Le risorseCatalogo: prodotti, categorie, clausoleTemplate documentoPreventivi (quote)Crea un preventivo da template e invialoContrattiProssimo passo