Guía de pruebas e integración

Resumen

Esta es la página que se abre al hacer clic en Probar ahora en la página de detalles del endpoint. Puede probar llamadas API directamente en el navegador sin herramientas adicionales, y compartirla con los colaboradores para que encuentren todo lo necesario para la integración en un solo lugar.

Las pruebas en esta página se realizan solo en el entorno Sandbox. No afectan los datos de Producción, así que puede experimentar libremente.

La página tiene dos pestañas:

• Inicio rápido — Autentíquese con una clave API y pruebe llamadas de inmediato
• Guía — Referencia de integración para propietarios y colaboradores (guía paso a paso, endpoints API, encabezados, definiciones de campos, ejemplos de código, etc.)

Cómo llegar aquí

• Detalles del endpoint barra lateral derecha > botón Probar ahora (pestaña Sandbox)
• Los colaboradores también pueden acceder desde su propio panel después de aceptar la invitación

---

Información del endpoint

• Se muestran el nombre y la descripción del endpoint
• Badge de entorno (Sandbox) e información de versión junto a él
• Cambie entre las pestañas Inicio rápido / Guía

Pestaña Inicio rápido

Autenticación

Para comenzar a probar, primero necesita autenticarse con una clave API.

• Pegue una clave de Sandbox (que comienza con tm_test_) en el campo de entrada y haga clic en Autorizar
• Se pueden usar dos tipos de claves:
  • Clave API por defecto — Cuando el propietario prueba directamente
  • Clave de colaboración — Cuando un colaborador prueba con su propia clave

Una vez autenticado, el campo de entrada desaparece y aparece un botón Cerrar sesión. Para probar con una clave diferente, cierre sesión y autentíquese de nuevo.

Probar

Después de la autenticación, se activa el área de ejecución de llamadas CRUD. Seleccione un método, ingrese el cuerpo de la solicitud (JSON) y haga clic en Execute para ver los resultados de inmediato.

Si quiere probar el flujo completo de una vez, siga este orden:

Guía completa de prueba CRUD

1. CREATE (POST) — Ingrese JSON de prueba en el cuerpo de la solicitud y ejecute. Copie el id de la respuesta — lo necesitará para los siguientes pasos.

2. READ — Registro individual (GET) — Pegue el id en el campo de Record ID y ejecute. Se devuelve el payload completo de ese registro.

3. READ — Lista (GET list) — Llame a GET sin Record ID para recibir los registros recientes en orden cronológico inverso. Use limit (1–30, predeterminado 10) y cursor para paginación — pase pagination.next_cursor de la respuesta como cursor de la siguiente llamada para obtener la página siguiente.

4. READ — Búsqueda (GET search) — Encuentre registros por una palabra clave dentro del payload. Use q (obligatorio, 3–200 caracteres) más start/end opcionales (por defecto últimos 30 días), limit y cursor. La coincidencia es por subcadena sin distinguir mayúsculas, con paginación por cursor.

5. READ — Sondeo (GET poll) — Obtenga los registros creados desde su último sondeo, del más antiguo al más reciente. La primera llamada no necesita nada (se suscribe desde ahora) o usa since; todas las siguientes devuelven el cursor de la respuesta anterior. next_cursor significa que queda pendiente — vuelva a llamar de inmediato. poll_cursor significa que está al día — guárdelo y espere al siguiente ciclo.

6. UPDATE (PUT) — Ingrese el mismo id y proporcione JSON modificado en el cuerpo de la solicitud. Es un reemplazo completo, así que incluya los campos que quiera conservar además de los que está cambiando.

7. DELETE — Ingrese el mismo id y ejecute. Intente READ de nuevo después para confirmar que el registro ha sido eliminado.

Verificación de permisos: Al probar con una clave de colaboración, solo se pueden ejecutar los métodos permitidos por los permisos de esa clave. Llamar a un método no autorizado devuelve un error 403. Consulte los permisos en Claves de colaboración > Permisos.

Webhook de colaborador

En la parte inferior de la sección Probar, hay un área colapsable de configuración de webhook. Esto es separado del webhook que configura el propietario en el panel — es para que el llamante de la API incluya información de webhook en los encabezados de la solicitud y reciba los resultados del procesamiento en su URL especificada. Puede probar estos encabezados aquí.

• Opera independientemente del webhook del propietario
• En la integración real, los encabezados del webhook se incluyen directamente en el código de su llamada API
• Consulte la sección Configuración de webhooks de la pestaña Guía para nombres detallados de encabezados e implementación

