Catálogo completo de filtros, campos, errores comunes y preguntas frecuentes del API de Consulta.
Consulta de referencia para el API de Consulta de Transacciones.
Consultas
| Consulta | Argumentos | Uso |
|---|---|---|
allTransactions | Todos los filtros de abajo | Listados. La principal |
transaction | orderId, transactionId | Búsqueda puntual. La más rápida |
allTransactionsV2 | Los mismos que allTransactions | Misma información, más lenta |
Filtros de allTransactions
allTransactions| Argumento | Tipo | Descripción |
|---|---|---|
rangeDateFilter | objeto | Rango por fecha de venta: { min: "YYYY/MM/DD", max: "YYYY/MM/DD" } |
paymentDateFilter | objeto | Rango por fecha de depósito, mismo formato |
storeId | lista de enteros | Uno o varios puntos de cobro: [1234567, 1234568] |
companyId | entero | Empresa |
transactionId | texto | Una transacción específica |
transactionTokenId | texto | El token UUID del cobro |
externalReference | texto | Tu referencia externa |
merchantRefCode | texto | Tu código de referencia de comercio |
paymentMethod | lista de texto | Método de pago |
promotion | lista de texto | Promoción (meses sin intereses, etc.) |
filterPreauth | lista de booleanos | Filtra preautorizaciones |
product | lista de enteros | Producto |
cognitoUser | texto | Usuario del portal |
productyfilterPreauthexcluyen registrosÚsalos solo cuando quieras acotar deliberadamente. Para reportes y conciliación, déjalos fuera y clasifica en tu sistema.
Los filtros de fecha no aceptan variables de GraphQL
rangeDateFilterypaymentDateFilterresponden HTTP 500 si reciben sus valores por variables. Escribe las fechas dentro del texto de la consulta.Las variables sí funcionan para los filtros de texto (
transactionTokenId,transactionId) y para listas (storeId).
Campos de la respuesta
Identificadores
| Campo | Tipo | Descripción |
|---|---|---|
transaction_id | texto | Identificador de la transacción. Es el que pide el servicio de devoluciones |
transaction_token_id | texto | Token UUID del cobro |
order_id | texto | Tu número de orden. 20 dígitos: manéjalo siempre como texto |
external_reference | texto | Tu referencia externa |
merchant_ref_code | texto | Tu código de referencia |
Comercio y punto de cobro
| Campo | Tipo | Descripción |
|---|---|---|
store_id | entero | Punto de cobro |
store_name | texto | Nombre del punto de cobro |
branch_id, branch_name | entero, texto | Sucursal |
company_id, company_name | entero, texto | Empresa |
merchant_id, sub_merchant_id | texto | Afiliación |
terminal_id | texto | Terminal física |
cashier | texto | Cajero |
product_id, product_name | entero, texto | Producto con el que se procesó |
Fechas
| Campo | Formato | Descripción |
|---|---|---|
transaction_date | DD/MM/YYYY HH:mm | Fecha de la venta |
payment_date_np | DD/MM/YYYY HH:mm | Fecha del depósito. Vacío si aún no se deposita |
void_date | DD/MM/YYYY HH:mm | Fecha de cancelación |
Montos
Todos los montos vienen en pesos con decimales, no en centavos.
| Campo | Tipo | Descripción |
|---|---|---|
auth_amount | decimal | Monto autorizado |
capt_amount | decimal | Monto capturado. Es el que cuenta para el depósito |
tip_amount | decimal | Propina |
sales_tax_amount | texto | Impuesto |
currency | texto | Moneda (MXN) |
Estados
| Campo | Descripción |
|---|---|
status | Estado principal. Ver tabla abajo |
report_status | Pagada / No Exitosa |
conc_status | C cuando está conciliada |
response_code | Código de respuesta del emisor |
response_msg | Mensaje del emisor. Motivo del rechazo cuando aplica |
Valores de status
status| Valor | Significado | ¿Hay dinero? |
|---|---|---|
Aprobada | Cobro autorizado | Sí |
Devolución | Registro de una devolución aplicada | Se resta |
Rechazada | El emisor rechazó el cobro | No |
Reversada | La operación se revirtió | No |
Cancelada | Se canceló antes de liquidar | No |
Autorización y rastreo
| Campo | Descripción |
|---|---|
auth_code | Código de autorización del emisor. Prueba del cobro |
host_ref_num | Referencia del adquirente |
eci | Indicador de comercio electrónico (3D Secure) |
Tarjeta
| Campo | Descripción |
|---|---|
brand | Marca (Visa, Mastercard, Amex) |
card_type | Crédito o débito |
span_route_num | Últimos dígitos de la tarjeta |
bank_name | Banco emisor |
payment_method, payment_method_description | Método de pago |
Promociones
| Campo | Descripción |
|---|---|
promotion | Promoción aplicada |
promo_term | Plazo |
promo_term_description | Descripción del plazo |
Disputas y contracargos
| Campo | Descripción |
|---|---|
dispute_state | Estado de la disputa |
dispute_case_number | Número de caso |
disputed_amount | Monto disputado |
dispute_creation_date | Fecha de apertura |
Cliente
| Campo | Descripción |
|---|---|
email_client | Correo del comprador |
phone_number | Teléfono |
Hay más campos disponiblesEl servicio expone campos adicionales. Si necesitas alguno que no esté aquí, consulta con tu ejecutivo de cuenta.
Buenas prácticas
| Práctica | Por qué |
|---|---|
| Pide solo los campos que necesitas | La respuesta pesa una fracción |
| Trocea rangos amplios por mes | No hay paginación; respuestas grandes arriesgan timeout |
| Manda una referencia propia al cobrar | Te permite buscar desde tus identificadores |
Guarda el transaction_token_id al cobrar | Localizas cualquier transacción sin depender de fechas |
order_id y transaction_id como texto | Como número pierden dígitos |
| Montos con tipos decimales | float genera diferencias de centavos |
Normaliza acentos al comparar status | Devolución lleva acento |
Revisa errors aunque el HTTP sea 200 | Los errores de consulta vienen con código 200 |
Errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
| Error de autenticación | Header equivocado | Usa X-Netpay-Apikey, no Authorization |
| HTTP 500 en consultas con fechas | Variables de GraphQL en los filtros de fecha | Escribe las fechas dentro del texto de la consulta |
HTTP 200 pero con errors | Error en la consulta | Revisa errors; indica el campo o argumento inválido |
| HTTP 404 | URL o ambiente incorrecto | Verifica la URL de tu ambiente |
| La respuesta viene vacía | Filtros product o filterPreauth, o no hay movimiento en ese rango | Quita esos filtros y verifica las fechas |
| Montos multiplicados o divididos por 100 | Asumiste centavos | Los montos vienen en pesos con decimales |
| El número de orden pierde los últimos dígitos | Se procesó como número | Manéjalo como texto en todo el flujo |
| Diferencias de centavos al sumar | Se usó float | Usa tipos decimales |
La comparación de status falla | Problema de acentos | Normaliza el texto al comparar |
| Una venta no aparece en ningún depósito | payment_date_np vacío | Todavía no se liquida; consulta después |
| La conciliación no cuadra por devoluciones | La ventana no llega hasta hoy | Amplía el rango: las devoluciones se fechan cuando se aplican |
Checklist de integración
Configuración
- Header
X-Netpay-Apikeyconfigurado. - URL correcta por ambiente, probado primero en sandbox.
-
storeIdde todos tus puntos de cobro identificados.
Construcción de consultas
- Fechas escritas dentro del texto de la consulta, con formato validado.
- Solo los campos necesarios en cada consulta.
- Rangos amplios troceados por mes.
Manejo de la respuesta
- Se revisa
errorsaunque el HTTP sea 200. -
order_idytransaction_idtratados como texto. - Montos con tipos decimales, en pesos.
- Comparación de
statusnormalizando acentos. - Al consultar por
order_id, se recorre todo el arreglo.
Preguntas frecuentes
¿Puedo consultar todos mis comercios con una sola llave?
Sí. Si omites storeId, la consulta devuelve todos los comercios asociados a tu llave dentro de la misma empresa.
¿Cada cuánto puedo consultar?
Evita consultas repetidas de rangos amplios. Para procesos automáticos, una corrida diaria es suficiente.
¿Esto reemplaza mis webhooks?
No. Los webhooks te avisan en tiempo real; este servicio es para consultar, verificar y conciliar.
¿Por qué una venta aprobada no aparece en ningún depósito?
Porque todavía no se liquida. Si payment_date_np está vacío, está pendiente.
¿Puedo aplicar devoluciones desde aquí?
No. Este servicio solo consulta. Las devoluciones se aplican con el servicio de Cancelaciones y reembolsos.
¿Los montos incluyen comisiones?
No. Los montos son los de la venta y los depósitos se hacen en bruto. Las comisiones se cobran por separado.
¿Cómo distingo mis ventas en línea de las de terminal?
Con product_name y terminal_id.
¿Por qué dos ventas del mismo día se depositaron en fechas distintas?
Porque el plazo de depósito depende de la marca de la tarjeta. Por eso la conciliación se hace con payment_date_np y no con una regla de días.
