Integración API
Especificaciones técnicas para la integración de API.
1. URL base
La URL de tu endpoint se muestra en la página de detalles del endpoint.
https://api.3minapi.com/api/v1/data/{slug}https://api.3minapi.com/api/v1/data/{slug}/searchhttps://api.3minapi.com/api/v1/data/{slug}/pollhttps://api.3minapi.com/api/v1/data/{slug}/{record_id}2. Autenticación
Incluye tu clave API en el encabezado.
| Encabezado | Descripción | Obligatorio |
|---|---|---|
| Authorization | Bearer tm_test_xxx... / Bearer tm_live_xxx... | Yes |
| Content-Type | application/json | Yes |
| X-Webhook-Callback | URL del webhook | No |
| X-Webhook-Auth | Valor de autenticación (ej., token Bearer) | No |
| X-Webhook-Auth-Header | Nombre del encabezado de autenticación | No |
3. Formato de solicitud
- Content-Type: Solo application/json
- Tamaño máximo: 100KB por solicitud
- Método: POST / GET (individual + lista + búsqueda + sondeo) / PUT / DELETE
Endpoints CRUD
Cada endpoint soporta automáticamente los siguientes métodos HTTP:
| Método | Ruta | Descripción |
|---|---|---|
POST | /api/v1/data/{slug} | Crear un nuevo registro (asíncrono, en cola) |
GET | /api/v1/data/{slug}/{record_id} | Recuperar un registro por ID |
GET | /api/v1/data/{slug} | Listar registros recientes (paginación cursor, 10 por página por defecto / máximo 30) |
GET | /api/v1/data/{slug}/search | Buscar registros por texto del payload (q obligatorio, rango de fechas opcional — por defecto últimos 30 días, paginación por cursor) |
GET | /api/v1/data/{slug}/poll | Obtener registros creados desde el último sondeo, del más antiguo al más reciente (paginación por cursor, 100 por defecto / máx. 100 por página) |
PUT | /api/v1/data/{slug}/{record_id} | Reemplazar un registro por ID (asíncrono, en cola) |
DELETE | /api/v1/data/{slug}/{record_id} | Eliminar un registro por ID (asíncrono, en cola) |
GET (individual), PUT y DELETE requieren un ID de registro devuelto de una respuesta POST anterior. GET (lista), GET (búsqueda) y GET (sondeo) no requieren ID.
POST — Crear:
curl -X POST https://api.3minapi.com/api/v1/data/{slug} \
-H "Authorization: Bearer tm_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORD-2024-001",
"amount": 45000,
"items": ["Item A", "Item B"],
"paid": true
}' GET — Leer:
curl https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
-H "Authorization: Bearer tm_test_xxx" GET — Lista:
curl "https://api.3minapi.com/api/v1/data/{slug}?limit=10" \
-H "Authorization: Bearer tm_test_xxx"
# Next page — pass the next_cursor returned in the previous response
curl "https://api.3minapi.com/api/v1/data/{slug}?limit=10&cursor=<next_cursor>" \
-H "Authorization: Bearer tm_test_xxx" GET — Buscar:
# q is required (min 3 chars). start/end are optional — defaults to last 30 days.
curl "https://api.3minapi.com/api/v1/data/{slug}/search?q=keyword&limit=10" \
-H "Authorization: Bearer tm_test_xxx"
# Next page — pass the next_cursor returned in the previous response
curl "https://api.3minapi.com/api/v1/data/{slug}/search?q=keyword&limit=10&cursor=<next_cursor>" \
-H "Authorization: Bearer tm_test_xxx" GET — Sondeo:
# First call — no cursor. Subscribes from now on.
# Use ?since=2026-08-01T00:00:00Z (or 2026-08-01) to start from a point in time — always UTC.
curl "https://api.3minapi.com/api/v1/data/{slug}/poll?limit=100" \
-H "Authorization: Bearer tm_test_xxx"
# Every response carries exactly one of two cursors:
# next_cursor — a backlog remains. Call again right away with it.
# poll_cursor — you are caught up. Save it and wait for the next cycle.
# The newest ~60 seconds are held back until the queue catches up, so those
# records arrive on a later poll instead of being skipped.
# The whole loop:
CURSOR=""
while true; do
CODE=$(curl -s -o /tmp/poll.json -w '%{http_code}' \
"https://api.3minapi.com/api/v1/data/{slug}/poll?limit=100&cursor=$CURSOR" \
-H "Authorization: Bearer tm_test_xxx")
# On any error, keep the cursor and retry. Overwriting it would lose your place.
if [ "$CODE" != "200" ]; then
echo "poll failed with HTTP $CODE" >&2
sleep 60
continue
fi
jq -c '.data[]' /tmp/poll.json # oldest first — dedupe on id, retries can repeat a record
NEXT=$(jq -r '.pagination.next_cursor // empty' /tmp/poll.json)
if [ -n "$NEXT" ]; then CURSOR=$NEXT; continue; fi # more waiting — no sleep
POLL=$(jq -r '.pagination.poll_cursor // empty' /tmp/poll.json)
if [ -n "$POLL" ]; then CURSOR=$POLL; fi # caught up — save and wait
sleep 60
done PUT — Actualizar:
curl -X PUT https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
-H "Authorization: Bearer tm_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORD-2024-001",
"amount": 50000,
"items": ["Item A", "Item B", "Item C"],
"paid": true
}' DELETE — Eliminar:
curl -X DELETE https://api.3minapi.com/api/v1/data/{slug}/rec_abc123 \
-H "Authorization: Bearer tm_test_xxx" 4. Formato de respuesta
Respuesta exitosa (202):
{
"success": true,
"id": "rec_abc123",
"message": "Request queued"
} Ejemplo de respuesta de error (400):
{
"success": false,
"error": "Validation failed",
"details": [
{ "field": "order_id", "error": "Required field is missing" }
]
} Respuestas de error:
| Code | Status | Description |
|---|---|---|
400 | Solicitud incorrecta | JSON inválido o campos obligatorios faltantes |
401 | No autorizado | Clave API faltante o inválida, o clave API desactivada por el propietario |
403 | Prohibido | Endpoint inactivo o suscripción expirada |
415 | Tipo de medio no soportado | Content-Type debe ser application/json |
429 | Demasiadas solicitudes | Límite de frecuencia mensual excedido |
5xx | Error del servidor | Error interno del servidor (500, 502, 503, etc.) |
5. Webhook del colaborador
Los colaboradores API pueden recibir resultados de procesamiento directamente.
Política de reintentos: Devuelva un 2xx en menos de 15s. Si falla: producción 6 intentos en total durante unas 5 horas, sandbox 4 en total durante unos 12 minutos
6. Herramientas de prueba
Prueba en Sandbox antes de salir en vivo.
- Página de prueba integrada: Accede mediante el botón Probar en la página de detalles del endpoint — sin herramientas adicionales necesarias
- cURL: Prueba desde la línea de comandos
- Postman: Usa la herramienta de prueba de API
7. Consola de producción
Después de desplegar a Producción, el propietario del endpoint puede gestionar los datos de producción directamente desde el panel — sin herramientas API externas ni código.
Cómo acceder
Ve a Detalle del endpoint → pestaña Producción → haz clic en "Abrir consola" para abrir en una nueva pestaña.
Características
- Soporte CRUD completo (POST / GET / PUT / DELETE) en datos de producción
- La clave API de producción se configura automáticamente — no se necesita entrada manual
- Las solicitudes desde la consola no activan webhooks
Solo propietario
Solo el propietario del endpoint puede acceder a la Consola de producción. Los colaboradores no pueden usarla.