Servicios generales GraphQL

Un solo servicio para consultar todas tus transacciones, sin importar con qué integración las cobraste.

Todas las integraciones de NetPay comparten un mismo servicio de consulta. Sin importar si cobras con Checkout Custom, Checkout Plus, Checkout Hosted o con terminales físicas, todas tus transacciones se consultan desde el mismo lugar.

Qué puedes hacer con este servicio

Lo que necesitasDónde está
Buscar una venta, verificar un pago, atender una aclaraciónBuscar una transacción
Sacar reportes de ventas por periodo o por punto de cobroReportes y exportaciones
Cuadrar los depósitos que recibes contra tus ventasConciliación de depósitos
Ver todos los filtros y campos disponiblesReferencia

Esta página cubre los conceptos y la configuración inicial. Empieza aquí antes de ir a las demás.

📘

No necesitas saber GraphQL

GraphQL es una forma de consultar datos donde tú pides exactamente los campos que necesitas en lugar de recibir una respuesta gigante con todo. Se usa como cualquier API: mandas un POST con un JSON y recibes un JSON.

Copia los ejemplos de esta documentación, cambia las fechas y tus identificadores, y listo.


Conceptos básicos

Cuatro conceptos que explican la mayoría de las dudas al integrar.

1. El storeId identifica cada punto de cobro

Un storeId no es tu negocio completo: es cada punto donde cobras.

  • Cada terminal física tiene su propio storeId.
  • Tu tienda en línea tiene un storeId.

Si tienes 5 terminales y un ecommerce, manejas 6 storeId.

Esto importa porque los depósitos se hacen por storeId, y los reportes también se organizan así.

📘

companyId agrupa tus comercios

Todos tus storeId pertenecen a una empresa (companyId). Puedes consultar por empresa cuando quieres ver todo junto, o por storeId cuando necesitas el detalle de un punto de cobro.

2. Los tres identificadores de una transacción

Una misma venta tiene tres identificadores, y cada uno sirve para algo distinto:

IdentificadorQué esCuándo lo usas
order_idTu número de orden, el que tú generasEl más práctico: ya lo tienes en tu sistema
transaction_token_idEl UUID que te devolvemos al cobrarSi lo guardaste al procesar el pago
transaction_idNuestro identificador internoEs el que requiere el servicio de devoluciones
❗

order_id tiene 20 dígitos: trátalo como texto

Excede la precisión de un número decimal (double), así que si lo manejas como número vas a perder los últimos dígitos. Guárdalo y transpórtalo siempre como texto (string), y si lo exportas a Excel dale formato de celda como texto.

La misma regla aplica para transaction_id.

3. Una venta y sus devoluciones comparten identificadores

Cuando devuelves un cobro, la devolución queda como un registro aparte, con su propio transaction_id, pero comparte el order_id y el transaction_token_id del cobro original.

Por eso, al consultar por order_id recibes toda la cadena: el cobro y todas sus devoluciones.

4. El producto con el que cobraste

El campo product_name te dice con qué integración se procesó cada transacción. Te sirve para separar, por ejemplo, tus ventas en línea de las de tus terminales cuando consultas todo junto.


Configuración

Lo que necesitas

QuéDónde lo obtienes
Tu secretKeyNetPay Manager → Llaves. Es la misma que usas para cobrar
Tus storeIdNetPay Manager, o pregúntale a tu ejecutivo de cuenta

El endpoint

AmbienteURL
Sandboxhttps://gateway.netpay-api.com/reports-sandbox/v1/graphql
Producciónhttps://gateway.netpay-api.com/reports/v1/graphql

Siempre es un POST a la misma URL. Lo que cambia es el contenido del cuerpo.

Los headers

X-Netpay-Apikey: {tu secretKey}
Content-Type: application/json
❗

El header es X-Netpay-Apikey, no Authorization

Es el error más común al integrar este servicio. El API de cobro usa Authorization; el de consulta usa X-Netpay-Apikey. Si mandas el header equivocado recibes un error de autenticación aunque tu llave sea correcta.


Tu primera consulta

