Conceptos clave

Una mirada más profunda a los términos introducidos en el Inicio rápido.

1. API

Un protocolo de comunicación para intercambiar datos entre programas.

En 3Min API:

• Crea APIs sin código backend
• Recibe datos JSON estándar
• Los datos se almacenan automáticamente y se pueden reenviar vía webhooks

2. Endpoint

La dirección API que recibe datos. Una API = un endpoint.

Cada endpoint incluye:

• Ruta URL única (generada automáticamente)
• Campos obligatorios (opcional)
• Separación de entornos Sandbox/Producción
• Claves API específicas por entorno (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min API acepta datos JSON estándar.

Tipos de campo soportados:

Ejemplo (información de pedido):

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. Campos obligatorios (opcional)

Puedes especificar campos que deben incluirse en los datos JSON.

Con campos obligatorios:

• Las solicitudes sin campos obligatorios se rechazan (error 400)
• Asegura la calidad de los datos

5. Sandbox vs Producción

• El entorno se determina por el prefijo de la clave API
• Los webhooks se pueden configurar por separado para cada entorno
• Prueba a fondo en Sandbox antes de desplegar a Producción

6. Clave API

Se usa para autenticación al llamar endpoints. La clave API predeterminada del propietario se genera automáticamente al crear el endpoint y no se puede eliminar. Si la clave se compromete, se puede regenerar.

Claves de colaboración

Crea claves de colaboración e invita colaboradores para gestionar registros y estadísticas por separado por clave de colaboración.

Filtra registros por clave de colaboración para rastrear el uso por clave.

Establece las operaciones permitidas (POST/GET/PUT/DELETE) por clave de colaboración, de forma independiente para cada entorno. El permiso de lectura (GET) cubre el GET individual, GET (lista) y GET (búsqueda) por igual.

7. Webhooks

Notificaciones automáticas enviadas a una URL especificada cuando llegan datos.

Dos tipos de webhooks:

Política de reintentos: devuelva un 2xx en menos de 15s. Si falla, la entrega se reintenta desde una cola durante horas

Nota: incluso si todos los reintentos del webhook fallan, tus datos siguen almacenados de forma segura. Verifica el estado del webhook en los registros.

8. Sondeo

La otra forma de recibir datos. En lugar de que nosotros llamemos a su URL, su cliente llama al endpoint de sondeo en bucle y recibe solo lo que ha llegado desde su última llamada.

Webhook o sondeo:

Elija webhook cuando el receptor tenga una URL pública y deba reaccionar en cuanto lleguen los datos. Es la opción por defecto.

Elija sondeo cuando no haya URL pública — desarrollo local, una red interna, detrás de un cortafuegos, sin servidor permanente — o cuando el receptor necesite controlar su propio ritmo.

No son excluyentes. Ambos pueden estar activos en el mismo endpoint: un webhook para reaccionar en tiempo real y un sondeo nocturno que recupere lo que el receptor se perdió.

Ejemplo de solicitud:

# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx

# Response - oldest first
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "limit": 100,
    "poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
  }
}

# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ

Cómo funciona el cursor:

• La primera llamada acepta since (RFC 3339 o YYYY-MM-DD, siempre en UTC) o nada en absoluto, lo que equivale a suscribirse desde ese momento. since y cursor no pueden enviarse juntos.
• next_cursor significa que queda trabajo pendiente — vuelva a llamar de inmediato
• poll_cursor significa que está al día — guárdelo y espere al siguiente ciclo
• Los registros llegan del más antiguo al más reciente, hasta 100 por página (limit, 1-100). Cada respuesta trae exactamente uno de los dos cursores

9. Tareas

Las tareas permiten que una IA como ChatGPT o Claude envíe un trabajo a tu propio servidor HTTP (un worker) y traiga el resultado de vuelta a la conversación. 3Min API solo entrega la tarea y registra su estado; el trabajo lo hace el worker.

Cómo se ejecuta una tarea:

1. La IA llama a task_create con el nombre de un worker y un input. La tarea empieza en working
2. 3Min API envía un POST firmado a la URL del worker, que incluye un callback_url
3. El worker responde 2xx de inmediato —significa "recibido", no un resultado— y luego hace el trabajo
4. Al terminar, el worker informa completed o failed al callback_url. Los mensajes de progreso previos son opcionales
5. La IA llama a task_get y muestra el resultado en la conversación

Webhook o tarea:

Conviene saber:

• Un worker público necesita una URL pública. El código en tu propio PC se ejecuta como worker local con la CLI de 3Min API, sin URL pública
• Una tarea que no termina en 24 horas pasa a failed
• La entrega es at-least-once: la misma tarea puede llegar dos veces, así que elimina duplicados por el ID de la tarea
• Registrar un worker y ver o rotar sus secretos solo se hace en el panel web. La IA nunca ve la URL ni los secretos

Contrato del worker, verificación de firma y código de ejemplo: guía de tareas

10. Retención de datos

Los registros se conservan durante un tiempo limitado. Considere el webhook o el endpoint de sondeo — no el panel — como la vía por la que sus datos salen de 3Min API.

Política por entorno:

Cómo sacar sus datos:

• Webhook: cada registro se envía a su URL en cuanto llega
• Sondeo: recupere lo que haya llegado desde su última llamada — véase la sección 8 más arriba
• Registros: mientras se conservan, puede consultarlos o buscarlos en el panel
• Las estadísticas de uso se guardan aparte y sobreviven al borrado de registros, así que sus gráficas siguen intactas