Árbol del API · Facturas y cobranza › createCollection

Registrar un cobro

createCollection

Tipo

Mutation

Devuelve

CreateCollectionPayload

Permiso de la llave

Crear Cobros

Reintentos

Seguros con idempotencyKey

Estable

Registra un pago recibido de un cliente y, si lo indicas, lo aplica a sus facturas en la misma operación. No emite ni timbra el complemento de pago.

El cobro se registra a nombre del usuario de input.userId, en la moneda de la cuenta bancaria (bankAccountId). Sin aplicaciones queda REGISTERED; con ellas queda APPLIED si se aplicó todo su importe o PARTIALLY_APPLIED si no, y cada factura baja su saldo (balance) en ese momento. Lo que no apliques se puede aplicar después en AdvantaCloud; con Llave API un cobro no se modifica ni se cancela.

Revisa siempre createCollection.errors y también errors de la respuesta: un error puede llegar en cualquiera de los dos y, con errores, collection llega null. Es todo o nada: si una aplicación falla, no se guardan el cobro, sus aplicaciones ni la clave.

Aplicaciones a facturas

Cada aplicación lleva el id de la factura y el importe en la moneda del cobro. Para que se acepte:

la factura es del cliente del cobro y está timbrada (INVOICED), con sus datos fiscales completos;
es de la misma unidad de negocio del cobro (la del almacén o xcumId), salvo que la empresa permita repartir cobros entre unidades de negocio;
el importe, convertido a la moneda de la factura, no pasa de su saldo (en una factura de venta mostrador, tampoco del saldo de su orden), y las aplicaciones juntas no pasan del importe del cobro;
cada factura aparece una sola vez.

Las facturas con saldo de un cliente están en invoicesConnection con customerId y onlyPending: true.

Moneda y tipo de cambio

La moneda del cobro es la de la cuenta bancaria. El tipo de cambio va en pesos por unidad de la moneda extranjera; si no envías exchangeRate, se usa el vigente en AdvantaCloud para esa moneda, y si no hay uno vigente la petición responde HTTP 422.

Misma moneda que la factura: se aplica el mismo importe.
Cobro en otra moneda a una factura en la moneda base de la empresa (p. ej. USD a MXN): AdvantaCloud convierte el importe con el tipo de cambio del cobro.
Cobro en pesos a una factura en dólares: sólo si envías exchangeRate, distinto de 1.
Cualquier otra combinación responde CONFLICT.

Cobros con tarjeta

Si la forma de cobro tiene card: true, envía en terminalId una terminal activa de bankTerminals(warehouseId:, bankAccountId:), con el almacén y la cuenta del cobro; esa consulta pide además «Ventas» en la llave. Si la terminal tiene cuenta bancaria o empresa, deben ser las del cobro (la empresa del cobro es la de su unidad de negocio: la del almacén o la de xcumId). Su error llega con field: "xvtb". Con otra forma de cobro, terminalId se ignora.

Catálogos

Los identificadores del input salen de estas consultas:

formas de cobro, con su marca card: paymentMethodOptions;
almacenes: warehouseOptions;
unidades de negocio, cobradores y tipos de cobro: businessUnitOptions, collectorOptions y collectionTypeOptions;
terminales de un cobro con tarjeta: bankTerminals. Una terminal con cuenta trae también su cuenta bancaria y su banco (bankAccount.id y bank.id).

Los bancos y las cuentas bancarias de la empresa no tienen una consulta publicada. Pide al administrador de AdvantaCloud los identificadores de la cuenta donde la empresa recibe los pagos y de su banco, y guárdalos en la configuración de tu integración.

Complemento de pago

Registrar el cobro no emite ni timbra el complemento de pago (REP): la empresa lo genera y lo timbra en AdvantaCloud. Consulta si el cobro ya está en uno, su estado y sus descargas con paymentComplement(collectionId:).

Reintentos seguros

Si la conexión se corta y no sabes si el cobro se registró, repite la petición con la misma idempotencyKey y los mismos datos: recibes el cobro que ya se registró, sin duplicarlo. La respuesta muestra el cobro como está en ese momento, no una copia de la primera respuesta. La clave se recuerda alrededor de 30 días. Una clave repetida con datos distintos, o desde otra llave, responde CONFLICT.

