Árbol del API · Facturas y cobranza › collectionsConnection

Lista de cobros

collectionsConnection

Tipo

Query

Devuelve

CollectionConnection!

Permiso de la llave

Consultar Cobros

Página

20 por omisión · máx. 100

Estable

Lista los cobros de la empresa con su importe, su forma de cobro y las facturas a las que se aplicaron. Filtra por cliente y por fecha del pago, y recorre el resultado por páginas con cursores.

Úsala para saber qué pagos recibió la empresa y a qué facturas se aplicaron; con customerId ves los cobros de un cliente. El saldo que queda en cada factura está en invoicesConnection.

La llave ve los cobros de toda la empresa del subdominio, sin importar quién los registró.

collectionsConnection(
  first: Int  after: String  customerId: ID  from: Date
  to: Date
): CollectionConnection!

# cobros.graphql
query Cobros($cliente: ID!, $desde: Date!, $cursor: String) {
  collectionsConnection(
    first: 100
    after: $cursor
    customerId: $cliente
    from: $desde
  ) {
    nodes {
      id
      status
      date
      amount
      currency
      paymentMethod { code name }
      reference
      applications(first: 20) {
        nodes {
          invoice { id folio }
          amount
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables: {"cliente": "1311", "desde": "2026-10-01", "cursor": null}

jq -n --rawfile q cobros.graphql \
  '{query: $q, variables: {"cliente":"1311","desde":"2026-10-01","cursor":null}}' |
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("cobros.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: { cliente: "1311", desde: "2026-10-01", cursor: null },
  }),
});
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.collectionsConnection);

import os, requests

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

cursor, nodos = None, []
while True:
    r = requests.post(URL, headers=HEADERS, timeout=30, json={
        "query": QUERY,
        "variables": {"cliente": "1311", "desde": "2026-10-01", "cursor": cursor},
    })
    r.raise_for_status()
    body = r.json()
    if "errors" in body:
        raise RuntimeError(body["errors"][0]["message"])
    page = body["data"]["collectionsConnection"]
    nodos += page["nodes"]
    if not page["pageInfo"]["hasNextPage"]:
        break
    cursor = page["pageInfo"]["endCursor"]

<?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('cobros.graphql'),
        'variables' => ['cliente' => '1311', 'desde' => '2026-10-01', 'cursor' => null],
    ]),
]);
$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']['collectionsConnection'];

Respuesta 200 OK · 2 de 2 nodos

