Detalles del endpoint

Resumen

Detalles del endpoint es la página que gestiona toda la configuración de un endpoint individual. Desde esta pantalla puede:

• Ver y editar la información del endpoint (nombre, descripción, URL, versión)
• Activar / desactivar
• Desplegar y redesplegar a Producción
• Gestionar la clave API por defecto
• Agregar y eliminar campos obligatorios
• Configurar webhooks
• Eliminar el endpoint

La gestión de claves de colaboración (emisión de claves, invitaciones, permisos) se realiza en una página separada. Consulte Claves de colaboración para más detalles.

Si participa como colaborador, solo se muestran las secciones a las que tiene acceso (las secciones exclusivas del propietario se ocultan automáticamente).

Cómo llegar aquí

• Menú superior APIs → Haga clic en el nombre del endpoint en la lista
• Actividad reciente del panel → Haga clic en el endpoint
• Navegación automática después de completar el Paso 1 del Onboarding

---

Banner de advertencia del plan Free

Se muestra en la parte superior cuando está usando el plan Free. Con el plan Free, puede crear y experimentar con endpoints tanto como desee. Se limpian automáticamente 7 días después de la creación, pero siempre puede crear nuevos — así que no dude en probar.

Botones de Activo/Inactivo y Desplegar

Área exclusiva del propietario.

• Botón Activo/Inactivo (icono de encendido): Úselo cuando quiera pausar temporalmente las llamadas API en todos los entornos. Las llamadas se rechazan mientras está inactivo, pero los datos se conservan.
• Botón Desplegar a producción (solo pestaña Sandbox):
  • Copia la configuración actual de Sandbox a Producción
  • Condición: Debe haber completado al menos 1 llamada de prueba en Sandbox antes de que se active

Si un colaborador accede a la página, aparece un botón Solicitar despliegue en su lugar. Envía un mensaje de solicitud de despliegue al propietario.

Pestañas de entorno

Debajo de la barra del encabezado, hay pestañas de Sandbox | Producción. Los dos entornos son completamente independientes.

El flujo de trabajo recomendado es: Probar en Sandbox y discutir con los colaboradores → Desplegar a Producción → Operar. Cuando se necesiten cambios, modifique primero en Sandbox y redespliegue.

Sandbox

• Entorno para llamadas con claves API de Sandbox (tm_test_)
• Solo para pruebas. Experimente libremente antes de poner en marcha
• Los datos de Sandbox se eliminan automáticamente después de 30 días (todos los planes)

Producción

• Entorno para llamadas con claves API de Producción (tm_live_)
• Para operaciones en vivo. Los registros se conservan al menos 60 días y luego se eliminan por meses completos. Exporte lo que necesite conservar a medida que llega — configure un webhook o consulte la API de listado
• Antes del despliegue a Producción, las llamadas con clave de Producción se rechazan y no se registran

Tarjeta de resumen

Sección que contiene la información básica del endpoint.

Elemento	Descripción
Descripción	Descripción del endpoint. El propietario puede editar en línea en la pestaña Sandbox
URL del endpoint	La dirección real de llamada API. Envíe solicitudes POST/GET/PUT/DELETE a esta URL. Botón de copiar incluido
Versión	Versión de configuración. Se incrementa con cada despliegue
Creado	Hora de creación del endpoint
Actualizado	Hora del último cambio de configuración (Sandbox)
Publicado	Hora del despliegue a Producción (solo pestaña Producción)

Clave API por defecto

Área exclusiva del propietario.

• La clave API por defecto emitida cuando se creó el endpoint
• Se utiliza para la autenticación en la página de Guía de pruebas e integración, accesible mediante el botón Probar ahora a la derecha
• Botón Mostrar / Ocultar para mostrar o esconder la clave en pantalla
• Botón Regenerar: La clave anterior se invalida inmediatamente. Úselo solo cuando sospeche una exposición

Cuando un colaborador accede a la página, esta sección se reemplaza con la tarjeta de su clave de colaboración asignada.

Claves de colaboración

Aquí solo se proporciona una tarjeta de resumen — la creación de claves, invitaciones y gestión de permisos se realizan en una página de gestión separada.