Si el registro falla, no se guardan el cobro ni la clave: corrige el dato y reenvía con la misma. Un error al leer la respuesta, como un first negativo en applications, llega cuando el cobro ya se guardó; ante cualquier duda, reintenta con la misma clave y los mismos datos.

createCollection(
  input: CollectionInput!  idempotencyKey: String!
): CreateCollectionPayload

# registrar-cobro.graphql
mutation RegistrarCobro($input: CollectionInput!, $clave: String!) {
  createCollection(input: $input, idempotencyKey: $clave) {
    collection {
      id
      status
      amount
      currency
      applications {
        nodes {
          invoice { folio balance }
          amount
        }
      }
    }
    errors { field code message }
  }
}

jq -n --rawfile q registrar-cobro.graphql \
  '{query: $q, variables: {"clave":"spei-7781203","input":{"userId":"35","customerId":"1311","warehouseId":"3","bankId":"4","bankAccountId":"9","paymentMethodId":"3","amount":"13432.00","date":"2026-10-24T10:15:00-06:00","reference":"SPEI 7781203","applications":[{"invoiceId":"73015","amount":"4872.00"},{"invoiceId":"72988","amount":"8560.00"}]}}}' |
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("registrar-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: {
      clave: "spei-7781203",
      input: {
        userId: "35",
        customerId: "1311",
        warehouseId: "3",
        bankId: "4",
        bankAccountId: "9",
        paymentMethodId: "3",
        amount: "13432.00",
        date: "2026-10-24T10:15:00-06:00",
        reference: "SPEI 7781203",
        applications: [
          { invoiceId: "73015", amount: "4872.00" },
          { invoiceId: "72988", amount: "8560.00" },
        ],
      },
    },
  }),
});
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);
if (data.createCollection.errors.length) throw new Error(data.createCollection.errors[0].code);
console.log(data.createCollection);

import os, requests

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

r = requests.post(URL, headers=HEADERS, timeout=30, json={
    "query": QUERY,
    "variables": {
        "clave": "spei-7781203",
        "input": {
            "userId": "35",
            "customerId": "1311",
            "warehouseId": "3",
            "bankId": "4",
            "bankAccountId": "9",
            "paymentMethodId": "3",
            "amount": "13432.00",
            "date": "2026-10-24T10:15:00-06:00",
            "reference": "SPEI 7781203",
            "applications": [
                {"invoiceId": "73015", "amount": "4872.00"},
                {"invoiceId": "72988", "amount": "8560.00"},
            ],
        },
    },
})
r.raise_for_status()
body = r.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
if body["data"]["createCollection"]["errors"]:
    raise RuntimeError(body["data"]["createCollection"]["errors"][0]["code"])
print(body["data"]["createCollection"])

<?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('registrar-cobro.graphql'),
        'variables' => [
            'clave' => 'spei-7781203',
            'input' => [
                'userId' => '35',
                'customerId' => '1311',
                'warehouseId' => '3',
                'bankId' => '4',
                'bankAccountId' => '9',
                'paymentMethodId' => '3',
                'amount' => '13432.00',
                'date' => '2026-10-24T10:15:00-06:00',
                'reference' => 'SPEI 7781203',
                'applications' => [
                    ['invoiceId' => '73015', 'amount' => '4872.00'],
                    ['invoiceId' => '72988', 'amount' => '8560.00'],
                ],
            ],
        ],
    ]),
]);
$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']['createCollection'];
if (!empty($resultado['errors'])) {
    throw new RuntimeException($resultado['errors'][0]['code']);
}

Variables

{
  "clave": "spei-7781203",
  "input": {
    "userId": "35",
    "customerId": "1311",
    "warehouseId": "3",
    "bankId": "4",
    "bankAccountId": "9",
    "paymentMethodId": "3",
    "amount": "13432.00",
    "date": "2026-10-24T10:15:00-06:00",
    "reference": "SPEI 7781203",
    "applications": [
      {
        "invoiceId": "73015",
        "amount": "4872.00"
      },
      {
        "invoiceId": "72988",
        "amount": "8560.00"
      }
    ]
  }
}