Pestaña Guía

La pestaña Guía está estructurada para que tanto propietarios como colaboradores puedan revisar el flujo completo de integración y los detalles técnicos en un solo lugar. Las guías de pasos específicas por rol están en la parte superior, seguidas de la referencia técnica.

Primeros pasos — Propietario

Seleccione la pestaña ¿Creó usted un endpoint? para ver los pasos desde la perspectiva del propietario.

1. Crear endpoint — Solo establezca un nombre de API y el CRUD se crea automáticamente. La descripción y los campos obligatorios se pueden agregar después
2. Prueba de Sandbox y verificación de registros — Haga una llamada con la clave API por defecto en la pestaña Inicio rápido, luego verifique la recepción de datos en los registros del panel
3. Crear clave de colaboración e invitar — Cree una clave y envíe invitaciones por correo desde la página de detalles
4. Prueba de integración — Verifique junto con el colaborador que las llamadas se realizan correctamente en Sandbox mediante los registros
5. Despliegue a Producción — Apruebe la solicitud de despliegue del colaborador, o despliegue directamente. Los colaboradores son notificados después del despliegue

Primeros pasos — Colaborador

Seleccione la pestaña ¿Fue usted invitado? para ver los pasos desde la perspectiva del colaborador.

1. Aceptar invitación — Consulte el correo de invitación y acepte en el panel después de iniciar sesión
2. Consultar clave API — Encuentre su clave API de Sandbox (tm_test_) en la página de detalles del endpoint
3. Integración y pruebas — Pruebe llamadas en la pestaña Inicio rápido, y consulte la información técnica de la pestaña Guía para desarrollar su integración. Si recibe una respuesta 202, el procesamiento está garantizado por el sistema
4. Solicitar despliegue — Cuando las pruebas estén completas, envíe una solicitud de despliegue desde la página de detalles del endpoint
5. Cambiar a Producción — Una vez que el propietario complete el despliegue, será notificado. Consulte y aplique la clave API de Producción (tm_live_) desde la pestaña Producción

Endpoints API

Muestra las rutas y métodos API disponibles para este endpoint. Los siguientes métodos se preparan automáticamente cuando se crea un endpoint.