• Vista del propietario: Botón Ver todo y resumen por colaborador (nombre, cantidad de invitaciones)
• Vista del colaborador: Badges de permisos para la clave asignada

Consulte Claves de colaboración para instrucciones detalladas.

Campos obligatorios

Defina los campos JSON que deben incluirse en las llamadas API. Para una explicación detallada, consulte Crear nuevo endpoint.

• Para agregar o editar campos, haga clic en el botón Editar
• Mientras edita, puede agregar, eliminar y cambiar tipos de campo. Finalice con Guardar o Cancelar
• Al guardar se actualiza la configuración de Sandbox — para aplicar a Producción, necesita redesplegar
• Incluso después del despliegue, modificar los campos obligatorios no afecta los datos ya almacenados. Las reglas de campo actualizadas se aplican solo a las nuevas llamadas entrantes

Webhooks

Área exclusiva del propietario.

Cuando una llamada API se procesa correctamente, se puede enviar una solicitud secundaria a la URL de webhook especificada. El almacenamiento de datos siempre se completa independientemente del éxito del webhook.

Campos de entrada

• URL del webhook: Dirección para recibir webhooks (se recomienda HTTPS)
• Encabezado de autenticación (opcional): Clave del encabezado de autenticación. Por defecto Authorization
• Valor de autenticación (opcional): Valor del encabezado de autenticación. Ejemplo: Bearer abc123

Para webhooks que no requieren autenticación (receptores simples, tokens embebidos en la URL, etc.), deje los campos de autenticación vacíos.

Resumen de la política de webhooks

• Tiempo de espera: Debe responder en 15 segundos. Se trata como fallo si se excede
• Código de respuesta: Un 2xx significa "lo he recibido", no "ha funcionado". Devuelva 2xx incluso cuando su propio procesamiento falle y registre ese fallo en su propio sistema. Un 5xx nos indica que la entrega nunca llegó, así que reenviamos el mismo registro según el calendario de reintentos de abajo y su receptor ejecuta el mismo trabajo cada vez
• Reintento: Producción son 6 intentos en total — la primera entrega más 5 reintentos a 30s, 2m, 10m, 1h, 4h (unas 5 horas). Sandbox son 4 intentos en total — la primera entrega más 3 reintentos a 30s, 2m, 10m (unos 12 minutos)
• Con reintento: 5xx, 429, tiempos de espera agotados y errores de conexión. Un Retry-After en un 429 hace que esperemos más, nunca menos que el intervalo predeterminado
• Sin reintento: Cualquier 4xx distinto de 429, incluido el 409. Corrija la configuración y la siguiente llamada se entregará
• Comprobar los fallos: Las entregas fallidas o en curso aparecen en Entrega de webhook, en la pantalla de registros. Las entregas correctas no se registran
• Aviso por correo: Cuando damos por perdida una entrega (reintentos agotados o respuesta permanente) le enviamos un correo en todos los planes, incluido el gratuito, pero solo en producción: como máximo un mensaje por endpoint y día, sin aviso de recuperación. Los fallos del webhook del colaborador no se notifican por correo, ya que usted no puede cambiar esa URL
• Idempotencia: Cada intento lleva el mismo X-3minapi-Record-Id. Úselo para detectar duplicados
• Firma: cada solicitud lleva una firma HMAC-SHA256 (webhook-signature). Consulte Secreto de firma del webhook más abajo para los detalles

Secreto de firma del webhook

Está justo debajo de la tarjeta de configuración del webhook. No es un área exclusiva del propietario: los colaboradores también pueden verla, porque un webhook que un colaborador recibe en su propia URL de X-Webhook-Callback se firma con el mismo secreto.

• Es distinto por entorno — la pestaña Sandbox y la pestaña Producción tienen secretos independientes. Use el del entorno en el que está recibiendo
• Tanto el propietario como los colaboradores pueden consultarlo
• Solo el propietario puede volver a emitirlo (rotarlo). El botón de reemisión no aparece en la pantalla de un colaborador
• No es un valor que deba rotarse periódicamente. La reemisión es lo que se hace cuando un secreto se ha filtrado
• Tras una reemisión, durante 24 horas se envían tanto la firma nueva como la anterior. Cambie el valor en su servidor receptor en cualquier momento de esa ventana y no perderá ninguna entrega. Durante el periodo de gracia la tarjeta muestra un aviso con la hora de vencimiento

