Árbol del API · Facturas y cobranza › collection

Detalle de un cobro

collection

Tipo

Query

Devuelve

Collection

Permiso de la llave

Consultar Cobros

Estable

Devuelve un cobro por su id, con su importe, su forma de cobro y las facturas a las que se aplicó.

Si la llave no tiene el permiso, la respuesta es collection: null sin error; un cobro que no existe responde NOT_FOUND. Así distingues una llave mal configurada de un id equivocado.

La factura de cada aplicación (applications.invoice) pide además el permiso «Facturación» en la llave; sin él llega null, pero el importe aplicado sí llega.

receiptPdfUrl llega cuando el cobro ya está en un complemento de pago, aunque el complemento aún no esté timbrado. Para saber si ya se timbró y descargar el XML, usa paymentComplement(collectionId:).

collection(
  id: ID!
): Collection

# cobro.graphql
query Cobro($id: ID!) {
  collection(id: $id) {
    id
    status
    date
    amount
    currency
    paymentMethod { code name card }
    reference
    applications(first: 100) {
      nodes {
        invoice { id folio uuid balance }
        amount
      }
      pageInfo { hasNextPage endCursor }
    }
    receiptPdfUrl
  }
}

Variables: {"id": "91530"}

jq -n --rawfile q cobro.graphql \
  '{query: $q, variables: {"id":"91530"}}' |
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("cobro.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: { id: "91530" },
  }),
});
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.collection);

import os, requests

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

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

<?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('cobro.graphql'),
        'variables' => ['id' => '91530'],
    ]),
]);
$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']['collection'];

Respuesta 200 OK

{
  "data": {
    "collection": {
      "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",
        "card": false
      },
      "reference": "SPEI 7781203",
      "applications": {
        "nodes": [
          {
            "invoice": {
              "id": "73015",
              "folio": "FMTY26100154",
              "uuid": "3F2A9C1E-7B4D-4E8A-9C21-0A5B6D7E8F90",
              "balance": "0.00"
            },
            "amount": "4872.00"
          },
          {
            "invoice": {
              "id": "72988",
              "folio": "FMTY26100131",
              "uuid": "C7D41B90-2E6A-4F18-B3C5-9A0E7D2F6B14",
              "balance": "0.00"
            },
            "amount": "8560.00"
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "endCursor": "WyJhcHBsaWNhdGlvbnM6OTE1MzAiLFsiMjAyNi0xMC0yNFQxNjoxNjowMi4yMDQxMThaIiwxODg0MDJdXQ=="
        }
      },
      "receiptPdfUrl": null
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`id`ID!	ID!	Identificador del cobro, el mismo `id` que llega en `collectionsConnection` o en `createCollection`. Obligatorio.

Lo que devuelve

Collection

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`.
`xcumId`ID	ID	Unidad de negocio del cobro.
`cobdorId`ID	ID	Cobrador asignado al cobro; `null` si no tiene.
`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

Las aplicaciones llegan en applications, una conexión con 20 por omisión y hasta 100 por página. Para un cobro aplicado a más facturas, repite la consulta con applications(first: 100, after: $cursor).

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 el resultado llega null.

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.
`NOT_FOUND`	No hay un cobro con ese `id` en la empresa.	Revisa el `id`.
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