Método	Ruta	Descripción
POST	/api/v1/data/{slug}	Crear un nuevo registro
GET	/api/v1/data/{slug}/{record_id}	Recuperar un registro por ID
GET	/api/v1/data/{slug}	Listar registros recientes (paginación cursor)
GET	/api/v1/data/{slug}/search	Buscar registros por texto del payload (q, start/end opcionales; mínimo 3 caracteres, 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 (since o cursor, paginación por cursor)
PUT	/api/v1/data/{slug}/{record_id}	Reemplazar un registro
DELETE	/api/v1/data/{slug}/{record_id}	Eliminar un registro

{slug} es un identificador único asignado automáticamente cuando se crea el endpoint. Puede ver el valor real en esta página.

La llamada de búsqueda (search) requiere q (3–200 caracteres). start y end (YYYY-MM-DD o RFC 3339) son opcionales — cuando se omiten, se usan los últimos 30 días. No hay límite superior en el rango. Los resultados se paginan por cursor (pagination.next_cursor aparece cuando hay más páginas). La coincidencia es por subcadena sin distinguir mayúsculas en todo el payload, por lo que pueden aparecer falsos positivos numéricos o de claves JSON (p. ej. buscar 32 también coincide con 132). La búsqueda usa el mismo permiso read que el GET individual y el GET de lista.

La llamada de sondeo (poll) recorre los registros en orden ascendente de created_at — lo contrario que lista y búsqueda. No envíe ningún parámetro para suscribirse desde ahora, use since (YYYY-MM-DD o RFC 3339, siempre UTC — 2026-08-28 es medianoche UTC, no local) para empezar desde un instante, o cursor para continuar; enviar since y cursor a la vez devuelve 400. limit es 1–100 (predeterminado 100) y no viaja dentro del cursor, así que reenvíelo en cada página. Cada respuesta lleva exactamente uno de los dos cursores: next_cursor significa que queda pendiente — vuelva a llamar de inmediato; poll_cursor significa que está al día — guárdelo y espere al siguiente ciclo. Los ~60 segundos más recientes se retienen, porque created_at lo emite el gateway mientras la fila se inserta de forma asíncrona a través de la cola — sin ese margen la marca de agua avanzaría por delante de registros aún en tránsito. Esos registros llegan en un sondeo posterior: aplazados, no perdidos. Los reintentos y reinicios pueden reenviar un registro, así que procese de forma idempotente por el id del registro. El sondeo usa el mismo permiso read que el GET individual, el GET de lista y el GET de búsqueda.

Claves API

Información clave para la autenticación al realizar llamadas API.

Entorno	Prefijo de clave	Uso
Sandbox	tm_test_	Desarrollo y pruebas
Producción	tm_live_	Servicio en vivo

Las claves API de Producción se pueden encontrar en la página de detalles del endpoint después de que se complete el despliegue. Antes del despliegue, las llamadas con claves de Producción se rechazan.

Encabezados de solicitud

Encabezados HTTP para incluir en las llamadas API. Content-Type y Authorization son obligatorios; los encabezados de webhook solo se agregan cuando es necesario.

Encabezado	Obligatorio	Descripción
Content-Type	Obligatorio	application/json (para POST/PUT)
Authorization	Obligatorio	Formato Bearer {API_KEY}
X-Webhook-Callback	Opcional	URL para recibir el webhook del llamante
X-Webhook-Auth	Opcional	Valor de autenticación del webhook (ej., Bearer token)
X-Webhook-Auth-Header	Opcional	Clave del encabezado de autenticación del webhook (por defecto: Authorization)

Cuerpo de la solicitud

Información sobre el cuerpo JSON enviado con las solicitudes POST/PUT.

• Formato: JSON (application/json) · Máx. 100KB · UTF-8
• Si el propietario ha definido campos obligatorios, esos campos deben incluirse. Campos adicionales más allá de los obligatorios se pueden enviar libremente
• Si no se definen campos obligatorios, se acepta cualquier JSON
• Las solicitudes se procesan de forma asíncrona. Recibe una respuesta 202 inmediatamente, y el almacenamiento real y la entrega de webhooks ocurren en segundo plano

Formato de respuesta

Muestra las respuestas exitosas y los códigos de error para cada método.

Respuestas exitosas:

• POST/PUT/DELETE → 202 Accepted (solicitud aceptada y en cola)
• GET (individual) → 200 OK (registro devuelto inmediatamente)
• GET (lista) → 200 OK (datos paginados + next_cursor cuando hay más páginas)
• GET (búsqueda) → 200 OK (datos paginados + next_cursor cuando hay más páginas)
• GET (sondeo) → 200 OK (datos del más antiguo al más reciente + exactamente uno de next_cursor / poll_cursor)

Códigos de error:

Código	Estado	Significado
400	Bad Request	JSON inválido, campos obligatorios faltantes, ID de registro inválido
401	Unauthorized	Clave API faltante o inválida
403	Forbidden	Endpoint inactivo, sin suscripción, o permisos insuficientes
415	Unsupported Media Type	Content-Type no es application/json
429	Too Many Requests	Límite de uso mensual excedido
5xx	Server Error	Error temporal del servidor — implemente lógica de reintento

Si recibe un error 5xx, la solicitud no llegó al servidor. Implemente lógica de reintento en su código (ej., backoff de 1s → 2s → 4s). Si recibe una respuesta 202, el procesamiento está garantizado por el sistema.

Configuración de webhooks

Instrucciones para configurar webhooks del llamante para recibir automáticamente los resultados del procesamiento. Esto opera de forma separada e independiente del webhook del propietario en el panel.

Cómo configurar: Incluya los siguientes encabezados en su llamada API.

Encabezado	Obligatorio	Descripción
X-Webhook-Callback	Obligatorio	URL para recibir webhooks
X-Webhook-Auth	Opcional	Valor de autenticación (ej., Bearer token)
X-Webhook-Auth-Header	Opcional	Clave del encabezado de autenticación (por defecto: Authorization)

Encabezados que enviamos con cada webhook:

Encabezado	Descripción
X-3minapi-Record-Id	ID del registro. Idéntico en todos los intentos de entrega: úselo para detectar duplicados
X-3minapi-Delivery-Attempt	Número de intento, comenzando en 1
webhook-id	ID del registro: el mismo valor que X-3minapi-Record-Id
webhook-timestamp	Cuándo firmamos (segundos unix). Se regenera en cada intento
webhook-signature	Firma HMAC-SHA256. Llegan dos mientras se reemplaza un secreto

Requisitos del receptor:

• Devuelva un 2xx en menos de 15 segundos. Delegue el trabajo pesado a su propia cola y responda de inmediato
• Un 2xx significa "lo he recibido", no "ha funcionado". Devuelva 2xx incluso cuando su propio procesamiento falle — una llamada rechazada aguas arriba, un error de validación de su lado, un pedido que no puede atender — y registre ese fallo en su propio sistema. Reserve el 5xx para lo que realmente significa: su receptor, o algo de lo que depende, está caído temporalmente y una entrega posterior del mismo registro podría funcionar. Un 5xx hace que reenviemos ese registro según el calendario de reintentos de abajo, así que su receptor ejecuta el mismo trabajo cada vez
• El mismo X-3minapi-Record-Id puede llegar más de una vez. Úselo para decidir si ya procesó el registro

Política de reintentos:

• Criterio de éxito: cualquier código de estado 2xx — solo confirma que se recibió la entrega, no que su procesamiento funcionara
• Producción: 6 intentos en total — la primera entrega más 5 reintentos a 30s, 2m, 10m, 1h, 4h (unas 5 horas). Sandbox: 4 intentos en total — la primera entrega más 3 reintentos a 30s, 2m, 10m (unos 12 minutos)
• Se reintenta: 5xx (excepto 501/505), 429, tiempos de espera agotados, errores de conexión. Un Retry-After en un 429 se respeta solo como una petición de esperar más: nunca acorta el intervalo predeterminado y los valores superiores a 4 horas se ignoran
• No se reintenta: cualquier 4xx distinto de 429, incluido el 409, que interpretamos como "el receptor ya lo tiene". Corrija la configuración y la siguiente llamada se entregará
• Incluso si todos los intentos fallan, los datos se almacenan de forma segura: dentro de la ventana de retención (producción al menos 60 días, sandbox 30) puede recuperarlos más tarde con el endpoint de sondeo. Las entregas fallidas o en curso aparecen en Entrega de webhook, en la pantalla de registros, incluido el cuerpo de la respuesta y cada intento
• Cuando damos por perdida una entrega (reintentos agotados, o una respuesta permanente que no se reintenta), enviamos un correo al propietario del endpoint, en todos los planes, incluido el gratuito, pero solo en producción y solo para el webhook del propietario, como máximo un mensaje por endpoint y día. No hay seguimiento ni aviso de recuperación. Los fallos del webhook del colaborador nunca se notifican por correo, porque el propietario del endpoint no puede cambiar esa URL

Verificar la firma del webhook

Cada webhook que enviamos lleva una firma HMAC-SHA256, de modo que puedes confirmar que la solicitud provino realmente de 3Min API y que no se alteró por el camino.

La verificación es opcional: si ya recibes webhooks, seguirán funcionando sin cambios. Activarla te protege de que alguien que descubrió tu URL de recepción envíe solicitudes falsas y consiga que tu servidor descarte una entrega genuina como "ya procesada".

Esto no es cifrado. El cuerpo sigue viajando en texto plano, exactamente como antes. Lo que cambia es que se adjunta en una cabecera una huella que demuestra que "este cuerpo no ha cambiado ni un carácter desde que salió de 3Min API".

La huella se construye uniendo tres piezas.

contenido firmado = "{webhook-id}.{webhook-timestamp}.{cuerpo original de la solicitud}"
clave             = el secreto sin el prefijo whsec_, decodificado en base64
firma             = base64( HMAC-SHA256(clave, contenido firmado) )

Cada pieza bloquea algo distinto.

Pieza	Qué bloquea
Cuerpo de la solicitud	Sustituir el contenido por el camino
webhook-timestamp	Reenviar tal cual una solicitud genuina capturada antes (repetición)
webhook-id	Adjuntar el id de registro de otro para que descarte una entrega real como "ya procesada"

Dónde está el secreto: Panel > detalle del endpoint > Secreto de firma del webhook. Sandbox y producción tienen secretos distintos.

Verificar con una biblioteca (recomendado)

Seguimos la especificación Standard Webhooks al pie de la letra, así que una biblioteca oficial reduce esto a unas pocas líneas.

Lenguaje	Paquete
Node.js / TypeScript	standardwebhooks (npm)
Python	standardwebhooks (pip)
PHP	standard-webhooks/standard-webhooks (composer)
Go	github.com/standard-webhooks/standard-webhooks/libraries/go
Ruby	standardwebhooks (gem)
Java / Kotlin	com.standardwebhooks:standardwebhooks
C#	StandardWebhooks (NuGet)
Rust	standardwebhooks (crates.io)
Elixir	standard_webhooks (hex)

// npm i standardwebhooks
import { Webhook } from 'standardwebhooks';
import express from 'express';

const app = express();
// 서명은 우리가 보낸 바이트 그대로에 대해 계산됩니다.
// JSON으로 파싱한 뒤 다시 문자열로 만들면 반드시 실패합니다.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
	const wh = new Webhook(process.env.WEBHOOK_SIGNING_SECRET.replace('whsec_', ''));
	try {
		const payload = wh.verify(req.body, {
			'webhook-id': req.header('webhook-id'),
			'webhook-timestamp': req.header('webhook-timestamp'),
			'webhook-signature': req.header('webhook-signature')
		});
		// 검증 통과 — payload를 처리하세요
		res.sendStatus(200);
	} catch {
		res.sendStatus(401);
	}
});

