Voltar ao início

Documentação API

Integre a ZyloPro nas suas aplicações

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

Início rápido

1. Obter as suas credenciais

Registe-se na ZyloPro para criar a sua conta e organização. Em seguida, pode autenticar-se através da API para obter um token de acesso.

2. Autenticação

A API utiliza tokens JWT (Bearer). Inclua o token no header Authorization dos seus pedidos:

Authorization: Bearer <votre-token>

3. Fazer o seu primeiro pedido

Uma vez autenticado, pode listar os agentes disponíveis, executar análises e recuperar resultados.

Autenticação

Os endpoints de autenticação gerem contas de utilizador, tokens de acesso e palavras-passe.

POST/api/auth/register
Public

Registo de uma nova organização com o seu proprietário

Corpo do pedido

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

Resposta

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

Início de sessão de um utilizador

Corpo do pedido

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

Resposta

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

Atualizar o token de acesso com um refresh token

Corpo do pedido

{
  "refreshToken": "string"
}

Resposta

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

Revogar um refresh token (terminar sessão)

Corpo do pedido

{
  "refreshToken": "string"
}

Resposta

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

Verificar o endereço de email com o token recebido por email

Query Params

{
  "token": "string"
}

Resposta

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

Solicitar uma reposição de palavra-passe

Corpo do pedido

{
  "email": "string"
}

Resposta

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

Repor a palavra-passe com o token recebido por email

Corpo do pedido

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

Resposta

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

Alterar a palavra-passe (utilizador autenticado)

Corpo do pedido

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

Resposta

{ message: string }

Módulos IA

Os endpoints de agentes permitem listar, subscrever e executar os 10 módulos IA da plataforma.

GET/api/agents
Auth

Obter todos os agentes disponíveis na plataforma

Resposta

AgentDto[]
GET/api/agents/organization
Admin

Obter os agentes subscritos pela organização (Admin)

Resposta

AgentDto[]
GET/api/agents/my
Auth

Obter os agentes acessíveis pelo utilizador autenticado

Resposta

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

Subscrever um agente (nível organização)

Parâmetros URL

{
  "agentId": "int"
}

Resposta

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

Cancelar a subscrição de um agente

Parâmetros URL

{
  "agentId": "int"
}

Resposta

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

Executar um agente com dados de entrada

Parâmetros URL

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

Corpo do pedido

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

Resposta

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

Obter o estado de uma execução

Parâmetros URL

{
  "executionId": "guid"
}

Resposta

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

Cancelar uma execução em curso

Parâmetros URL

{
  "executionId": "guid"
}

Resposta

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

Obter o histórico de execuções do utilizador

Query Params

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

Resposta

AgentExecutionDto[]

Exemplos de código

Autenticação e obtenção do 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;
Execução de um 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);
Acompanhamento de uma execução (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));
  }
}

Tipos de dados

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
}

Gestão de erros

Código HTTPDescrição
200Sucesso
400Pedido inválido (parâmetros em falta ou incorretos)
401Não autenticado (token em falta ou expirado)
403Acesso proibido (permissões insuficientes)
404Recurso não encontrado
429Demasiados pedidos (limitação de taxa)
500Erro interno do servidor

Formato de erros

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

Limites e quotas

Limitação de taxa

A API está limitada a 100 pedidos por minuto por utilizador. Os headers X-RateLimit-* indicam o estado da sua quota.

Quotas de execução

Cada plano tem um número de execuções mensais por agente. Consulte o seu painel de controlo para acompanhar o seu consumo.

Precisa de ajuda?

A nossa equipa técnica está disponível para o acompanhar na integração da API ZyloPro.