Recursos para Desarrolladores

1. Introducción

nearServices ofrece APIs y SDKs para integrar nuestras herramientas SaaS especializadas en sus aplicaciones empresariales. Nuestro sistema de créditos unificado permite a sus usuarios acceder a múltiples herramientas con una sola integración.

2. Guía de Inicio Rápido

2.1 Obtener Credenciales de API

1. Regístrese en nearServices y verifique su cuenta
2. Acceda al panel de desarrollador en su dashboard
3. Genere sus claves de API (pública y privada)
4. Configure los dominios autorizados para su aplicación

2.2 Autenticación

Utilizamos autenticación basada en API keys con firma HMAC-SHA256:

# Ejemplo de autenticación
curl -X GET "https://api.near.services/v1/tools" \
  -H "X-API-Key: your_public_key" \
  -H "X-Signature: hmac_sha256_signature" \
  -H "X-Timestamp: unix_timestamp"
                

2.3 Primer Llamada a la API

# Obtener lista de herramientas disponibles
GET https://api.near.services/v1/tools

# Respuesta
{
  "tools": [
    {
      "id": "text-analyzer",
      "name": "Analizador de Texto",
      "description": "Análisis avanzado de texto con IA",
      "cost_per_use": 1,
      "currency": "USD",
      "category": "nlp"
    }
  ]
}
                

3. API Reference

3.1 Base URL

https://api.near.services/v1

3.2 Endpoints Principales

Gestión de Créditos

Herramientas SaaS

4. SDKs Disponibles

4.1 JavaScript/Node.js

npm install @nearservices/sdk

// Uso básico
import { NearServices } from '@nearservices/sdk';

const client = new NearServices({
  apiKey: 'your_public_key',
  secretKey: 'your_private_key'
});

// Ejecutar herramienta
const result = await client.tools.execute('text-analyzer', {
  text: 'Texto a analizar',
  options: { sentiment: true, keywords: true }
});
                

4.2 Python

pip install nearservices-sdk

# Uso básico
from nearservices import NearServices

client = NearServices(
    api_key='your_public_key',
    secret_key='your_private_key'
)

# Ejecutar herramienta
result = client.tools.execute('text-analyzer', {
    'text': 'Texto a analizar',
    'options': {'sentiment': True, 'keywords': True}
})
                

4.3 PHP

composer require nearservices/sdk

// Uso básico
use NearServices\Client;

$client = new Client([
    'api_key' => 'your_public_key',
    'secret_key' => 'your_private_key'
]);

// Ejecutar herramienta
$result = $client->tools->execute('text-analyzer', [
    'text' => 'Texto a analizar',
    'options' => ['sentiment' => true, 'keywords' => true]
]);
                

5. Ejemplos de Integración

5.1 Análisis de Texto en Tiempo Real

// Frontend JavaScript
async function analyzeText(text) {
  try {
    const response = await fetch('/api/analyze', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text })
    });
    
    const result = await response.json();
    displayResults(result);
  } catch (error) {
    console.error('Error:', error);
  }
}

// Backend (Node.js/Express)
app.post('/api/analyze', async (req, res) => {
  try {
    const result = await nearServices.tools.execute('text-analyzer', {
      text: req.body.text,
      options: { sentiment: true, entities: true }
    });
    
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
                

5.2 Procesamiento por Lotes

// Procesar múltiples documentos
async function processBatch(documents) {
  const jobs = [];
  
  for (const doc of documents) {
    const job = await nearServices.tools.execute('document-processor', {
      document: doc,
      async: true  // Procesamiento asíncrono
    });
    jobs.push(job);
  }
  
  // Esperar a que todos terminen
  const results = await Promise.all(
    jobs.map(job => nearServices.tools.waitForResult(job.id))
  );
  
  return results;
}
                

6. Webhooks

6.1 Configuración

Configure webhooks para recibir notificaciones sobre eventos importantes:

POST /webhooks
{
  "url": "https://su-app.com/webhooks/nearservices",
  "events": ["job.completed", "credits.low", "tool.error"],
  "secret": "webhook_secret_for_verification"
}
                

6.2 Eventos Disponibles

• job.completed - Trabajo completado
• job.failed - Trabajo falló
• credits.low - Créditos bajos (configurable)
• credits.purchased - Créditos comprados
• tool.error - Error en herramienta

6.3 Verificación de Webhooks

// Verificar firma del webhook
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return signature === `sha256=${expectedSignature}`;
}
                

7. Límites y Cuotas

7.1 Límites de Rate

7.2 Headers de Rate Limit

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
                

8. Manejo de Errores

8.1 Códigos de Error HTTP

8.2 Formato de Errores

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "No tiene suficientes créditos para esta operación",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}
                

9. Mejores Prácticas

9.1 Seguridad

• Nunca exponga sus claves privadas en el frontend
• Use HTTPS para todas las comunicaciones
• Implemente verificación de webhooks
• Rote sus claves de API regularmente

9.2 Rendimiento

• Implemente caché para resultados frecuentes
• Use procesamiento asíncrono para trabajos largos
• Implemente retry con backoff exponencial
• Monitoree el uso de créditos

9.3 Experiencia de Usuario

• Muestre el progreso de trabajos largos
• Implemente notificaciones de créditos bajos
• Proporcione feedback claro sobre errores
• Permita cancelación de trabajos en progreso

10. Soporte y Comunidad

10.1 Canales de Soporte

• Email: developers@near.services
• Discord: discord.gg/nearservices
• GitHub: github.com/nearservices
• Stack Overflow: Tag "nearservices"

10.2 Recursos Adicionales

• Documentación completa de API
• Ejemplos en GitHub
• Blog técnico
• Changelog de API

10.3 Status de Servicios

Monitoree el estado de nuestros servicios en: status.near.services

10.4 Información Legal

nearServices opera desde Buenos Aires, Argentina. Todos los precios se expresan en dólares estadounidenses (USD).