Árbol del API · Facturas y cobranza › invoicesConnection

Lista de facturas

invoicesConnection

Tipo

Query

Devuelve

InvoiceConnection!

Permiso de la llave

Facturación

Página

20 por omisión · máx. 100

Estable

Lista las facturas de la empresa con su cliente, su total y su saldo por cobrar. Filtra por cliente, estatus, fecha de emisión o texto, pide sólo las que tienen saldo pendiente y recorre el resultado por páginas con cursores.

Úsala para llevar la cartera a tu sistema: con customerId y onlyPending: true tienes lo que un cliente debe, y con from y to, lo emitido en un periodo. Para el XML o el PDF de una factura usa invoice(id:).

La lista trae también las notas de crédito de la empresa, que llegan con el mismo tipo y sólo se distinguen por la serie de su folio. Una factura sin cuenta por cobrar llega con balance, paid y dueDate en null; una factura vencida es la que tiene dueDate en el pasado y balance mayor que cero.

La llave ve las facturas de toda la empresa del subdominio, sin importar quién las emitió.

invoicesConnection(
  first: Int  after: String  customerId: ID
  onlyPending: Boolean  status: [InvoiceStatus!]
  from: Date  to: Date  search: String
): InvoiceConnection!

# facturas-pendientes.graphql
query FacturasPendientes($desde: Date!, $cursor: String) {
  invoicesConnection(
    first: 100
    after: $cursor
    onlyPending: true
    status: [INVOICED]
    from: $desde
  ) {
    nodes {
      id
      folio
      uuid
      issuedAt
      dueDate
      customer { id name rfc }
      currency
      total
      paid
      balance
    }
    pageInfo { hasNextPage endCursor }
  }
}

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

jq -n --rawfile q facturas-pendientes.graphql \
  '{query: $q, variables: {"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("facturas-pendientes.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: { 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.invoicesConnection);

import os, requests

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

cursor, nodos = None, []
while True:
    r = requests.post(URL, headers=HEADERS, timeout=30, json={
        "query": QUERY,
        "variables": {"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"]["invoicesConnection"]
    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('facturas-pendientes.graphql'),
        'variables' => ['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']['invoicesConnection'];

Respuesta 200 OK · 2 de 100 nodos

{
  "data": {
    "invoicesConnection": {
      "nodes": [
        {
          "id": "72988",
          "folio": "FMTY26100131",
          "uuid": "C7D41B90-2E6A-4F18-B3C5-9A0E7D2F6B14",
          "issuedAt": "2026-10-07T09:31:12.000000-06:00",
          "dueDate": "2026-11-06",
          "customer": {
            "id": "1311",
            "name": "Ferretería Hermanos Garza",
            "rfc": "XAXX010101000"
          },
          "currency": "MXN",
          "total": "18560.00",
          "paid": "10000.00",
          "balance": "8560.00"
        },
        {
          "id": "73015",
          "folio": "FMTY26100154",
          "uuid": "3F2A9C1E-7B4D-4E8A-9C21-0A5B6D7E8F90",
          "issuedAt": "2026-10-24T12:05:31.000000-06:00",
          "dueDate": "2026-11-23",
          "customer": {
            "id": "1311",
            "name": "Ferretería Hermanos Garza",
            "rfc": "XAXX010101000"
          },
          "currency": "MXN",
          "total": "4872.00",
          "paid": "0.00",
          "balance": "4872.00"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "WzEsInh2Zm1zIiwidXBkYXRlZF9hdCIsZmFsc2UsIjIwMjYtMTAtMjRUMTI6MDU6MzEuNDgyMTEzLTA2OjAwIiw3MzAxNV0="
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Paginación
`first`Int	Int	Cuántas facturas 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 las facturas que siguen.
Filtros
`customerId`ID	ID	Sólo las facturas de este cliente.
`onlyPending`Boolean	Boolean	Con `true`, sólo las facturas con saldo por cobrar mayor que cero; no incluye las facturas de anticipo. Con `false` u omitido, todas.
`status`[InvoiceStatus!]	[InvoiceStatus!]	Uno o varios estatus; basta con que la factura tenga uno de ellos. Una lista vacía no trae ninguna factura.
`from`Date	Date	Emitidas desde este día, inclusive (`AAAA-MM-DD`).
`to`Date	Date	Emitidas hasta este día, inclusive. Con Llave API el día se corta en la hora del centro de México.
`search`String	String	Texto que contiene el folio, el UUID, o el nombre o la clave del cliente, sin distinguir mayúsculas: `"0154"` encuentra `FMTY26100154`.

Estatus de una factura

InvoiceStatus

REGISTEREDRegistrada, aún sin timbrar

CONFIRMEDConfirmada, en espera de timbrarse

INVOICEDTimbrada y vigente; la única a la que se aplican cobros

CANCELLATION_REQUESTEDCancelación solicitada al SAT, en espera de respuesta

CANCELLEDCancelada

UNKNOWNSin equivalente, p. ej. una factura sustituida; revisa rawStatus

Ver InvoiceStatus

Lo que devuelve

InvoiceConnection!

nodes[Invoice]Las facturas de esta página. La forma más corta de leerlas.

edges[InvoiceEdge]Las mismas facturas, cada una 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 Invoice

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador de la factura; úsalo con `invoice(id:)` y en las aplicaciones de `createCollection`.
`folio`String	String	Folio de la factura con su serie, p. ej. `FMTY26100154`.
`uuid`String	String	Folio fiscal (UUID) del CFDI; `null` mientras la factura no se timbra.
`status`InvoiceStatus!	InvoiceStatus!	Estatus de la factura.
`issuedAt`DateTime	DateTime	Fecha y hora de emisión de la factura.
`dueDate`Date	Date	Fecha de vencimiento del pago de la factura. No se borra al cobrarse: la factura está vencida si esta fecha ya pasó y `balance` es mayor que cero. Llega `null` si la factura no tiene cuenta por cobrar.
`customer`Customer	Customer	Cliente de la factura.
`currency`String	String	Clave SAT de la moneda de la factura, p. ej. `MXN` o `USD`.
`total`Money	Money	Total de la factura.
`paid`Money	Money	Lo cobrado de la factura (`total` menos `balance`); `null` cuando `balance` es `null`.
`balance`Money	Money	Saldo por cobrar, en la moneda de la factura. Llega `null` si la factura no tiene cuenta por cobrar en AdvantaCloud.
`orders`OrderConnection	OrderConnection	Órdenes de venta incluidas en la factura, de la más antigua a la más reciente. Requiere «Ventas» en la llave; sin él llega `null`.20 por omisión, hasta 100 por página.

Ver todos los campos de Invoice

Paginación

first · after

Pide hasta 100 facturas 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 facturas entre páginas. Más sobre paginación.

Las facturas llegan por su última modificación, de la más antigua a la más reciente. Una factura que se modifica mientras recorres la lista pasa al final y puede llegar otra vez: guárdalas por id. Aplicarle un cobro cambia su saldo, pero no la cambia de lugar.

Permisos

Llave API Integraciones

Facturación

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`	Un argumento escrito en la consulta no tiene el tipo esperado: una fecha que no es `AAAA-MM-DD` o un estatus fuera de `InvoiceStatus`. 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.	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