Saltar al contenido principal

MONEI GraphQL API

Con la MONEI GraphQL API tienes acceso completo a todas las funciones de MONEI, como informes de análisis, pagos, eventos y mucho más. Esta API requiere autenticación y está pensada para usarse en el lado del servidor. Tanto los comercios (su propia cuenta) como los socios de MONEI Connect (que actúan en nombre de cuentas de comercios vinculadas) pueden utilizarla.

Si quieres saber cómo funciona la GraphQL API, consulta How to GraphQL.

Si aún no tienes una cuenta de MONEI, necesitarás crear una para usar la GraphQL API.

Explorador GraphQL integrado​

Usa el Explorador GraphQL integrado para probar la API directamente desde esta documentación. Pega cualquier clave de API en modo de prueba, navega por el esquema y ejecuta consultas contra https://graphql.monei.com/. Cada página de operación (consultas y mutaciones) tiene un enlace "Abrir en el Explorador ↗" que precarga una consulta de ejemplo. No es necesario iniciar sesión como comercio.

Explorador de la GraphQL API​

Si quieres empezar a experimentar con la API de inmediato, puedes hacerlo en el Explorador de la GraphQL API de tu cuenta de MONEI. Puedes ejecutar consultas (queries) y mutaciones (mutations) en el explorador para ver lo que la MONEI GraphQL API puede ofrecerte. El Explorador de API está disponible para todos los usuarios de MONEI.

nota

Atención: El Explorador GraphQL de MONEI utiliza tus datos reales de producción.

Autenticación​

La API utiliza claves de API para autenticar las solicitudes. Puedes ver y gestionar tu clave de API en el MONEI Dashboard → Ajustes → Acceso a la API.

Tu clave de API permite el acceso completo a todos los recursos de MONEI, así que asegúrate de mantenerla segura. No compartas tu clave de API secreta en áreas de acceso público como GitHub, código del lado del cliente, etc.

Incluye tu clave de API como cabecera Authorization en todas tus solicitudes GraphQL.

Autenticación de socios (MONEI Connect)​

Los socios de MONEI Connect utilizan su Clave de API de socio más una cabecera MONEI-Account-ID que indica la cuenta del comercio en cuyo nombre actúan. Todas las consultas y mutaciones de esta página funcionan de forma idéntica: solo cambian las cabeceras.

curl --request POST 'https://graphql.monei.com' \
--header 'Authorization: <PARTNER_API_KEY>' \
--header 'MONEI-Account-ID: <MONEI_ACCOUNT_ID>' \
--header 'User-Agent: MONEI/<PARTNER_NAME>/<VERSION>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{account {name status}}"}'

Endpoint de la GraphQL API​

POST https://graphql.monei.com

Consultar la GraphQL API​

Puedes acceder al endpoint de la GraphQL API usando cURL o cualquier otro cliente HTTP.

curl --request POST 'https://graphql.monei.com' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{account {name status}}"}'
nota

Puedes explorar las consultas y mutaciones de la GraphQL API en el Explorador de la GraphQL API interactivo de tu MONEI Dashboard.

Ejemplos de consultas​

En GraphQL, las consultas (queries) son el equivalente del verbo de acción GET de REST. Aunque se envía un POST al endpoint de GraphQL, si el cuerpo solo contiene consultas, los datos únicamente se recuperarán y no se modificarán.

Los ejemplos siguientes reproducen las consultas que ejecuta el propio MONEI Dashboard; puédalas en el Explorador GraphQL para ver datos reales de tu cuenta.

nota

Todos los campos monetarios se devuelven en la unidad monetaria más pequeña (céntimos para EUR/USD). 1234 en EUR equivale a €12,34. Las marcas de tiempo para rangos de KPI/filtros están en segundos unix.

Obtener un pago individual​

Busca un cobro por ID: los campos principales que se muestran en la página de detalle de pago del panel.

query GetPayment($id: ID!) {
  charge(id: $id) {
    id
    orderId
    amount
    currency
    status
    statusCode
    statusMessage
    refundedAmount
    authorizationCode
    createdAt
    customer {
      email
      name
      phone
    }
    paymentMethod {
      method
      card {
        brand
        country
        last4
        threeDSecure
      }
    }
    metadata {
      key
      value
    }
  }
}
{
  "id": "bc8eb8588e175ce4c957212f17ca051a"
}

