Clientes — Crear y Actualizar

Crea clientes nuevos y actualiza los existentes con actualizaciones parciales.

---

Crear cliente

POST/apidev/v1/clients

PermisoAPICLI_CLIENTS_WRITE

Límite de solicitudes10 solicitudes/min

Alta o actualización según external_code

Los clientes son únicos por external_code dentro de tu compañía. Si ya existe un cliente con ese mismo external_code, la solicitud no crea un duplicado: devuelve ese cliente existente, con created: false en la respuesta.

Cuando hay coincidencia, solo se actualizan name y zip_code con los valores que mandaste. El resto de los campos del cliente existente queda intacto — para cambiar los demás, encadená un Actualizar cliente con el id que te devolvió.

Si omitís external_code, se usa el name del cliente (en mayúsculas) como código externo — así que volver a dar de alta el mismo nombre también cae sobre el cliente existente.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Máx	Descripción
name	string	Sí	200	Nombre para mostrar del cliente.
external_code	string	No	120	Identificador del sistema externo.
status	string	No	10	Estado del cliente.
document	string	No	60	Número de documento.
document_type	number	No	—	Identificador del tipo de documento.
business_name	string	No	200	Razón social.
tax_id	string	No	60	Número de identificación fiscal.
phone	string	No	60	Número de teléfono.
mobile	string	No	60	Teléfono móvil.
email	string	No	200	Dirección de correo electrónico.
notes	string	No	1000	Notas de texto libre.
image_url	string	No	500	URL de la imagen.
street	string	No	200	Nombre de la calle.
door_number	string	No	20	Número de puerta.
apartment	string	No	20	Apartamento o unidad.
corner	string	No	200	Esquina.
zip_code	string	No	20	Código postal.
latitude	number	No	—	Coordenada de latitud.
longitude	number	No	—	Coordenada de longitud.
country_id	string	No	30	ID del país.
department_id	string	No	30	ID del departamento.

Ejemplos de código

cURL

curl -s -X POST "https://$TENANT/apidev/v1/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Regional Distributors",
    "business_name": "Regional Distributors S.A.",
    "tax_id": "219900005018",
    "email": "info@regionaldist.com",
    "phone": "+59821009876",
    "street": "Bvar. Artigas",
    "door_number": "567",
    "country_id": "1",
    "department_id": "10"
  }'

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Regional Distributors',
      business_name: 'Regional Distributors S.A.',
      tax_id: '219900005018',
      email: 'info@regionaldist.com',
      phone: '+59821009876',
      street: 'Bvar. Artigas',
      door_number: '567',
      country_id: '1',
      department_id: '10',
    }),
  }
);
const { data } = await res.json();
console.log(`Created client: ${data.id}`);

Python

import requests

response = requests.post(
    f"https://{TENANT}/apidev/v1/clients",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "name": "Regional Distributors",
        "business_name": "Regional Distributors S.A.",
        "tax_id": "219900005018",
        "email": "info@regionaldist.com",
        "phone": "+59821009876",
        "street": "Bvar. Artigas",
        "door_number": "567",
        "country_id": "1",
        "department_id": "10",
    },
)
result = response.json()
print(f"Created client: {result['data']['id']}")

Campos de respuesta

Campo	Tipo	Descripción
id	string	Identificador único del cliente — el id del cliente nuevo, o el del cliente existente cuando la solicitud coincidió con uno por external_code.
created	boolean	true cuando se creó un cliente nuevo; false cuando se actualizó uno existente con el mismo external_code.

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "982710394857200005",
    "created": true
  }
}

---

Actualizar cliente

Actualiza un cliente existente. Solo se modifican los campos incluidos; los campos omitidos permanecen sin cambios. Enviá null para limpiar un campo que admita nulos.

Consultá Actualizaciones parciales para el patrón general.

PUT/apidev/v1/clients/{id}

PermisoAPICLI_CLIENTS_WRITE

Límite de solicitudes10 solicitudes/min

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	Identificador único del cliente.

Cuerpo de la solicitud

Se aceptan todos los campos de Crear cliente (ninguno requerido). Incluí solo los campos que quieras modificar.

Ejemplos de código

cURL

curl -s -X PUT "https://$TENANT/apidev/v1/clients/982710394857200005" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-info@regionaldist.com",
    "phone": "+59821005555",
    "notes": "Updated primary contact"
  }'

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients/982710394857200005`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'new-info@regionaldist.com',
      phone: '+59821005555',
      notes: 'Updated primary contact',
    }),
  }
);
const { data } = await res.json();
console.log(`Updated fields: ${data.updated_fields.join(', ')}`);

Python

import requests

response = requests.put(
    f"https://{TENANT}/apidev/v1/clients/982710394857200005",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "email": "new-info@regionaldist.com",
        "phone": "+59821005555",
        "notes": "Updated primary contact",
    },
)
result = response.json()
print(f"Updated: {result['data']['updated_fields']}")

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "982710394857200005",
    "updated_fields": ["email", "phone", "notes"]
  },
  "meta": {}
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos.
UNAUTHORIZED	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso requerido.
NOT_FOUND	404	Recurso no encontrado (endpoint de actualización).
RATE_LIMITED	429	Se superaron 10 solicitudes/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionado

• Autenticación
• Listado y Detalle de Clientes
• API de Cuentas
• Actualizaciones parciales
• Límites de solicitudes
• Manejo de errores