Árbol del API · Facturas y cobranza › invoice

Detalle de una factura

invoice

Tipo

Query

Devuelve

InvoiceDetail

Permiso de la llave

Facturación

Estable

Devuelve una factura por su id, con su saldo y las ligas para descargar el XML del CFDI y su PDF.

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

Descargas

xmlUrl trae el XML del CFDI tal como se timbró y pdfUrl, el PDF con el formato de la empresa. Las dos llegan sólo si la factura está timbrada, y el XML pide además el permiso «Consultar XML de Factura» en la llave.

Las ligas están firmadas, vencen a los 10 minutos y no llevan el header Authorization: descarga el archivo desde tu servidor en cuanto lo pidas, sin compartir la liga. Al descargar, AdvantaCloud vuelve a revisar que la llave exista y conserve sus permisos: si la liga venció o la llave perdió el permiso, responde HTTP 403. Para una liga nueva, vuelve a pedir la factura.

invoice(
  id: ID!
): InvoiceDetail

# factura.graphql
query Factura($id: ID!) {
  invoice(id: $id) {
    id
    folio
    uuid
    status
    currency
    total
    balance
    xmlUrl
    pdfUrl
  }
}

Variables: {"id": "73015"}

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

import os, requests

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

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

<?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('factura.graphql'),
        'variables' => ['id' => '73015'],
    ]),
]);
$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']['invoice'];

Respuesta 200 OK

{
  "data": {
    "invoice": {
      "id": "73015",
      "folio": "FMTY26100154",
      "uuid": "3F2A9C1E-7B4D-4E8A-9C21-0A5B6D7E8F90",
      "status": "INVOICED",
      "currency": "MXN",
      "total": "4872.00",
      "balance": "4872.00",
      "xmlUrl": "https://mi-empresa.advantacloud.com/graphql/field-download?token=eyJfcmFpbHMiOnsiZGF0YSI6eyJpZCI6NzMwMTV9fX0%3D--9f2c4e7a1b",
      "pdfUrl": "https://mi-empresa.advantacloud.com/graphql/field-download?token=eyJfcmFpbHMiOnsiZGF0YSI6eyJpZCI6NzMwMTZ9fX0%3D--3d8b0a5c62"
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`id`ID!	ID!	Identificador de la factura, el mismo `id` que llega en `invoicesConnection` o en las aplicaciones de un cobro. Obligatorio.

Lo que devuelve

InvoiceDetail

Campos principales de InvoiceDetail:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador de la factura.
`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.
`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.
`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.
`xmlUrl`String	String	Liga para descargar el XML del CFDI timbrado. Está firmada y vence a los 10 minutos. Llega `null` si la factura no está timbrada. Requiere «Consultar XML de Factura» en la llave; sin él llega `null`.
`pdfUrl`String	String	Liga para descargar el PDF de la factura, que se genera al descargarlo con el formato de la empresa. Está firmada y vence a los 10 minutos. Llega `null` si la factura no está timbrada.
`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 InvoiceDetail

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 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 una factura 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