API

Aquí se detallará toda la información sobre la API de CustomCards.

Precaución

Antes de empezar con la documentación, se deben tener en cuenta las siguientes concideraciones:

1. Es importante destacar que esta documentación se centrará en las versiones 2 y posteriores debido a que la versión 1 será deprecada (y dejará de ser accesible) una semana después de la publicación de la versión 2.

2. Se asume que el usuario tiene conocimientos básicos sobre peticiones HTTP, por lo que no se explicarán detalles técnicos que se puedan llegar a mencionar a lo largo del documento.

URL Base

Las solicitudes que se hagan hacia la API deben realizarse a la siguiente URL:

https://custom-cards.koyeb.app/v{VERSION}

{VERSION} debe ser reemplazado por el número de la versión que se desea utilizar. Por ejemplo, si deseas usar la versión 1 debes especificarlo en la ruta:

https://custom-cards.koyeb.app/v1

Versión 2 (actual)

La versión 2 introdujo características que antes estaban limitadas por el diseño de la versión 1. Por lo tanto, para poder aprovechar estas características, es necesario tener en cuenta la forma en la que debemos hacer una petición a la API.

Tipo de contenido

Comumente se usa el header Content-Type: application/json para enviar información al servidor en formato JSON, pero la realidad es que la Version 2 introdujo la capacidad de enviar archivos locales (anteriormente sólo se admitían URLs). Por lo tanto, a partir de la versión 2 en adelante, las solicitudes deberán enviarse con el header Content-Type: multipart/form-data y el cuerpo de la solicitud en el respectivo formato (FormData)

Peligro

Algunas veces se puede dar el caso que obtengar un error con la descripción Missing boundary, la mejor solución a esto es eliminar el header Content-Type y que su cliente HTTP lo estableza por usted (como en el caso de fetch() con JavaScript).

Autorización

Al momento de hacer una solicitud es normal que obtengas un error HTTP 401 Unauthorized, pues para evitar abusos y poder ofrecer muchas más características se implementaron los Tokens. Para evitar este error es necesario incluir en cada petición el header Authorization.

Authorization: Bearer <TOKEN>

<TOKEN> deberá ser reemplazado por el token de acceso que solicita el usuario dentro del servidor de discord. (Leer más)

Variantes

En la versión 2 y posteriores se admitirán más de un estilo de diseño. Significa que este deberá ser la primera propiedad que se debe encontrar presente en el body de la solicitud, pues las propiedades usadas en cada estilo podrían cambiar de acuerdo a las necesidades.

Existen 2 nombres de variantes válidos, pero su disponibilidad puede cambiar de acuerdo al tipo de tarjeta.

Nota

Tener en cuenta que las variantes son sensitivas a mayúsculas y minúsculas.

Peligro

El objetivo de las variantes es poder utilizar más de un estilo sin tener que usar muchas rutas. Cada estilo puede tener sus propias propiedades, por lo que el body no siempre será el mismo para cada estilo, aunque si puede haber propiedades compartidas (propiedades que no cambian sin importar el estilo).

interface Body {
  variant: "Classic" | "Revay";
}

Leer más sobre las variantes El contenido sobre las variantes y el body de cada solicitud se encuentra aquí.

Rutas

La versión 2 de CustomCards admite las siguientes rutas, estas estarán acompañadas del respectivo método y cuerpo que se debe usar.

POST /cards/welcome

Classic

Propiedad	Tipo	Requerido	Descripción
variant	”Classic”	true	La variante de la tarjeta.
font	string	true	La tipografía a usar.
text	array	true	Los texto de la tarjeta (máximo 3 índices)
frameType	string	true	El tipo de marco para el avatar. (Leer más sobre el frameType)
avatar	File	true	El avatar a usar en la tarjeta.
background	File	false	El fondo de la tarjeta.
backgroundOpacity	number	false	La opacidad de la tarjeta, un número entre 0 y 1 (máximo 1, por defecto 0).