BEZ-Coin token logoBEZHAS
apiIntegraciónIntermedio4 min de lectura

Referencia de API

La API Core es la puerta de entrada para integrar BeZhas sin escribir Solidity. Unifica wallet, staking, gobernanza, contratos, billing y las integraciones sectoriales.

Esta referencia cubre solo endpoints públicos de integración. Los endpoints de administración, despliegue y operación interna no se documentan aquí y no son accesibles con credenciales de integrador.

Base y autenticación

text
Producción : https://api.bezhas.com/api
Local      : http://localhost:3001/api

Todas las llamadas (salvo /sso/login y las marcadas public) requieren API key y JWT:

http
Authorization: Bearer <JWT>
X-API-Key: <API_KEY>

El JWT se obtiene mediante login con wallet y es válido entre Apps Nativas del ecosistema. Se mantiene en memoria, nunca en disco ni en localStorage.

Gateway unificado

Todos los endpoints cuelgan de /gateway/v1/.

Sesión

MétodoRutaDescripciónScope
POST/sso/loginLogin con wallet, devuelve JWT cross-apppublic

Wallet

MétodoRutaDescripciónScope
GET/wallet/balancesBalances de todos los tokenswallet:read
POST/wallet/transferTransferir tokenswallet:write

Staking y farming

MétodoRutaDescripciónScope
GET/staking/positionsPosiciones activasstaking:read
POST/staking/stakeIniciar staking de BEZstaking:write
GET/farming/poolsPools de farming disponiblesfarming:read

Gobernanza

MétodoRutaDescripciónScope
GET/governance/proposalsPropuestas activasgovernance:read
POST/governance/voteVotar una propuestagovernance:write

Token, contratos y tesorería

MétodoRutaDescripciónScope
GET/token/infoDatos del token BEZpublic
GET/contracts/addressesDirecciones de contratos por redpublic
GET/treasury/overviewEstado de la tesorería DAOtreasury:read

Bridge

MétodoRutaDescripciónScope
POST/bridge/initiateIniciar transferencia cross-chainbridge:write

Otros namespaces

RutaPara qué
GET /healthSalud del Core
GET /contracts-abi/*Descarga de ABIs
POST /cargolink/v1/*Integración logística CargoLink
POST /ai-billing/*Billing, créditos y consumo

Endpoints sectoriales

SectorEndpointDescripción
LogísticaGET /v1/supply/shipmentsListar envíos
LogísticaGET /v1/supply/checkpointsCheckpoints de rastreo
LogísticaGET /v1/supply/certificatesCertificados de calidad
LogísticaGET /v1/supply/tariffsTarifas y aranceles
AduanasPOST /v1/supply/customs/clearSolicitar despacho
SaludGET /v1/health/recordsRegistros clínicos (permisos explícitos)
EnergíaGET /v1/energy/creditsCréditos de carbono

Los endpoints de datos personales o clínicos exigen permisos específicos y consentimiento registrado; no basta con un token válido.

Roles

RolAlcance
userConsulta básica
agentOperaciones de agentes sectoriales
adminOperaciones internas — no documentadas ni disponibles públicamente

Ejemplo

bash
curl -H "Authorization: Bearer $JWT" \
     -H "X-API-Key: $BEZHAS_API_KEY" \
     https://api.bezhas.com/api/gateway/v1/wallet/balances
js
const res = await fetch(`${BASE}/gateway/v1/staking/positions`, {
  headers: {
    Authorization: `Bearer ${jwt}`,
    'X-API-Key': apiKey,
  },
});
if (!res.ok) throw new Error(`API ${res.status}`);
const posiciones = await res.json();

Errores

CódigoSignificadoQué hacer
400Petición inválidaRevisa el cuerpo y los tipos
401Sin autenticarAPI key o JWT ausente, caducado o mal formado
403Sin permisoTu scope no cubre esa operación
404No existeRevisa la ruta y los identificadores
429Rate limitBackoff exponencial y reintento
5xxError del servidorReintenta; si persiste, abre incidencia

Ante un 401, comprueba primero si el JWT ha caducado: se renueva automáticamente en el SDK, pero no si lo gestionas a mano.

Reglas de integración

  • Nunca expongas la API key en el frontend. Las llamadas autenticadas salen de tu backend.
  • No registres JWT ni API keys en logs, trazas ni sistemas de errores.
  • Usa siempre HTTPS.
  • Todas las Apps Nativas deben consumir el mismo Core, el mismo sistema de billing y el mismo BEZ-Coin: no dupliques la lógica de créditos por tu cuenta.

Ver también