Árbol del API · Clientes › upsertCustomerAddress

Registrar o actualizar un lugar de entrega

upsertCustomerAddress

Tipo

Mutation

Devuelve

UpsertCustomerAddressPayload

Permiso de la llave

Creacion de Cliente

Reintentos

Seguros con idempotencyKey

Estable

Registra un lugar de entrega nuevo para un cliente o actualiza uno que ya tiene, y devuelve el lugar de entrega como quedó.

Con el id que devuelve, el lugar de entrega queda disponible para las órdenes del cliente: aparece en addresses de orderDefaults y se envía en addressId al crear la orden con createOrder.

Al actualizar, envía otra vez todos los datos obligatorios, no sólo los que cambian. Si omites interiorNumber, se conserva el que tenía.

El lugar de entrega que devuelve trae la clave, la calle, la ciudad, el estado y el código postal. El número exterior e interior, la colonia, el municipio, el país y la descripción se guardan, pero CustomerAddress no los devuelve.

Reintentos seguros

Si la conexión se corta y no sabes si el cambio se guardó, repite la petición con la misma idempotencyKey, la misma llave y exactamente el mismo input: recibes el lugar de entrega como está en ese momento, sin duplicarlo. Una clave repetida con datos distintos responde CONFLICT; un dato omitido y uno enviado en null cuentan como distintos. Si la petición se rechazó por un dato inválido, la clave no queda usada. Las claves se recuerdan alrededor de 30 días.

upsertCustomerAddress(
  input: CustomerAddressInput!  idempotencyKey: String!
): UpsertCustomerAddressPayload

# lugar-de-entrega.graphql
mutation LugarDeEntrega($input: CustomerAddressInput!, $clave: String!) {
  upsertCustomerAddress(input: $input, idempotencyKey: $clave) {
    address { id code street city state zip }
    errors { field code message }
  }
}

jq -n --rawfile q lugar-de-entrega.graphql \
  '{query: $q, variables: {"clave":"lugar-1215-bod-apo","input":{"customerId":"1215","code":"BOD-APO","description":"Bodega Apodaca, recibe de 8 a 14 h","street":"Av. Industrias","exteriorNumber":"410","neighborhood":"Parque Industrial Apodaca","municipality":"Apodaca","city":"Apodaca","state":"NLE","zip":"66600","country":"MX"}}}' |
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("lugar-de-entrega.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: "lugar-1215-bod-apo",
      input: {
        customerId: "1215",
        code: "BOD-APO",
        description: "Bodega Apodaca, recibe de 8 a 14 h",
        street: "Av. Industrias",
        exteriorNumber: "410",
        neighborhood: "Parque Industrial Apodaca",
        municipality: "Apodaca",
        city: "Apodaca",
        state: "NLE",
        zip: "66600",
        country: "MX",
      },
    },
  }),
});
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.upsertCustomerAddress.errors.length) throw new Error(data.upsertCustomerAddress.errors[0].code);
console.log(data.upsertCustomerAddress);

import os, requests

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

r = requests.post(URL, headers=HEADERS, timeout=30, json={
    "query": QUERY,
    "variables": {
        "clave": "lugar-1215-bod-apo",
        "input": {
            "customerId": "1215",
            "code": "BOD-APO",
            "description": "Bodega Apodaca, recibe de 8 a 14 h",
            "street": "Av. Industrias",
            "exteriorNumber": "410",
            "neighborhood": "Parque Industrial Apodaca",
            "municipality": "Apodaca",
            "city": "Apodaca",
            "state": "NLE",
            "zip": "66600",
            "country": "MX",
        },
    },
})
r.raise_for_status()
body = r.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
if body["data"]["upsertCustomerAddress"]["errors"]:
    raise RuntimeError(body["data"]["upsertCustomerAddress"]["errors"][0]["code"])
print(body["data"]["upsertCustomerAddress"])

<?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('lugar-de-entrega.graphql'),
        'variables' => [
            'clave' => 'lugar-1215-bod-apo',
            'input' => [
                'customerId' => '1215',
                'code' => 'BOD-APO',
                'description' => 'Bodega Apodaca, recibe de 8 a 14 h',
                'street' => 'Av. Industrias',
                'exteriorNumber' => '410',
                'neighborhood' => 'Parque Industrial Apodaca',
                'municipality' => 'Apodaca',
                'city' => 'Apodaca',
                'state' => 'NLE',
                'zip' => '66600',
                'country' => 'MX',
            ],
        ],
    ]),
]);
$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']['upsertCustomerAddress'];
if (!empty($resultado['errors'])) {
    throw new RuntimeException($resultado['errors'][0]['code']);
}

Variables

{
  "clave": "lugar-1215-bod-apo",
  "input": {
    "customerId": "1215",
    "code": "BOD-APO",
    "description": "Bodega Apodaca, recibe de 8 a 14 h",
    "street": "Av. Industrias",
    "exteriorNumber": "410",
    "neighborhood": "Parque Industrial Apodaca",
    "municipality": "Apodaca",
    "city": "Apodaca",
    "state": "NLE",
    "zip": "66600",
    "country": "MX"
  }
}

Respuesta 200 OK

{
  "data": {
    "upsertCustomerAddress": {
      "address": {
        "id": "141",
        "code": "BOD-APO",
        "street": "Av. Industrias",
        "city": "Apodaca",
        "state": "NLE",
        "zip": "66600"
      },
      "errors": []
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Lugar de entrega
`input`CustomerAddressInput!	CustomerAddressInput!	Los datos del lugar de entrega. Con `input.id` actualiza ese lugar de entrega; sin él registra uno nuevo. Ver `CustomerAddressInput`. Obligatorio.
Reintentos
`idempotencyKey`String!	String!	Clave única que generas por cada registro o cambio, por ejemplo un UUID, de hasta 200 caracteres. Si repites la petición con la misma clave y los mismos datos, recibes el lugar de entrega que ya se guardó en lugar de otro nuevo. Obligatorio.

Lo que devuelve

UpsertCustomerAddressPayload

Campos principales de UpsertCustomerAddressPayload:

Campo	Tipo	Descripción
`address`CustomerAddress	CustomerAddress	El lugar de entrega como quedó guardado; `null` si hubo errores.
`errors`[FieldError!]!	[FieldError!]!	Errores de los datos, cada uno con el dato que lo causó. Lista vacía si se guardó.

Ver todos los campos de UpsertCustomerAddressPayload

Permisos

Llave API Integraciones

Creacion de Cliente

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 «Creacion de Cliente». La respuesta es HTTP 422 con el cuerpo `{"error": "invalid_graphql_request"}`, sin `data`.	La llave necesita ese permiso; reintentar no ayuda.
`VALIDATION`	Un dato obligatorio llega vacío, o la `idempotencyKey` está vacía o pasa de 200 caracteres. Llega en `upsertCustomerAddress.errors` con el dato en `field` (por ejemplo `exteriorNumber` o `idempotencyKey`) y `address` llega `null`.	Corrige el dato y vuelve a enviar.
`NOT_FOUND`	El cliente no existe, o `input.id` no es un lugar de entrega de ese cliente. Llega en `errors` de la respuesta.	Revisa `customerId` e `input.id`.
`CONFLICT`	La `idempotencyKey` ya se usó con otros datos.	Para otros datos usa otra clave.
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