{
  "data": {
    "collectionsConnection": {
      "nodes": [
        {
          "id": "91342",
          "status": "RECONCILED",
          "date": "2026-10-15T13:20:00.000000-06:00",
          "amount": "10000.00",
          "currency": "MXN",
          "paymentMethod": {
            "code": "TRA",
            "name": "Transferencia electrónica"
          },
          "reference": "SPEI 7765410",
          "applications": {
            "nodes": [
              {
                "invoice": {
                  "id": "72988",
                  "folio": "FMTY26100131"
                },
                "amount": "10000.00"
              }
            ]
          }
        },
        {
          "id": "91530",
          "status": "APPLIED",
          "date": "2026-10-24T10:15:00.000000-06:00",
          "amount": "13432.00",
          "currency": "MXN",
          "paymentMethod": {
            "code": "TRA",
            "name": "Transferencia electrónica"
          },
          "reference": "SPEI 7781203",
          "applications": {
            "nodes": [
              {
                "invoice": {
                  "id": "73015",
                  "folio": "FMTY26100154"
                },
                "amount": "4872.00"
              },
              {
                "invoice": {
                  "id": "72988",
                  "folio": "FMTY26100131"
                },
                "amount": "8560.00"
              }
            ]
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "WzEsInhhY3FzIiwidXBkYXRlZF9hdCIsZmFsc2UsIjIwMjYtMTAtMjRUMTA6MTY6MDIuMTE4NTQwLTA2OjAwIiw5MTUzMF0="
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Paginación
`first`Int	Int	Cuántos cobros devolver desde el inicio o desde `after`. Sin `first` llegan 20; si pides más de 100 recibes 100.
`after`String	String	Cursor de la página anterior (`pageInfo.endCursor`). Devuelve los cobros que siguen.
Filtros
`customerId`ID	ID	Sólo los cobros de este cliente.
`from`Date	Date	Pagos recibidos desde este día, inclusive (`AAAA-MM-DD`).
`to`Date	Date	Pagos recibidos hasta este día, inclusive. Con Llave API el día se corta en la hora del centro de México.

Estatus de un cobro

CollectionStatus

REGISTEREDRegistrado, sin aplicar a facturas

PARTIALLY_APPLIEDAplicado en parte; le queda importe por aplicar

APPLIEDAplicado completo a facturas

RECONCILEDAplicado y conciliado con el banco

CANCELLEDCancelado

UNKNOWNSin equivalente; revisa rawStatus

Ver CollectionStatus

Lo que devuelve

CollectionConnection!

nodes[Collection]Los cobros de esta página. La forma más corta de leerlos.

edges[CollectionEdge]Los mismos cobros, cada uno con su cursor.

pageInfoPageInfo!Dónde estás en la lista.

hasNextPageBoolean!Hay más elementos después de esta página.

endCursorStringCursor del último elemento; pásalo en after para pedir la página siguiente.

hasPreviousPageBoolean!true si pediste esta página con after, es decir, si no es la primera.

startCursorStringCursor del primer elemento de esta página.

Campos principales de Collection

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador del cobro; úsalo con `collection(id:)` y con `paymentComplement(collectionId:)`.
`status`CollectionStatus!	CollectionStatus!	Estatus del cobro.
`date`DateTime	DateTime	Fecha y hora en que se recibió el pago. Es la fecha de pago que lleva el complemento de pago.
`amount`Money	Money	Importe recibido, en la moneda de la cuenta bancaria que lo recibió.
`currency`String	String	Clave SAT de la moneda del cobro, p. ej. `MXN` o `USD`.
`paymentMethod`PaymentMethod	PaymentMethod	Forma de cobro.
`reference`String	String	Referencia del pago, p. ej. la clave de rastreo de una transferencia.
`tpcbro`String	String	Tipo de cobro, `Cobro` o `Anticipo`.
`applications`CollectionApplicationConnection!	CollectionApplicationConnection!	Las facturas a las que se aplicó el cobro, con el importe aplicado a cada una, por su último cambio.20 por omisión, hasta 100 por página.
`receiptPdfUrl`String	String	Liga al PDF del complemento de pago que incluye el cobro, aunque todavía no esté timbrado. Llega `null` mientras el cobro no está en un complemento. Está firmada y vence a los 10 minutos.

Ver todos los campos de Collection

Paginación

first · after

Pide hasta 100 cobros por página junto con pageInfo. Repite la misma consulta pasando endCursor en after mientras hasNextPage sea true. El orden es estable: no se saltan cobros entre páginas. Más sobre paginación.

Los cobros llegan por su última modificación, del más antiguo al más reciente: si uno cambia de estatus mientras recorres la lista, pasa al final y puede llegar otra vez con sus datos al día. Las aplicaciones de cada cobro (applications) son otra conexión con su propio límite de 100; si un cobro tiene más, pide el resto con collection(id:) y applications(after:).

Permisos

Llave API Integraciones

Consultar Cobros

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

Sin el permiso Sin error

La consulta responde sin error, pero nodes llega vacío y hasNextPage es false.

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.
`argumentLiteralsIncompatible`	Una fecha escrita en la consulta no es `AAAA-MM-DD`. Si el valor llega en una variable, el error trae `extensions.problems` y puede no traer `code`.	Corrige la consulta; reintentar no ayuda.
`VALIDATION`	El cursor de `after` está mal formado o es de otra lista, o `first` es negativo. También aplica al cursor de `applications`.	Empieza de nuevo sin `after` y usa sólo cursores de `pageInfo`.
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