Traigamos las transacciones de un día:

curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ allTransactions( storeId: [1234567] rangeDateFilter: { min: \"2026/09/09\", max: \"2026/09/09\" } ) { transaction_id order_id transaction_date auth_amount status } }"}'
{
  "data": {
    "allTransactions": [
      {
        "transaction_id": "90296F9F-4915-0A46-F335-5E047CBB4CED",
        "order_id": "17889789767211234567",
        "transaction_date": "09/09/2026 12:36",
        "auth_amount": 14,
        "status": "Aprobada"
      }
    ]
  }
}

Cómo se arma el cuerpo

El cuerpo es un JSON con una sola llave, query, cuyo valor es texto:

{ "query": "{ NOMBRE_DE_LA_CONSULTA( FILTROS ) { CAMPOS_QUE_QUIERES } }" }
  • NOMBRE_DE_LA_CONSULTA — normalmente allTransactions.
  • FILTROS — qué transacciones quieres.
  • CAMPOS_QUE_QUIERES — qué datos quieres de vuelta, separados por espacios.

Pedir solo los campos que necesitas hace la respuesta mucho más ligera. Si después necesitas un campo más, lo agregas a la lista.


Tres reglas que te van a ahorrar tiempo

❗

Las fechas van escritas dentro del texto, no como variables de GraphQL

Si intentas pasar las fechas con variables ($min, $max) en los filtros de fecha, el servidor responde HTTP 500. Escríbelas directamente en el texto de la consulta.

Si las armas concatenando en tu código, valida primero el formato YYYY/MM/DD para no abrir una inyección.

❗

Un HTTP 200 no siempre es éxito

Si algo está mal en la consulta, el servidor puede responder 200 con un campo errors en el cuerpo. Revisa siempre si existe errors antes de leer data.

{ "errors": [ { "message": "Field 'campo_inexistente' doesn't exist..." } ] }
🚧

Los montos vienen en pesos, no en centavos

auth_amount: 1678.14 son mil seiscientos setenta y ocho pesos con catorce centavos. No los multipliques ni los dividas por 100.


Entender la respuesta

Los estados de una transacción

statusQué pasó¿Hay dinero?
AprobadaEl cobro fue autorizadoSí, se te va a depositar
DevoluciónRegistro de una devolución aplicadaSe resta de tu depósito
RechazadaEl banco emisor rechazó el cobroNo
ReversadaLa operación se revirtióNo
CanceladaSe canceló antes de liquidarNo
❗

Devolución lleva acento

Al comparar en tu código, normaliza el texto (quita acentos y pasa a minúsculas) para no depender de la codificación de tu cliente HTTP.

Además de status, tienes dos campos de apoyo:

CampoValoresPara qué sirve
report_statusPagada, No ExitosaTe dice si ya se depositó
conc_statusC cuando está conciliadaConfirmación de nuestro lado

Los montos

CampoQué es
auth_amountEl monto autorizado
capt_amountEl monto realmente capturado
tip_amountLa propina, cuando aplica

En una venta normal auth_amount y capt_amount son iguales. En preautorizaciones pueden diferir: autorizas un monto y capturas otro. Para efectos de dinero real, capt_amount es el que manda.

🚧

Súmalos con tipos decimales, no con float

Sumar muchos float produce errores de centavos en cualquier lenguaje. Usa Decimal en Python, BigDecimal en Java, decimal en C#, o trabaja en enteros de centavos internamente.

El mensaje del emisor

Cuando una transacción es rechazada, response_msg trae el motivo tal como lo devolvió el banco emisor. Es el primer lugar a revisar cuando un cliente te dice que su pago no pasó.


Las consultas disponibles

ConsultaPara qué sirveVelocidad
allTransactionsLa principal. Listados con cualquier combinación de filtrosDepende del rango
transactionBuscar por orderId o transactionIdLa más rápida
allTransactionsV2Misma información que allTransactionsMás lenta; usa la primera

En la práctica vas a usar allTransactions para listados y transaction para búsquedas puntuales.


Siguientes pasos