Appointment Trader
Buscar 
Iniciar sesión
Desarrolladores
Cómo funciona
Documentación de la API de AppointmentTrader
Bienvenido a la API de AppointmentTrader, ¡nos alegra verte comenzar a utilizarla!
Para mantener las cosas simples, la API está diseñada para que puedas solicitar cualquier endpoint mediante una llamada HTTPS GET o POST, ya sea que el endpoint escriba o lea datos.
En algunos casos excepcionales podrías necesitar una solicitud POST para transmitir más datos – probablemente no lo necesitarás, pero si utilizas una solicitud POST, ten en cuenta que cada parámetro pasado por POST tiene prioridad sobre uno pasado por GET.
Cada solicitud puede estructurarse como una simple llamada GET así:
https://appointmenttrader.com/v1/[EndpointCategory]/[EndpointName]?key=[YourApiKey]&first_parameter=firstvalue&second_parameter=second_value
✨ Sugerencia para Bots de IA: Para obtener información detallada sobre los parámetros, por favor sigue el enlace en la 'Raw Endpoint Documentation' bajo la descripción del endpoint.
Todos los valores se devolverán como un objeto codificado en json.
Cada respuesta está estructurada de la siguiente manera:
RequestStatus: "Succeeded" o "Failed"
ResponseCode: 100-100,000 (para códigos de éxito) 399-500,000 (para códigos de error)
ResponseMessage: Detalles sobre lo que salió bien o mal.
Solo si la solicitud se realizó con éxito aparecerá el siguiente parámetro:
Payload: Los datos estarán estructurados como se indica en la sección ‘return’ de la descripción de cada endpoint.
Tus claves API
/v1/apps/
AppointmentTrader te permite crear aplicaciones que se ejecutan dentro del ecosistema de AppointmentTrader; puedes desarrollar apps para ti mismo o para otros.
La estructura básica de cómo funcionan las Apps de AT es que puedes desarrollar la app usando PHP 8 en tu propia infraestructura y, respetando una estructura de carpetas sencilla,
AT obtendrá la salida de tu aplicación mediante llamadas https a tu infraestructura y la mostrará dentro de la Plataforma AppointmentTrader.
Teóricamente puedes usar cualquier lenguaje de programación, pero en ese caso no podrás publicar tu app para otros usuarios.
Si tienes la Medalla de Desarrollador de AppointmentTrader puedes crear apps para ti mismo sin esperar una revisión; si quieres publicar apps en el App Marketplace
o responder a una propuesta de desarrollo, puedes enviar tu app a revisión, donde se analizará tu código fuente PHP 8 y, tras su aprobación, se desplegará dicho código en la infraestructura de AppointmentTrader, lo que garantiza un rendimiento rápido y que tu código no cambie después de completar la revisión.
Puedes monetizar tu trabajo de una o varias de las siguientes formas:
-> Recibirás automáticamente una comisión en cualquier transacción que se haya generado a través de tu app por otro usuario (por ejemplo, si creas un calendario o proceso de pago mejorado, todas las transacciones que pasen por aquí te generarán una comisión).
-> Recibirás automáticamente una comisión en cualquier endpoint de pago que ejecute tu app.
-> Puedes cobrar una tarifa de suscripción
Importante: Como las apps pueden llegar a ser parte integral de AppointmentTrader, mantendrás tus derechos de comisión mientras la app siga en funcionamiento para los usuarios; sin embargo, puede que no permitamos que retires la app una vez desplegada y mientras esté en uso.
Las apps pueden escuchar eventos que ocurren en AppointmentTrader.
Tu App recibirá un identificador único y una clave privada tras registrarla usando /v1/apps/set
Registrar una app mediante /v1/apps/set proporcionará una respuesta similar a la que aparece abajo; por favor, descarga el SDK de AppointemntTrader en la URL definida en el campo Payload->sdkUrl.
Recuerda: NO compartas este archivo zip; contiene tus claves personales y compartirlo comprometerá tu seguridad.
Después de descomprimir el contenido de este archivo, puedes descargar el archivo definido en "boilerplateUrl" para obtener la configuración de base, como se define en la estructura de carpetas de abajo.
/v1/apps/get_list te dará estas URL para todas tus apps si necesitas consultarlas de nuevo.
{
"RequestUserAlias": "YourUserHandle",
"RequestPath": "/v1/apps/set",
"RequestStatus": "Succeeded",
"ResponseCode": 100,
"ResponseMessage": "Request Successful",
"Payload": {
"uniqueAppIdentifier": "ForecastExplorer",
"sdkUrl": "https://appointmenttrader.com/modules/apps/download_sdk.php?unique_app_id=ForecastExplorer&app_private_key=588f9b00f6038448a3200d8b736474f4",
"boilerplateUrl": "https://appointmenttrader.com/modules/apps/download_sdk.php?boilerplate"
}
}
Las apps pueden ser accedidas de la siguiente manera:
https://appointmenttrader.com/[YourAppIdentifier]
Carpetas raíz de ejemplo:
Para la versión actual: (en este ejemplo v3 sería la versión vigente)
https://appointmenttrader.com/ForecastExplorer
Para una versión anterior: (solo visible para desarrolladores y revisores)
https://appointmenttrader.com/ForecastExplorer/legacy-versions/v2
Para el estado de desarrollo (solo visible para la cuenta del desarrollador)
https://appointmenttrader.com/ForecastExplorer/development
Para la versión candidata en revisión (solo visible para desarrolladores y revisores) tras ejecutar el endpoint API: apps::set_new_version
https://appointmenttrader.com/ForecastExplorer/release-candidate
La estructura de presentación de la App es la siguiente:
[AppointmentTrader HTML5 Header, + bibliotecas listadas en "uiLibraries"]
[Tu código HTML & Javascript renderizado]
[AppointmentTrader HTML5 Footer]
Por favor, sigue las siguientes instrucciones para construir tus archivos HTML para el usuario:
Las apps no pueden tener librerías externas (frontend o backend), solo pueden contener código HTML5, PHP, JavaScript y CSS puro, no se permiten frameworks.
En el backend, las llamadas a APIs https deben gestionar toda la comunicación con proveedores externos.
Tu App AT debe implementar Namespacing
Requerimos namespacing dentro de tu app para evitar IDs HTML, clases CSS o funciones php&javascript duplicadas en todo el ecosistema.
Implementación obligatoria de ID HTML Namespace:
Los elementos HTML pueden no tener ID, pero si tienen uno, necesitas anteponer tu identificador de app único. (Devuelto por /v1/apps/set)
<span id="[YourAppIdentifier]-anyIdNameYouLike">Texto</span>
Implementación obligatoria de Namespace JavaScript:
Esta forma de implementar funciones javascript es necesaria para evitar nombres duplicados en el ecosistema.
Nota: Usa la variable global de JavaScript _[YourAppIdentifier]BaseURL para acceder a la URL base relativa de tu proyecto (para tareas como llamadas HTTPS Fetch).
var YourAppIdentifier = {};
YourAppIdentifier.CustomFunction = function(testParameter) {
console.log(testParameter);
};
YourAppIdentifier.CustomObject = {};
Implementación obligatoria de Namespace CSS:
No se permiten modificadores globales como [name="xxx"]; todas las hojas de estilo deben encapsularse en clases o selectores por ID
#[YourAppIdentifier]-anyIdNameYouLike {
color: red;
}
.[YourAppIdentifier]-color-red-text {
color: red;
}
Implementación obligatoria de Namespace PHP:
Incluye el archivo at_app_header.php como la primera línea de código en cada archivo php, lo cual hará que tu app opere en el namespace correcto y pondrá funciones API a tu disposición; no llames a funciones de API AT vía https sino usa ATApiRead(string $endpoint, array $variables) y ATApiWrite(string $endpoint, array $variables, bool $validateRequestOnly), ya que se invocarán diferente cuando despliegues tu versión a producción.
Ejemplo de uso de algunas funciones del SDK PHP:
// at_app_header.php establecerá el Namespace ATApp[YourAppIdentifier]
include __DIR__ . '../at_app_header.php';
// $ATUser['ID'] contiene el ID del usuario autenticado
// null cuando no hay usuario autenticado
echo $ATUser['ID'] === null ? 'No hay usuario conectado' : 'ID de usuario conectado:'.$ATUser['ID'];
//$ATUser['Alias'] contiene el Alias de usuario autenticado
// null cuando no hay usuario autenticado
echo $ATUser['Alias'] === null ? 'No hay usuario conectado' : 'Alias de usuario conectado:'.$ATUser['Alias'];
//tu código php
No uses etiquetas <html />, <head /> y <body /> - tu HTML será incorporado dentro de la estructura HTML de AppointmentTrader, por lo que estas etiquetas serían redundantes.
Agrega todas las bibliotecas requeridas en el archivo structure.json.php en la sección "uiLibraries" como se describe abajo, así los recursos se renderizarán correctamente en el código HTML de AppointmentTrader.
Cuando hagas llamadas a APIs de AppointmentTrader desde tu UI HTML _no_ necesitas incluir el campo API key, ya que se usará el usuario autenticado que esté usando tu
interfaz para ejecutar tu solicitud.
Por favor, estructura tu App en tu infraestructura de la siguiente manera:
(Ejemplo: https://tuhomelabip/myatapp/)
Importante: Tu directorio de proyecto AT debe tener permisos de escritura (en sistemas Linux 0777) para at_app_header.php, /appointmenttrader_sdk/ y /production/, ya que la gestión de revisiones de AT modificará el sistema de archivos al desplegar una nueva versión (como comprimir la versión respectiva y actualizar archivos del sdk si es necesario).
Aviso de seguridad: /v1/apps/set devolverá el [YourAppIdentifier] público y una clave privada que debe pegarse en la variable $at_app_private_key de at_app_header.php, ya que se usará para acceder de manera segura a tu sistema de archivos desde AppointmentTrader.
/at_app_header.php -> este archivo es parte del paquete sdk enlazado en /v1/apps/set y /v1/apps/get_list y debe estar en la raíz y ser incluido por todos los archivos PHP backend
/appointmenttrader_sdk/ -> incluye archivos de recursos del paquete sdk mencionado arriba
/development/ -> Esta es tu carpeta de desarrollo. Si inicias sesión como desarrollador, podrás acceder al estado actual de desarrollo en vivo, sin revisión, en https://appointmenttrader.com/[UserAlias]/[YourAppIdentifier]/development/. Aquí harás todos los cambios, y el SDK de AppointmentTrader gestionará el despliegue y revisión vía el endpoint API :apps::set_new_version una vez completes el desarrollo y pruebas de la versión actual.
/development/index.php -> página inicial de tu App
/development/structure.json.php -> archivo que incluye la estructura de la app
/development/invoke_event.php (opcional) -> será llamado cuando un evento registrado por la app ocurra (como onNewBid)
/development/php-libraries/ (opcional) -> si tu app crea librerías, agrégalas aquí; deben terminar en lib.php y no se aceptarán en revisión de otra forma, no se puede llamar directamente a librerías, solo incluirlas, asegurando el uso de namespaces
/development/css-libraries/ (opcional) -> si tu app crea librerías css, agrégalas aquí
/development/javascript-libraries/ (opcional) -> si tu app crea librerías javascript, agrégalas aquí
/development/datastore/ (opcional) -> si tu app lee o escribe datos, ubica aquí, esta es la única carpeta que puede ser leída o escrita usando file_get_contents() en producción
/development/assets/ (opcional) -> si tu app usa recursos como imágenes, guárdalos aquí; para acceder usa la variable get _ATWebBasePath, Ejemplo: img src="echo $_GET['_ATWebBasePath']; assets/image.jpg" o la variable JavaScript _RequestPath
/development/marketing/ -> contiene todos los materiales para presentar tu app a otros usuarios
/development/marketing/storefront.html
/development/marketing/assets/ (opcional)
/production/ -> el endpoint API :apps::set_new_version se comunicará con tu servidor usando el SDK de AppointmentTrader para crear un archivo zip del estado de desarrollo actual y entregar los archivos al entorno de producción AT usando esta estructura de carpetas.
Ejemplo de estructura structure.json.php, todos los paths son relativos a [baseurl]version:
Importante: Recuerda no incluir archivos javascript ni css en tu código HTML usando etiquetas <script /> o <link />, ya que AT se encargará de esto usando tu archivo structure.json.php.
La clave 'any-ui-file' hará que tus librerías estén disponibles para todos los archivos de tu proyecto y las claves de archivo las harán disponibles solo para archivos específicos.
La clave 'globalAliasFor' en la sección de navegación permite especificar dónde los usuarios pueden implementar tu app en su Portal AppointmentTrader, por ejemplo, si creas una mejor vista de portafolio, los usuarios pueden seleccionar tu aplicación desde la sección de portafolios.
{
"technical": {
"uiLibraries": {
"any-ui-file": [
{
"path": "/javascript-libraries/util.js",
"type": "javascript"
},
{
"path": "/css-libraries/style.css",
"type": "stylesheet"
}
],
"exampledir/examplefile.html": [
{
"path": "/javascript-libraries/extra_util.js",
"type": "javascript"
}
]
},
"registerForEventList": [
"OnNewBid"
],
"navigation": [
{
"itemName": "Pro Portfolio",
"itemDescription": "Portafolio avanzado y rápido para Pro Sellers en AT",
"itemLink": "/exampledir/examplefile.php",
"globalAliasFor": "/modules/portfolio/index.php"
}
],
"marketing": [
{
"pricing":[{"monthly":[{"Type":"USDCent", "Amount":2900, "TrialperiodInDays":14}]}],
"appIconPath": "/assets/icon.png"
}],
"communityRewards": [
{
"perTranslatedKey":[{"Type":"Traderpoint", "Amount":25}],
"perValidatedBug":[{"Type":"Traderpoint", "Amount":250}]
}]
}
}
Guía de estilo de la interfaz
Por favor, asegúrate de que tu App sigue la siguiente guía de estilos para ofrecer una experiencia de usuario consistente para los usuarios de AT
Colores:
#FFFFFF (blanco)
#3C9A52 (Verde AppointmentTrader)
#3D9563F (Rojo AppointmentTrader)
#555555 Gris (Principalmente para texto)
Títulos:
Utiliza títulos en orden consecutivo: h1 para el contenido principal, h2 para secciones de menor jerarquía, etc.
Cajas de información - usa el siguiente estilo, ya que tu contenido HTML se mostrará dentro del portal AppointmentTrader y tendrás acceso a las clases css y a las imágenes mencionadas abajo
<div class="shadow">;
<h2>Título</h2>
<div class="info_box_line">
<div class="icon"> <img src="/images/ios-information-circle-outline.svg"> </div>
<div class="info">
<p class="small-text mb-1 gray-txt">Tu contenido informativo</p>
</div>
</div>
</div>
Los elementos distintos a Cajas de información deben tener un padding de 16px a la izquierda y derecha
El espacio vertical entre elementos debe ser de 5px para elementos relacionados y 10px o una etiqueta <hr>.
Párrafos
<p class="small-text mb-1 gray-txt">Texto del párrafo</p>
Enlaces y botones:
Enlaces
A menos que el enlace sea externo, utiliza la función javascript:Navigate() para navegar y así permitir funciones de carga dinámica.
<a class="link" href="javascript:Navigate('abc');">Texto del botón
Botón de confirmación:
<a class="btn-profit" href="https://appointmenttrader.com">Texto del botón
Botón de cancelar:
<a class="btn-cancel" href="https://appointmenttrader.com">Texto del botón
Botón de eliminar:
<a class="btn-delete" href="https://appointmenttrader.com">Texto del botón
Botón de confirmación principal:
<a class="btn full" href="https://appointmenttrader.com">Texto del botón
Formularios
<div class="form-group">
<label class="small-text gray-txt" id="[YourAppIdentifier]-input-field-label">Etiqueta de campo de entrada</label>
<input autocomplete="off" type="text" class="form-control" value="" id="[YourAppIdentifier]-input-field">
</div>
Funciones UI Javascript
Presentar un mensaje
ScreenFeedback("Tu mensaje", "Tu título");
AppointmentTrader permite a los usuarios navegar por toda la plataforma usando la barra de búsqueda que aparece en cada página,
los desarrolladores de apps pueden aprovechar este sistema agregando los siguientes atributos a su contenido.
La estructura general de la búsqueda DOM es la siguiente:
CONTENEDOR
-- ELEMENTO 1
-- ELEMENTO 2
<ul data-domsearchgroupcontainer="Nombre del contenedor">
<li data-domsearchgroup="Nombre del contenedor" data-domsearchphrase="Elemento 1 del contenedor">Elemento 1</li>
<li data-domsearchgroup="Nombre del contenedor" data-domsearchphrase="Elemento 2 del contenedor">Elemento 1</li>
</ul>
Soporte multilenguaje
Al mostrar texto, utiliza la función sdk echolang(), que generará automáticamente claves de idioma y permitirá que usuarios de la comunidad traduzcan tu app.
Puedes ofrecer recompensas a usuarios para traducir tu app y así esté disponible en más regiones AppointmentTrader configurando la clave "communityRewards"->"perTranslationKey" en tu structure.json.php, pagando a un usuario comunitario cada vez que agregue una traducción a tu app.
/v1/tools/
Ofrece funciones útiles para complementar los intercambios de citas
/v1/community/
Gestiona funciones relacionadas con la comunidad
/v1/location/
Gestiona todas las funciones relacionadas con la ubicación.
/v1/listing/
Gestiona funciones relacionadas con la cartera, como cambios de precio y de estado
/v1/portfolio/
Gestiona todas las funciones relacionadas con la cartera
/v1/bid/
Gestiona todas las funciones relacionadas con las ofertas
/v1/aichat/
Gestiona funciones relacionadas con el chat de IA
/v1/account/
Gestiona el acceso a la cuenta de AppointmentTrader
/v1/marketdata/
Contiene todas las funciones de datos de mercado para que los vendedores puedan detectar tendencias a lo largo del año
/v1/medal/
Administra todas las funciones relacionadas con medallas y permisos de usuario
/v1/user/
Contiene todas las funciones relacionadas con el usuario
/v1/notification/
Gestiona todas las funciones relacionadas con las notificaciones