Árbol del API · Facturas y cobranza › bankTerminals

Terminales bancarias

bankTerminals

Tipo

Query

Devuelve

[BankTerminal!]!

Permiso de la llave

Ventas

Estable

Lista las terminales bancarias activas para los cobros con tarjeta de un almacén, con su cuenta bancaria y su banco.

Úsala para registrar un cobro con tarjeta con createCollection: si la forma de cobro tiene card: true en paymentMethodOptions, el cobro pide en terminalId el id de una de estas terminales.

Llegan sólo las terminales activas, ordenadas por nombre. Una terminal sin empresa sirve a los almacenes de todas las empresas del grupo, y una sin cuenta bancaria sirve a cualquier cuenta: llega con cualquier bankAccountId, con bankAccount y bank en null.

Cuando la terminal tiene cuenta, el cobro debe ir a esa cuenta: envía bankAccount.id en bankAccountId y bank.id en bankId. Cuando tiene empresa, debe ser la del cobro: la del almacén o, si el cobro lleva xcumId, la de esa unidad de negocio. Las terminales se piden por almacén, así que con un xcumId de otra empresa revisa companyId. Las otras formas de cobro no llevan terminal.

bankTerminals(
  warehouseId: ID  bankAccountId: ID
): [BankTerminal!]!

# terminales.graphql
query Terminales($almacen: ID!, $cuenta: ID) {
  bankTerminals(warehouseId: $almacen, bankAccountId: $cuenta) {
    id
    name
    bankAccount { id code currency }
    bank { id name }
  }
}

Variables: {"almacen": "3", "cuenta": "9"}

jq -n --rawfile q terminales.graphql \
  '{query: $q, variables: {"almacen":"3","cuenta":"9"}}' |
curl https://mi-empresa.advantacloud.com/graphql \
  -H "Authorization: Bearer $ADVANTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data @-

import { readFile } from "node:fs/promises";

const query = await readFile("terminales.graphql", "utf8");

const res = await fetch("https://mi-empresa.advantacloud.com/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADVANTA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query,
    variables: { almacen: "3", cuenta: "9" },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].extensions?.code ?? errors[0].message);
console.log(data.bankTerminals);

import os, requests

URL = "https://mi-empresa.advantacloud.com/graphql"
HEADERS = {"Authorization": f"Bearer {os.environ['ADVANTA_API_KEY']}"}
QUERY = open("terminales.graphql").read()

r = requests.post(URL, headers=HEADERS, timeout=30, json={
    "query": QUERY,
    "variables": {"almacen": "3", "cuenta": "9"},
})
r.raise_for_status()
body = r.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
print(body["data"]["bankTerminals"])

<?php
$ch = curl_init('https://mi-empresa.advantacloud.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ADVANTA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'query' => file_get_contents('terminales.graphql'),
        'variables' => ['almacen' => '3', 'cuenta' => '9'],
    ]),
]);
$respuesta = curl_exec($ch);
$estatus = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($respuesta === false || $estatus !== 200) {
    throw new RuntimeException("HTTP $estatus " . curl_error($ch));
}
$body = json_decode($respuesta, true);
if (!empty($body['errors'])) {
    throw new RuntimeException($body['errors'][0]['message']);
}
$resultado = $body['data']['bankTerminals'];

Respuesta 200 OK · 2 terminales

{
  "data": {
    "bankTerminals": [
      {
        "id": "11",
        "name": "Cobranza en ruta",
        "bankAccount": null,
        "bank": null
      },
      {
        "id": "6",
        "name": "Mostrador Monterrey",
        "bankAccount": {
          "id": "9",
          "code": "0458712390",
          "currency": "MXN"
        },
        "bank": {
          "id": "4",
          "name": "Banorte"
        }
      }
    ]
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`warehouseId`ID	ID	Almacén del cobro, el mismo `warehouseId` que enviarás a `createCollection`. Llegan las terminales de la empresa a la que pertenece el almacén y las que no tienen empresa. Es obligatorio, aunque el schema lo marque opcional.
`bankAccountId`ID	ID	Sólo las terminales de esta cuenta bancaria y las que no tienen cuenta. Envía la cuenta del cobro para descartar las de otras cuentas.

Lo que devuelve

[BankTerminal!]!

Campos principales de BankTerminal:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador de la terminal.
`name`String!	String!	Nombre de la terminal.
`bankAccount`BankAccount	BankAccount	Cuenta bancaria donde se depositan sus cobros; `null` si la terminal sirve a cualquier cuenta. Un cobro con esta terminal debe ir a esta cuenta.
`bank`Bank	Bank	Banco de la cuenta de la terminal; `null` si no tiene cuenta.
`companyId`ID	ID	Empresa del grupo a la que pertenece la terminal; `null` si sirve a todas las empresas.

Ver todos los campos de BankTerminal

Permisos

Llave API Integraciones

Ventas

La llave ve los registros de toda la empresa del subdominio.

Sin el permiso Sin error

La consulta responde sin error, pero la lista llega vacía.

Así lo conserva el API para las integraciones que ya lo usan: revisa los permisos de la llave si una lista llega vacía sin razón.

Errores

Código	Cuándo ocurre	Qué hacer
HTTP 401	Falta el header `Authorization` o la llave no existe en la empresa del subdominio. La respuesta no trae cuerpo.	Revisa la llave y el subdominio. No reintentes.
`VALIDATION`	Falta `warehouseId`. El mensaje es «Envía orderId o warehouseId, sólo uno».	Envía el almacén del cobro.
`NOT_FOUND`	No hay un almacén con ese `warehouseId` en la empresa.	Revisa el `warehouseId` con `warehouseOptions`.
HTTP 422	Falla interna o dato rechazado al guardar. El cuerpo es `{"error": …}`, sin `data`.	Si no cambiaste nada, reintenta con espera exponencial.

Los errores de la consulta llegan con HTTP 200 en errors, con su código en extensions.code. Revisa siempre errors, no sólo el estatus HTTP. Errores y reintentos.

Relacionadas

Schema del 26 oct 2026 · Ver cambios¿Algo no cuadra? Repórtalo en ayuda.advanta.mx