GraphQL API
URL de pruebas: https://api-sandbox.koywe.com/graphql
Esta URL corre una instancia del explorador Apollo, por si es que quieres probar la API desde tu navegador.
Envíanos un email a hola@koywe.com para obtener tus credenciales de prueba o que te hagamos un tour personalizado.
Pruebas: La API de pruebas funciona en las testnets de las distintas blockchains. Tenemos un stock limitado de tokens, por lo que te pedimos criterio al probarlas.
Queries y Mutaciones
Para hacer llamados a la API GraphQL, siempre debes enviar un request POST a la URL base, incluyendo la query y variables como objeto JSON. Un ejemplo en CURL de autenticación (header de Authorization incluido ilustrativamente):
En los ejemplos siguientes sólo pondremos el objeto JSON del request.
Authentication
devuelve un Bearer Token que dura 24 horas.
Require: clientId
, secret
Opcional: email
. Este campo asocia las transacciones a una cuenta de usuario específica y permite ver la información asociada a esta.
Los dos siguientes servicios permiten la validación de un usuario final de manera directa. El primer servicio enviará un código al correo deseado. Ese código debe ser ingresado en el segundo servicio para recibir la información de la sesión.
Validación de sesión
Envía un código de 6 dígitos al email entregado en el input.
Validación de código
El valor de code en el input debe ser recogido del correo enviado por el servicio anterior.
Pares
Obtiene los pares de moneda-tokens soportados.
Opcional: symbol:
El símbolo de la moneda a elección. clientId
.
Obtiene los pares de token-monedas soportados.
Opcional: symbol
. El símbolo del cripto a elección. clientId
Métodos de Pago
Listado de los medios de pago disponibles y sus detalles (fee, datos de transferencia, etc) para una moneda específica.
Requiere: symbol
. currencyId
.
Opcional: clientId
. La lista de medios de pago disponibles pueden variar de acuerdo a este parámetro.
Reglas para Pagos por Transferencia Bancaria WIRE: Para los pagos realizados mediante transferencia bancaria, se han establecido las siguientes reglas:
- Se permite a los usuarios tener solo una orden activa por cliente si utilizan la transferencia bancaria como su método de pago. Esto implica que si un usuario crea una nueva orden mediante transferencia bancaria, las órdenes anteriores se cancelarán, y solo se mantendrá activa la orden más reciente.
- Si un usuario realiza un pago mediante transferencia bancaria y el saldo no es igual al monto de la orden, el sistema ajustará automáticamente la orden. Este ajuste es necesario tanto para los pagos que son inferiores al monto de la orden como para las órdenes que superan el monto especificado.
Métodos para Payouts
Listado de los payouts disponibles y sus detalles (fees, tiempos, etc) para una moneda específica.
Requiere: symbol
. currencyId
.
Opcional: clientId
. La lista de medios de pago disponibles pueden variar de acuerdo a este parámetro.
Servicios Quote
Consultar Quote
Devuelve un “Quote”. Recibe un quoteId.
Crear Quote
Queries Privadas
Todas las queries a continuación requieren un Bearer Token en los headers:
Servicio de cuentas de usuarios
Estos servicios de usuario incluye: la creación de nuevos perfiles de usuario, la capacidad de actualizar información de usuarios,
la posibilidad de consultar detalles de usuario, y una función de validación que verifica si el usuario brindo datos suficientes de su persona para poder operar.
Ver Consideraciones
Check account
Verifica la información de la cuenta del usuario y determina si es posible realizar alguna operación. Si llegase a faltar algún dato del usuario, podría agregarlo mediante el servicio de actualización de usuario detallado mas abajo.
Get account
Devuelve la información registrada del usuario.
Create account
Crea una cuenta nueva de usuario.
Update account
Actualiza datos del usuario. Si updateEmail está presente, la API valida que sea un email válido y que no exista ya otra cuenta con ese email.
Si updateDocumentNumber o updateDocumentType está presente, la API valida que tenga un formato válido, que no exista en otra cuenta, que no tenga ordenes ejecutadas y ejecuta una validación asíncrona para corroborar que los datos personales sean correctos.
Los resultados de la validación asíncrona serán enviados a el callback configurado. Puedes ver más información en la sección de webhooks.
Servicios de órdenes
Create Order
Crea una orden de compra o venta, retorna un UUID para seguimiento (orderId
) y, dependiendo del medio de pago, una URL para realizarlo (providedAction
).
Para llamadas autenticadas sin haber asociado un email
, debe incluirse uno como parámetro para asociar la transacción a un usuario específico.
Necesitas introducir amountIn
o amountOut
, no ambos.
On ramp
Requiere: destinationAddress
, quoteId
.
Off ramp
Requiere: destinationAddress
, quoteId
.
Opcional: email
(obligatorio si no se está autenticado con email), documentNumber
(para facilitar la conciliación bancaria).
Descripción de datos: ver Order Rest
Consultar Orden
Retorna información de una order. Recibe un orderId
.
Consultar Orden Por ExternalId
Retorna información de una order. Recibe un ExternalId
.
Consultar Ordenes Por txHash
Retorna la información de las ordenes vinculadas al txHash. Recibe un txHash
.
Lista de órdenes pasadas
Retorna una lista de todas las órdenes asociadas al clientId
o al email
especificado al autenticarse.
pagesize
: Límite de 300, representa la cantidad de respuestas por página.
pageNumber
: Número de páginas a mostrar.
initDate
: Fecha de inicio desde la cual se obtienen los registros. Formato: YYYY-MM-DD. Se incluirán los registros desde esta fecha en adelante, a menos que se especifique un endDate.
endDate
: Fecha de fin hasta la cual se obtienen los registros. Formato: YYYY-MM-DD. Se incluirán solo los registros hasta esta fecha. Si se omite, se retornarán los registros hasta la fecha actual.
Agrega txHash para orden Off Ramp
Agrega el txHash a una orden de off ramp. Valida que el hash sea válido para la red de la operación.
Reembolso de Orden
Inicia una solicitud de reembolso para una orden off-ramp debido a errores en los detalles de la transferencia de fiat, devolviendo el orderId y el estado de la solicitud.
Reprocesando una orden
Servicio responsable de reprocesar un pedido en caso de errores bancarios. El objetivo es poder finalizar la transacción OFF correspondiente, donde se realiza una transferencia a la cuenta bancaria asociada.
Servicios Bancarios
Create Bank Account
Crea una nueva cuenta bancaria y la guarda para futuras operaciones.
opcional: bankCode
, documentNumber
, payoutMethodId (deprecado)
documentNumber
es requerido en el caso de que el usuario no haya hecho el KYC.
Validaciones Bancos en Colombia
Para evitar rechazos, debes cumplir con estos requerimientos al crear una cuenta en Colombia:
Warning: El número de cuenta: el campo Bank Account Number debe contener sólo números y ser distinto a 0.
Get Bank Account
Retorna una lista de cuentas bancarias asociadas al usuario, filtrados de acuerdo a countryCode
, currencySymbol
y email
.
Delete Bank Account
Elimina una cuenta bancaria de la lista de cuentas guardadas.
Get Bank Info by Country
Retorna una lista con los bancos que son soportados para un countryCode
dado.