Respuesta 200 OK

{
  "data": {
    "createCollection": {
      "collection": {
        "id": "91530",
        "status": "APPLIED",
        "amount": "13432.00",
        "currency": "MXN",
        "applications": {
          "nodes": [
            {
              "invoice": {
                "folio": "FMTY26100154",
                "balance": "0.00"
              },
              "amount": "4872.00"
            },
            {
              "invoice": {
                "folio": "FMTY26100131",
                "balance": "0.00"
              },
              "amount": "8560.00"
            }
          ]
        }
      },
      "errors": []
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Cobro
`input`CollectionInput!	CollectionInput!	Los datos del cobro y sus aplicaciones a facturas (hasta 100). Ver `CollectionInput`. Obligatorio.
Reintentos
`idempotencyKey`String!	String!	Clave única que generas por cada cobro, de hasta 200 caracteres, por ejemplo un UUID o la referencia del pago en tu sistema. Si repites la petición con la misma clave y los mismos datos, recibes el cobro que ya se registró en lugar de uno nuevo. Obligatorio.

Lo que devuelve

CreateCollectionPayload

Campos principales de CreateCollectionPayload:

Campo	Tipo	Descripción
`collection`Collection	Collection	El cobro registrado, con sus aplicaciones; `null` si hubo errores.
`errors`[FieldError!]!	[FieldError!]!	Errores que impidieron registrar el cobro; vacía si se registró.

Ver todos los campos de CreateCollectionPayload

Permisos

Llave API Integraciones

Crear Cobros

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

Sin el permiso HTTP 422

La respuesta es HTTP 422 con el cuerpo {"error": "invalid_graphql_request"}, sin data.

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.
HTTP 422	La llave no tiene «Crear Cobros». La respuesta es HTTP 422 con el cuerpo `{"error": "invalid_graphql_request"}`, sin `data`.	La llave necesita ese permiso; reintentar no ayuda.
`NOT_FOUND`	Un identificador del `input` no existe. Llega en `createCollection.errors` con el dato en `field`: `customerId`, `warehouseId`, `bankId`, `bankAccountId` (también si la cuenta es de otro banco), `paymentMethodId`, `xcumId`, `cobdorId`, o `applications.0.invoiceId` para una factura que no existe, es de otro cliente o no tiene cuenta por cobrar (las aplicaciones se cuentan desde 0).	Corrige el identificador y vuelve a enviar; puedes usar la misma clave.
`VALIDATION`	Un dato no es válido. En `errors` de la respuesta: falta `userId` o el usuario no está activo, `amount` no es mayor que cero, hay más de 100 aplicaciones, una aplicación tiene importe cero o negativo o repite factura, `exchangeRate` no es mayor que cero o `tpcbro` no es `Cobro` ni `Anticipo`. En `createCollection.errors`: la terminal de un cobro con tarjeta falta, está inactiva o no es de la cuenta (`field: "xvtb"`), una aplicación pasa del saldo de su factura o las aplicaciones suman más que el cobro (`field: "base"`), o la `idempotencyKey` está vacía o pasa de 200 caracteres.	Corrige el dato y vuelve a enviar; puedes usar la misma clave.
`CONFLICT`	En `createCollection.errors`, con `field: "base"`: una factura no está timbrada (`INVOICED`) o le faltan datos fiscales, es de otra unidad de negocio, su moneda no se puede combinar con la del cobro, o estaba bloqueada por otra operación. En `errors` de la respuesta: la `idempotencyKey` ya se usó con otros datos o con otra llave.	Si es un bloqueo, reintenta con espera y la misma clave. Si no, corrige la aplicación, o usa otra clave para otros datos.
HTTP 422	Falla interna o dato rechazado al guardar. El cuerpo es `{"error": …}`, sin `data`.	Si no cambiaste nada, reintenta con la misma `idempotencyKey`.

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