Para saber qué hacer realmente con este valor, consulte Verificar la firma del webhook.

Payload del webhook

Cuando se procesa una llamada API, se envía el siguiente payload JSON a la URL del webhook. Puede ver el formato real expandiendo la sección Ejemplo de payload del webhook en la captura de pantalla.

Campo	Descripción
id	ID único del registro almacenado
operation	Acción realizada (create, update, delete)
status	Resultado del procesamiento (success, failed)
endpoint_slug	Identificador del endpoint
payload	Los datos JSON originales enviados por el llamante, incluidos tal cual (null para delete)
target_record_id	ID del registro objetivo (incluido para update/delete)
processed_at	Hora de finalización del procesamiento

Webhooks de colaborador

Si los colaboradores necesitan webhooks, pueden configurar los suyos incluyendo X-Webhook-Callback y otros encabezados en su solicitud API. Los webhooks de colaborador operan independientemente de los webhooks del propietario, y el formato del payload es idéntico. Consulte Guía de pruebas e integración para instrucciones detalladas de configuración.

Los webhooks de colaborador reciben la misma política de reintentos y la misma firma que los del propietario. El secreto para verificarlos está en la tarjeta Secreto de firma del webhook de más arriba.

Zona de peligro

Área exclusiva del propietario.

• Botón Eliminar endpoint
• La eliminación remueve inmediata y permanentemente:
  • La propia configuración del endpoint
  • Todos los registros API en Sandbox y Producción
  • Estadísticas relacionadas / solicitudes de despliegue / webhooks / claves de colaboración
• Los colaboradores también pierden el acceso
• No se puede deshacer — debe escribir el nombre del endpoint en el diálogo de confirmación para proceder

Barra lateral derecha

El lado derecho de la página de detalles muestra diferentes tarjetas rápidas dependiendo del entorno.

Registros de llamadas API

Navegue a una página donde puede ver los resultados de las llamadas API a este endpoint. Puede consultar éxito/fallo de las solicitudes, payloads, estado del webhook y más en detalle.

Prueba de Sandbox

Se muestra en la pestaña Sandbox.

Navegue a una página donde puede probar llamadas API directamente en el navegador y consultar métodos de integración. Consulte Guía de pruebas e integración para más detalles.

Consola de Producción

Se muestra en la pestaña Producción, después del despliegue, solo para el propietario.

Una consola para gestionar datos de Producción directamente desde el panel. Útil para precargar listados de productos o anuncios que los colaboradores recuperarán mediante GET. Soporta POST (crear), GET (leer), PUT (actualizar) y DELETE (eliminar). La consola se ejecuta con la clave API del propietario, y los webhooks de colaborador no se activan. Si el webhook del propietario está configurado, se activa normalmente. Consulte Consola de Producción para más detalles.

Notificación de solicitud de despliegue

Se muestra en la pestaña Sandbox.

Se muestra cuando un colaborador ha solicitado el despliegue a Producción. Esta notificación también se envía por correo electrónico, así que no se la perderá. Haga clic en el botón Ver historial completo para ver el historial completo de solicitudes de despliegue.

---

Solución de problemas

• El botón de desplegar está deshabilitado: O no se han realizado llamadas de prueba en Sandbox, o la última versión de Sandbox ya está desplegada en Producción. Ejecute una prueba en Sandbox primero
• La pestaña de Producción no tiene registros: Las llamadas de Producción se rechazan hasta el despliegue, por lo que no se registran. Verifique si el despliegue fue exitoso y si se están usando claves tm_live_
• Los campos obligatorios se cambiaron pero no se reflejan en Producción: Los cambios de Sandbox no se aplican automáticamente a Producción. Haga clic en Desplegar a producción de nuevo
• El webhook no llega: Los servidores de webhook deben responder en 15 segundos. Verifique que el servidor sea públicamente accesible y use HTTPS. Plataformas como Discord y Slack tienen sus propios límites de velocidad — si se disparan demasiados webhooks en poco tiempo, algunos pueden ser bloqueados. Consulte también la política de límites de velocidad de la plataforma receptora