Árbol del API · Facturas y cobranza › paymentComplement

Complemento de pago de un cobro

paymentComplement

Tipo

Query

Devuelve

PaymentComplement

Permiso de la llave

Complemento de Pago

Estable

Devuelve el complemento de pago (REP) que incluye un cobro: el estado de su timbrado, su UUID y las ligas para descargar el XML y el PDF.

El complemento no se emite al registrar el cobro: la empresa lo genera y lo timbra en AdvantaCloud con cobros ya conciliados con el banco, y un mismo complemento puede amparar varios cobros del cliente en el mes. Mientras el cobro no esté en un complemento, la respuesta es paymentComplement: null sin error. Timbrar o reintentar el timbrado no está disponible con Llave API.

Si la llave no tiene el permiso, la respuesta también es null sin error; un cobro que no existe sí responde NOT_FOUND.

Estado del timbrado

stampStatus dice en qué punto está el timbrado y qué descargas llegan:

REGISTERED: el complemento existe, pero aún no se envía a timbrar. Sin descargas.
PENDING: se envió a timbrar y falta la respuesta del PAC; vuelve a consultar en unos segundos. Sin descargas.
STAMPED: timbrado, con UUID; es un CFDI válido. XML y PDF.
FAILED: el PAC o el SAT rechazó el timbrado; el motivo está en stampError y la empresa lo corrige y lo vuelve a enviar. Sin descargas.
CANCEL_REQUESTED: se solicitó su cancelación al SAT y falta la respuesta. XML y PDF.
CANCELLED: cancelado. Sólo XML.
UNKNOWN: un estatus sin equivalente; revisa rawStatus. Sin descargas.

Cuando se completa la cancelación de un complemento, el cobro queda libre y la consulta vuelve a responder null hasta que la empresa emita otro. Si la empresa lo sustituye, la consulta devuelve desde ese momento el complemento nuevo, con otro folio y, al timbrarse, otro UUID. Guarda el UUID que recibiste y compáralo en cada consulta.

Descargas

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, que conserve el permiso «Complemento de Pago» y que el complemento siga en un estado con esa descarga: si no, o si la liga ya venció, responde HTTP 403, y si el complemento ya no tiene su XML, HTTP 404. Para una liga nueva, repite la consulta.

paymentComplement(
  collectionId: ID!
): PaymentComplement

# complemento-de-pago.graphql
query ComplementoDePago($cobro: ID!) {
  paymentComplement(collectionId: $cobro) {
    id
    folio
    uuid
    stampStatus
    stampError
    stampedAt
    xmlUrl
    pdfUrl
  }
}

Variables: {"cobro": "91342"}

jq -n --rawfile q complemento-de-pago.graphql \
  '{query: $q, variables: {"cobro":"91342"}}' |
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("complemento-de-pago.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: { cobro: "91342" },
  }),
});
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.paymentComplement);

import os, requests

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

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

<?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('complemento-de-pago.graphql'),
        'variables' => ['cobro' => '91342'],
    ]),
]);
$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']['paymentComplement'];

Respuesta 200 OK

{
  "data": {
    "paymentComplement": {
      "id": "6120",
      "folio": "PF2610031",
      "uuid": "9B1E6C2A-4F3D-4A7B-8E5C-2D1F0A9B3C47",
      "stampStatus": "STAMPED",
      "stampError": null,
      "stampedAt": "2026-10-16T09:02:47.000000-06:00",
      "xmlUrl": "https://mi-empresa.advantacloud.com/graphql/field-download?token=eyJfcmFpbHMiOnsiZGF0YSI6eyJpZCI6NjEyMH19fQ%3D%3D--7a3e19c0d4",
      "pdfUrl": "https://mi-empresa.advantacloud.com/graphql/field-download?token=eyJfcmFpbHMiOnsiZGF0YSI6eyJpZCI6NjEyMX19fQ%3D%3D--c05b2f8e91"
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`collectionId`ID!	ID!	Identificador del cobro (`Collection.id`), no del complemento. Es el `id` que llega en `collectionsConnection`, `collection` o `createCollection`. Obligatorio.

Lo que devuelve

PaymentComplement

Campos principales de PaymentComplement:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador del complemento. Varios cobros del mismo cliente pueden compartirlo.
`folio`String	String	Folio del complemento con su serie, p. ej. `PF2610031`.
`uuid`String	String	Folio fiscal (UUID) del complemento; `null` mientras no se timbra.
`stampStatus`String!	String!	Estado del timbrado: `REGISTERED`, `PENDING`, `STAMPED`, `FAILED`, `CANCEL_REQUESTED`, `CANCELLED` o `UNKNOWN`. Sólo con `STAMPED` el complemento es un CFDI válido. Es texto, no un enum: trata un valor desconocido como `UNKNOWN`.
`stampError`String	String	Motivo por el que se rechazó el timbrado, cuando `stampStatus` es `FAILED`.
`stampedAt`DateTime	DateTime	Fecha y hora del timbrado que devolvió el PAC. Antes de timbrarse trae la fecha con la que el complemento se envió a timbrar.
`xmlUrl`String	String	Liga para descargar el XML timbrado. Llega con `STAMPED`, y con `CANCEL_REQUESTED` o `CANCELLED` si el complemento llegó a timbrarse; si no, `null`. Está firmada y vence a los 10 minutos. Requiere «Complemento de Pago» en la llave; sin él llega `null`.
`pdfUrl`String	String	Liga para descargar el PDF del complemento timbrado. Llega con `STAMPED`, y con `CANCEL_REQUESTED` si el complemento llegó a timbrarse; si no, `null`. Está firmada y vence a los 10 minutos. Requiere «Complemento de Pago» en la llave; sin él llega `null`.

Ver todos los campos de PaymentComplement

Permisos

Llave API Integraciones

Complemento de Pago

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 `collectionId` en la empresa.	Revisa que envías el `id` del cobro, no el del complemento.
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