# 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](https://docs.monei.com/es/es/monei-connect/.md)** (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](https://www.howtographql.com/). Si aún no tienes una cuenta de MONEI, necesitarás [crear](https://dashboard.monei.com/?action=signUp) una para usar la GraphQL API. ## Explorador GraphQL integrado[​](#explorador-graphql-integrado "Enlace directo al Explorador GraphQL integrado") Usa el [Explorador GraphQL integrado](https://docs.monei.com/es/es/apis/graphql/explorer/.md) 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[​](#explorador-de-la-graphql-api "Enlace directo al Explorador de la GraphQL API") Si quieres empezar a experimentar con la API de inmediato, puedes hacerlo en el [Explorador de la GraphQL API](https://dashboard.monei.com/api-explorer) 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[​](#autenticación "Enlace directo al 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](https://dashboard.monei.com/settings/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)[​](#autenticación-de-socios-monei-connect "Enlace directo al Autenticación de socios (MONEI Connect)") Los socios de [MONEI Connect](https://docs.monei.com/es/es/monei-connect/.md) 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: ' \ --header 'MONEI-Account-ID: ' \ --header 'User-Agent: MONEI//' \ --header 'Content-Type: application/json' \ --data-raw '{"query":"{account {name status}}"}' ``` ## Endpoint de la GraphQL API[​](#endpoint-de-la-graphql-api "Enlace directo al Endpoint de la GraphQL API") ``` POST https://graphql.monei.com ``` ## Consultar la GraphQL API[​](#consultar-la-graphql-api "Enlace directo al 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: ' \ --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](https://dashboard.monei.com/api-explorer) interactivo de tu MONEI Dashboard. ## Ejemplos de consultas[​](#ejemplos-de-consultas "Enlace directo al 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](https://docs.monei.com/es/es/apis/graphql/explorer/.md) 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[​](#obtener-un-pago-individual "Enlace directo al 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[​](#listar-pagos-con-filtros "Enlace directo al 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[​](#informe-kpi-pagos-en-un-rango-de-fechas "Enlace directo al 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[​](#suscripciones "Enlace directo al 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)[​](#eventos-de-cobro-registro-de-auditoría "Enlace directo al 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[​](#ejemplos-de-mutaciones "Enlace directo al Ejemplos de mutaciones") Las mutaciones son el equivalente de los verbos de acción de modificación de datos de REST. #### Reembolsar un pago[​](#reembolsar-un-pago "Enlace directo al 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[​](#capturar-un-pago-autorizado "Enlace directo al 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 } } ```