Cambiar ID externo de una empresa
curl --request POST \
--url http://api.gu1.ai/entities/change-external-id \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
'import requests
url = "http://api.gu1.ai/entities/change-external-id"
payload = {
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: {},
externalId: '<string>',
taxId: '<string>',
newExternalId: '<string>',
reason: '<string>'
})
};
fetch('http://api.gu1.ai/entities/change-external-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/change-external-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => [
],
'externalId' => '<string>',
'taxId' => '<string>',
'newExternalId' => '<string>',
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/change-external-id"
payload := strings.NewReader("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/change-external-id")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/change-external-id")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyReferencia API
Cambiar ID externo de una empresa
Asigna un nuevo identificador externo a una empresa en gu1 con motivo de auditoría obligatorio; actualiza referencias desnormalizadas en transacciones.
POST
/
entities
/
change-external-id
Cambiar ID externo de una empresa
curl --request POST \
--url http://api.gu1.ai/entities/change-external-id \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
'import requests
url = "http://api.gu1.ai/entities/change-external-id"
payload = {
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: {},
externalId: '<string>',
taxId: '<string>',
newExternalId: '<string>',
reason: '<string>'
})
};
fetch('http://api.gu1.ai/entities/change-external-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/change-external-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => [
],
'externalId' => '<string>',
'taxId' => '<string>',
'newExternalId' => '<string>',
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/change-external-id"
payload := strings.NewReader("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/change-external-id")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/change-external-id")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyDescripción
Este endpoint cambia el external ID de una entidad. No es posible hacerlo conPATCH /entities/:id, PATCH /entities/by-external-id/:externalId ni PATCH /entities/by-tax-id/:taxId (esos cuerpos ignoran externalId).
- Comprueba unicidad del nuevo ID en la organización.
- Actualiza la fila de la entidad.
- Si el ID anterior no estaba vacío y cambia, actualiza las referencias en transacciones (
origin_external_id/destination_external_id) y user events (entity_external_id, incluidas las filas ligadas porentity_id). La ficha se guarda en el momento. El historial se actualiza por lotes cortos, así un volumen grande no bloquea el request.externalIdPropagationvaledonesi esa reescritura terminó antes de la respuesta, orunningsi sigue. Las transacciones nuevas ya usan el ID nuevo. Las filas viejas que todavía tienen el ID anterior se alcanzan mientras el campo está enrunning.
externalIdChangeReason, source: change_external_id_endpoint).
Endpoint
POST https://api.gu1.ai/entities/change-external-id
Cuerpo de la petición
Indica exactamente uno de los campos de búsqueda, más el nuevo valor y el motivo.Solo búsqueda: tax ID de una entidad que ya tenga tax ID guardado y no vacío. Si hay varias coincidencias →
409 AMBIGUOUS_TAX_ID_LOOKUP; usar entityId o externalId.Nuevo identificador externo (se recorta en servidor). No puede estar en uso por otra entidad.
Respuesta
success: booleanchanged:falsesi el nuevo valor es igual al actual (sin cambios)entity: objeto entidad actualizadoexternalIdPropagation: solo sichangedestrue.donesi el historial de transacciones y eventos ya usa el ID nuevo.runningsi la ficha ya cambió y el historial sigue actualizándose. Las transacciones nuevas usan el ID nuevo en ambos casos.
Ejemplo
{
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"newExternalId": "crm_cliente_8842",
"reason": "Migración CRM — alinear con ID del sistema origen"
}
Was this page helpful?