Listar pagos con filtros​

Alimenta la tabla de Pagos del panel: filtra por rango de fechas, estado, tienda, moneda, correo electrónico del cliente, etc. range acepta dos marcas de tiempo en segundos unix; match es exacto; matchPhrase no distingue mayúsculas de minúsculas.

query ListPayments($filter: SearchableChargeFilterInput, $search: String, $size: Int, $from: Int) {
  charges(filter: $filter, search: $search, size: $size, from: $from) {
    total
    items {
      id
      orderId
      amount
      currency
      status
      createdAt
      customer {
        email
      }
      paymentMethod {
        method
        card {
          brand
          last4
        }
      }
    }
  }
}
{
  "filter": {
    "createdAt": {"range": [1748304000, 1748390399]},
    "status": {"match": "SUCCEEDED"},
    "currency": {"match": "EUR"}
  },
  "size": 25,
  "from": 0
}

Informe KPI: pagos en un rango de fechas​

Alimenta el gráfico de resumen del panel y las tarjetas de KPI. Devuelve totales agregados más una serie agrupada por tiempo (minute, hour, day, week, month, quarter, year) para la moneda elegida.

query ChargesKPI(
  $start: Int!
  $end: Int!
  $interval: Interval!
  $timezone: String
  $currency: Currencies
  $storeId: ID
) {
  chargesDateRangeKPI(
    start: $start
    end: $end
    interval: $interval
    timezone: $timezone
    currency: $currency
    storeId: $storeId
  ) {
    currency
    total {
      succeededAmount
      succeededCount
      refundedAmount
      refundedCount
      failedCount
      capturedAmount
      directAmount
    }
    data {
      timestamp
      succeededAmount
      succeededCount
      refundedCount
      failedCount
    }
  }
}
{
  "start": 1745020800,
  "end": 1747612799,
  "interval": "day",
  "timezone": "Europe/Madrid",
  "currency": "EUR"
}

KPIs derivados (calcúlalos en el cliente a partir de total):

  • Tasa de autorización — succeededCount / (succeededCount + failedCount)
  • Tasa de reembolso — refundedAmount / succeededAmount
  • Ticket medio — succeededAmount / succeededCount

Suscripciones​

Facturación recurrente activa: filtra y pagina de la misma forma que con charges.

query ListSubscriptions($filter: SearchableSubscriptionFilterInput, $size: Int, $from: Int) {
  subscriptions(filter: $filter, size: $size, from: $from) {
    total
    items {
      id
      status
      amount
      currency
      interval
      intervalCount
      nextPaymentAt
      customer {
        email
        name
      }
    }
  }
}
{
  "filter": {"status": {"match": "ACTIVE"}},
  "size": 25,
  "from": 0
}

Eventos de cobro (registro de auditoría)​

Cada cambio de estado en un cobro: útil para la conciliación, el soporte y la depuración de la entrega de webhooks.

query ChargeEvents($chargeId: ID!, $size: Int, $from: Int) {
  chargeEvents(chargeId: $chargeId, size: $size, from: $from) {
    total
    items {
      id
      type
      createdAt
      object {
        status
        statusCode
        statusMessage
        amount
        refundedAmount
      }
    }
  }
}

Ejemplos de mutaciones​

Las mutaciones son el equivalente de los verbos de acción de modificación de datos de REST.

Reembolsar un pago​

Reembolso total o parcial. amount está en unidades menores y es obligatorio: pasa el importe original completo para un reembolso total.

mutation Refund($input: RefundPaymentInput!) {
  refundPayment(input: $input) {
    id
    status
    amount
    refundedAmount
    lastRefundAmount
    lastRefundReason
  }
}
{
  "input": {
    "paymentId": "bc8eb8588e175ce4c957212f17ca051a",
    "amount": 500,
    "refundReason": "requested_by_customer"
  }
}

Capturar un pago autorizado​

Para pagos con flujo AUTH: captura los fondos previamente autorizados. El pago debe estar en estado AUTHORIZED. Omite amount para capturar el importe total autorizado; capturar un importe menor reembolsa automáticamente la diferencia.

mutation Capture($input: CapturePaymentInput!) {
  capturePayment(input: $input) {
    id
    status
    amount
    authorizationCode
  }
}
{
  "input": {
    "paymentId": "bc8eb8588e175ce4c957212f17ca051a",
    "amount": 1000
  }
}