Si lo implementas por tu cuenta

1. Quita el prefijo whsec_ del secreto y decodifica en base64 el resto para obtener los bytes de la clave
2. Comprueba que webhook-timestamp esté dentro de ±5 minutos respecto a ahora (bloquea solicitudes reenviadas)
3. Calcula base64(HMAC_SHA256(clave, "{webhook-id}.{webhook-timestamp}.{cuerpo sin procesar}"))
4. Divide webhook-signature por espacios y acepta si coincide alguna entrada que empiece por v1,

Ten en cuenta

• Firma los bytes originales. Analizar el JSON y volver a serializarlo cambia el orden de las claves y los espacios, y entonces la verificación falla siempre. Usa express.raw en Express, request.get_data() en Flask, file_get_contents('php://input') en PHP
• Puede haber más de una firma. Llegan dos mientras se reemplaza un secreto, así que rechazar tras comprobar solo la primera rechazaría todo durante el cambio
• Ignora las entradas que no sean v1,. Así tu código sigue funcionando si más adelante se añade otra versión
• No compares con ==. Usa una comparación de tiempo constante: crypto.timingSafeEqual (Node), hmac.compare_digest (Python), hash_equals (PHP)

Reemplazar el secreto

Solo el propietario del endpoint puede volver a emitir un secreto, y es lo que se hace cuando uno se ha filtrado: no es un valor que deba rotarse periódicamente. Durante las 24 horas siguientes se envían la firma nueva y la anterior, así que puedes actualizar tu servidor receptor en cualquier momento de ese plazo sin perder ninguna entrega. Pasadas las 24 horas solo se envía la nueva.

