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.

POST GET (list)
https://api.3minapi.com/api/v1/data/{slug}
GET (search)
https://api.3minapi.com/api/v1/data/{slug}/search
GET (poll)
https://api.3minapi.com/api/v1/data/{slug}/poll
GET / PUT / DELETE
https://api.3minapi.com/api/v1/data/{slug}/{record_id}

2. Autenticación

Incluye tu clave API en el encabezado.

EncabezadoDescripciónObligatorio
AuthorizationBearer tm_test_xxx... / Bearer tm_live_xxx...Yes
Content-Typeapplication/jsonYes
X-Webhook-CallbackURL del webhookNo
X-Webhook-AuthValor de autenticación (ej., token Bearer)No
X-Webhook-Auth-HeaderNombre del encabezado de autenticaciónNo

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étodoRutaDescripció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}/searchBuscar 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}/pollObtener 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:

CodeStatusDescription
400Solicitud incorrectaJSON inválido o campos obligatorios faltantes
401No autorizadoClave API faltante o inválida, o clave API desactivada por el propietario
403ProhibidoEndpoint inactivo o suscripción expirada
415Tipo de medio no soportadoContent-Type debe ser application/json
429Demasiadas solicitudesLímite de frecuencia mensual excedido
5xxError del servidorError 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.