Torna alla home

Documentazione API

Integrate ZyloPro nelle vostre applicazioni

v1.0URL base: https://api.zylopro.com

Avvio rapido

1. Ottenere le credenziali

Registratevi su ZyloPro per creare il vostro account e organizzazione. Potrete poi accedere tramite l'API per ottenere un token di accesso.

2. Autenticazione

L'API utilizza token JWT (Bearer). Includete il token nell'header Authorization delle vostre richieste:

Authorization: Bearer <votre-token>

3. Fare la prima richiesta

Una volta autenticati, potete elencare gli agenti disponibili, eseguire analisi e recuperare i risultati.

Autenticazione

Gli endpoint di autenticazione gestiscono account utente, token di accesso e password.

POST/api/auth/register
Public

Registrazione di una nuova organizzazione con il suo proprietario

Corpo della richiesta

{
  "email": "string",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "organizationName": "string"
}

Risposta

{ success: boolean, token?: string, refreshToken?: string, user?: UserDto }
POST/api/auth/login
Public

Accesso di un utente

Corpo della richiesta

{
  "email": "string",
  "password": "string"
}

Risposta

{ success: boolean, token?: string, refreshToken?: string, user?: UserDto }
POST/api/auth/refresh
Public

Aggiornare il token di accesso con un refresh token

Corpo della richiesta

{
  "refreshToken": "string"
}

Risposta

{ success: boolean, token?: string, refreshToken?: string }
POST/api/auth/revoke
Auth

Revocare un refresh token (disconnessione)

Corpo della richiesta

{
  "refreshToken": "string"
}

Risposta

{ message: string }
GET/api/auth/verify-email
Public

Verificare l'indirizzo email con il token ricevuto via email

Query Params

{
  "token": "string"
}

Risposta

{ message: string }
POST/api/auth/forgot-password
Public

Richiedere un reset della password

Corpo della richiesta

{
  "email": "string"
}

Risposta

{ message: string }
POST/api/auth/reset-password
Public

Reimpostare la password con il token ricevuto via email

Corpo della richiesta

{
  "token": "string",
  "newPassword": "string"
}

Risposta

{ message: string }
POST/api/auth/change-password
Auth

Modificare la password (utente connesso)

Corpo della richiesta

{
  "currentPassword": "string",
  "newPassword": "string"
}

Risposta

{ message: string }

Moduli IA

Gli endpoint degli agenti permettono di elencare, sottoscrivere ed eseguire i 10 moduli IA della piattaforma.

GET/api/agents
Auth

Ottenere tutti gli agenti disponibili sulla piattaforma

Risposta

AgentDto[]
GET/api/agents/organization
Admin

Ottenere gli agenti sottoscritti dall'organizzazione (Admin)

Risposta

AgentDto[]
GET/api/agents/my
Auth

Ottenere gli agenti accessibili dall'utente connesso

Risposta

AgentDto[]
POST/api/agents/{agentId}/subscribe
Owner

Sottoscrivere un agente (livello organizzazione)

Parametri URL

{
  "agentId": "int"
}

Risposta

{ message: string }
POST/api/agents/{agentId}/unsubscribe
Owner

Annullare la sottoscrizione di un agente

Parametri URL

{
  "agentId": "int"
}

Risposta

{ message: string }
POST/api/agents/{code}/execute
Auth

Eseguire un agente con dati di input

Parametri URL

{
  "code": "string (ex: proposalcraft)"
}

Corpo della richiesta

{
  "inputData": "string",
  "projectId": "guid? (optionnel)",
  "metadata": "Record<string, string>? (optionnel)"
}

Risposta

{ success: boolean, status: string, executionId: guid, outputData?: string, error?: string }
GET/api/agents/executions/{executionId}
Auth

Ottenere lo stato di un'esecuzione

Parametri URL

{
  "executionId": "guid"
}

Risposta

AgentExecutionDto
POST/api/agents/executions/{executionId}/cancel
Auth

Annullare un'esecuzione in corso

Parametri URL

{
  "executionId": "guid"
}

Risposta

{ message: string }
GET/api/agents/executions
Auth

Ottenere lo storico delle esecuzioni dell'utente

Query Params

{
  "limit": "int (défaut: 20)"
}

Risposta

AgentExecutionDto[]

Esempi di codice

Accesso e recupero del token
// Exemple de connexion
const response = await fetch('https://api.zylopro.com/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'votre-mot-de-passe'
  })
});

const data = await response.json();
// Stocker le token pour les requêtes ultérieures
const accessToken = data.token;
Esecuzione di un agente
// Exemple d'exécution d'un agent
const response = await fetch('https://api.zylopro.com/api/agents/proposalcraft/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    inputData: "Contenu de l'appel d'offres à analyser...",
    metadata: {
      projectName: "Étude satisfaction client 2025",
      clientName: "ACME Corp"
    }
  })
});

const result = await response.json();
console.log('Exécution ID:', result.executionId);
console.log('Statut:', result.status);
Monitoraggio di un'esecuzione (polling)
// Exemple de polling pour suivre une exécution
async function waitForCompletion(executionId, accessToken) {
  while (true) {
    const response = await fetch(
      `https://api.zylopro.com/api/agents/executions/${executionId}`,
      {
        headers: { 'Authorization': `Bearer ${accessToken}` }
      }
    );

    const execution = await response.json();

    if (execution.status === 'Completed') {
      return execution;
    }

    if (execution.status === 'Failed') {
      throw new Error(execution.errorMessage);
    }

    // Attendre 2 secondes avant le prochain check
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

Tipi di dati

AgentDto

{
  id: number
  code: string
  name: string
  shortDescription: string
  longDescription: string
  category: string
  inputType: string
  outputType: string
  monthlyPrice: number
  includedExecutions: number
  extraExecutionPrice: number
  iconName: string
  color: string
  isActive: boolean
  isBeta: boolean
  isSubscribed: boolean
  hasAccess: boolean
}

AgentExecutionDto

{
  id: guid
  agentCode: string
  agentName: string
  status: "Pending" | "Running" |
          "Completed" | "Failed" |
          "Cancelled"
  createdAt: datetime
  startedAt: datetime | null
  completedAt: datetime | null
  durationSeconds: number | null
  inputTokens: number | null
  outputTokens: number | null
  outputFilePath: string | null
  errorMessage: string | null
}

Gestione degli errori

Codice HTTPDescrizione
200Successo
400Richiesta non valida (parametri mancanti o errati)
401Non autenticato (token mancante o scaduto)
403Accesso vietato (permessi insufficienti)
404Risorsa non trovata
429Troppe richieste (rate limiting)
500Errore interno del server

Formato degli errori

{
  "message": "Description de l'erreur",
  "errors": {
    "fieldName": ["Détail de l'erreur de validation"]
  }
}

Limiti e quote

Rate Limiting

L'API è limitata a 100 richieste al minuto per utente. Gli header X-RateLimit-* indicano lo stato della vostra quota.

Quote di esecuzione

Ogni piano ha un numero di esecuzioni mensili per agente. Consultate la vostra dashboard per monitorare il consumo.

Avete bisogno di aiuto?

Il nostro team tecnico è disponibile per accompagnarvi nell'integrazione dell'API ZyloPro.