> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integración de registros personalizada
> Esta documentación explica cómo enviar los registros de tu aplicación directamente a la plataforma de análisis de Profound mediante nuestra API de integración de registros personalizada.
## Descripción general
La integración de registros personalizada te permite enviar los registros de tu aplicación directamente a la plataforma de análisis de Profound con un formato JSON estandarizado. Esta integración admite el procesamiento por lotes de registros e incluye una validación sólida para garantizar la calidad de los datos, a la vez que ofrece información detallada sobre cualquier problema de validación.
## Requisitos previos
* Tu Log Ingestion Token de Profound
* La capacidad de enviar solicitudes HTTP POST desde tu aplicación o infraestructura
## Especificación de la API
### Endpoint
```http theme={null}
POST https://artemis.api.tryprofound.com/v1/logs/custom
```
### Autenticación
Incluye tu Log Ingestion Token de Profound en el encabezado de la solicitud:
```http theme={null}
'x-api-key': 'bot_PROFOUND_LOG_INGESTION_TOKEN'
```
### Formato de la solicitud
Los registros deben enviarse como un array de objetos JSON. Cada entrada de registro requiere campos específicos:
#### Campos obligatorios
* `timestamp` - Marca de tiempo del evento (marca de tiempo Unix o cadena ISO 8601)
* `method` - Método HTTP (máximo 10 caracteres)
* `host` - Nombre de host de la solicitud (máximo 255 caracteres)
* `path` - Ruta de la solicitud (máximo 2048 caracteres)
* `status_code` - Código de estado HTTP (rango: 100-599)
* `ip` - Dirección IP del cliente (máximo 45 caracteres)
* `user_agent` - Cadena de user agent (máximo 1024 caracteres)
#### Campos opcionales
Tanto `query_params` como `referer` son opcionales. Sin embargo, si no proporcionas ninguno de los dos, los datos de referidos humanos **no estarán disponibles** en tu panel.
* `query_params` - Parámetros de consulta (clave máx.: 100 caracteres, valor máx.: 1000 caracteres)
* `referer` - Referer de la solicitud (máximo 2048 caracteres)
* `bytes_sent` - Tamaño de la respuesta en bytes (debe ser >= 0)
* `duration_ms` - Duración de la solicitud en milisegundos (debe ser >= 0)
Cada solicitud puede contener hasta 1000 entradas de registro. Para conjuntos de datos más grandes, divide tus registros en varias solicitudes.
## Guía de implementación
Prepara los datos de tus registros en el formato JSON requerido:
```json theme={null}
[
{
"timestamp": "2024-01-11T12:00:00Z",
"method": "GET",
"host": "example.com",
"path": "/products",
"status_code": 200,
"ip": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"query_params": {
"category": "electronics",
"page": "1"
},
"referer": "https://example.com",
"bytes_sent": 1024,
"duration_ms": 150
}
]
```
Así puedes enviar registros con lenguajes de programación populares:
Python:
```python theme={null}
import requests
import json
logs = [{
"timestamp": "2024-01-11T12:00:00Z",
"method": "GET",
"host": "example.com",
"path": "/products",
"status_code": 200,
"ip": "192.168.1.1",
"user_agent": "Mozilla/5.0..."
}]
response = requests.post(
"https://artemis.api.tryprofound.com/v1/logs/custom",
headers={
"x-api-key": "bot_PROFOUND_LOG_INGESTION_TOKEN",
"Content-Type": "application/json"
},
json=logs
)
print(response.json())
```
Node.js:
```javascript theme={null}
const axios = require('axios');
const logs = [{
timestamp: "2024-01-11T12:00:00Z",
method: "GET",
host: "example.com",
path: "/products",
status_code: 200,
ip: "192.168.1.1",
user_agent: "Mozilla/5.0..."
}];
axios.post('https://artemis.api.tryprofound.com/v1/logs/custom', logs, {
headers: {
'x-api-key': 'bot_PROFOUND_LOG_INGESTION_TOKEN',
'Content-Type': 'application/json'
}
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```
Procesa la respuesta de la API para confirmar que la ingesta se realizó correctamente o para gestionar cualquier error:
Respuesta correcta:
```json theme={null}
{
"status": "accepted",
"message": "Processing X log entries",
"first_visit_id": "uuid-string",
"errors": []
}
```
Respuesta con errores de validación:
```json theme={null}
{
"status": "accepted",
"message": "Processing 98 log entries",
"first_visit_id": "uuid-string",
"errors": [
"Invalid log format: timestamp out of reasonable range",
"Invalid log format: status_code must be between 100 and 599"
]
}
```
## Gestión de errores
La API gestiona los errores de dos maneras:
### Errores de validación
Ante problemas de validación previstos (marcas de tiempo no válidas, datos con formato incorrecto, etc.), la API:
* Seguirá procesando las entradas válidas del lote
* Agregará los errores de validación al array `errors` de la respuesta
* Devolverá un código de estado 200 con las entradas procesadas y los errores
### Errores inesperados
Ante errores inesperados (problemas del servidor, problemas de la base de datos, etc.), la API:
* Devolverá un código de estado 500
* Devolverá un mensaje de error en el campo detail de la respuesta
* No procesará ninguna entrada del lote
## Prácticas recomendadas
* Agrupa los registros en lotes de hasta 1000 entradas
* Implementa lógica de reintentos para las solicitudes fallidas
* Usa procesamiento en segundo plano para el envío de registros
* Envía los registros de forma asíncrona para no afectar al rendimiento de la aplicación
* Considera implementar un búfer local
* Usa compresión para cargas útiles grandes
## Soporte
* Escribe a [support@tryprofound.com](mailto:support@tryprofound.com) para obtener ayuda
## Consideraciones de seguridad
* Almacena los Log Ingestion Tokens de forma segura
* Rota los Log Ingestion Tokens con regularidad
* Supervisa los registros de solicitudes para detectar patrones inusuales
* Usa HTTPS para todas las solicitudes a la API
***