Si recibes webhooks como colaborador, también puedes consultar el secreto: tu webhook se firma con el mismo. Solo la reemisión es exclusiva del propietario.

Ejemplos de código

Se proporcionan ejemplos de código de llamadas API en los principales lenguajes incluyendo curl, JavaScript y Python. Cambie de pestaña para ver ejemplos en cada lenguaje. La URL real del endpoint y los encabezados requeridos ya están prellenados, por lo que puede copiarlos y usarlos de inmediato.

---

Pestaña API Reference

Una pestaña que presenta la especificación de este endpoint en formato estilo OpenAPI de un vistazo. Cada tarjeta de método incluye la URL de solicitud, los encabezados, los parámetros de ruta/consulta, el esquema del cuerpo de solicitud y ejemplos de respuesta — para que pueda comprender la especificación de integración solo desde esta página, sin herramientas externas.

• Si la pestaña Inicio rápido sirve para "llamar y verificar directamente", la pestaña API Reference sirve para "leer la especificación y escribir código de integración"
• POST / GET (individual) / GET (lista) / GET (búsqueda) / GET (sondeo) / PUT / DELETE están separados en tarjetas, lo que facilita comparar las diferencias de un vistazo
• Los ejemplos de respuesta usan la misma estructura JSON que las respuestas reales — puede usarlos directamente en las definiciones de tipo de su cliente

---

Solución de problemas

• No pasa nada al hacer clic en Autorizar: Verifique que la clave API comience con tm_test_ (clave de Sandbox). Las claves de Producción (tm_live_) no se pueden usar en esta página
• Perdí el ID después de CREATE: Ejecute CREATE de nuevo para generar un nuevo registro y continúe probando. Si necesita el ID del registro anterior, consulte el historial de llamadas en la página de Registros del panel
• Obtengo errores 403: La clave de colaboración que está usando puede no tener permiso para ese método. Consulte en Claves de colaboración > Permisos
• El webhook no llega: El servidor de webhook debe responder en 15 segundos. Verifique que sea públicamente accesible y use HTTPS. Plataformas como Discord y Slack tienen límites de velocidad — si se disparan demasiados webhooks en poco tiempo, algunos pueden ser bloqueados