> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# El objeto cliente

> Describe el objeto cliente y sus atributos, incluidos los datos de contacto, de dirección y de documento

Este objeto representa a un cliente que realizará pagos mediante tu servicio.

## Atributos

**id** `string`

El identificador único del cliente (MAX 64; MIN 36).

Ejemplo: faa89e18-5a11-11ed-9b6a-0242ac120002

**merchant\_customer\_id** `string`

El identificador único del cliente en el comercio externo (MAX 255; MIN 1).

Ejemplo: 50ca6f06-5a12-11ed-9b6a-0242ac120002

**merchant\_customer\_created\_at** `timestamp`

Fecha de registro del cliente en la plataforma del comercio (MAX 27; MIN 27 [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

**first\_name** `string`

El nombre del cliente (MAX 255; MIN 1).

Ejemplo: John

**last\_name** `string`

El apellido del cliente (MAX 255; MIN 1).

Ejemplo: Doe

**gender** `enum`

El género del cliente (MAX 2; MIN 1).

Valores posibles del enum: `M`, `F` o `NB`

**date\_of\_birth** `string`

La fecha de nacimiento del cliente en formato YYYY-MM-DD (MAX 10; MIN 10).

Ejemplo: 1990-02-28

**email** `string`

El email del cliente (MAX 255; MIN 3).

Ejemplo: [john.doe@email.com](mailto:john.doe@email.com)

**nationality** `enum`

La nacionalidad del cliente (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**country** `enum`

El país del cliente (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**document** `object`

Especifica el objeto de documento del cliente, incluido su número y tipo.

**propiedades**

**document\_number** `string`

El número de documento del cliente (MAX 40; MIN 3).

Ejemplo: 1093333333

**document\_type** `enum`

El tipo de documento del cliente (MAX 6; MIN 2).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**phone** `object`

Especifica el objeto de número de teléfono del cliente.

**propiedades**

**country\_code** `string`

El código de llamada del país del teléfono del cliente (MAX 3; MIN 1). Valores posibles: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

Ejemplo: 57

**number** `string`

El número de teléfono del cliente, sin el código de país (MAX 32; MIN 1).

Ejemplo: 3132450765

**billing\_address** `object`

Especifica el objeto de dirección de facturación del cliente.

**propiedades**

**address\_line\_1** `string`

La línea principal de la dirección de facturación del cliente (MAX 255; MIN 3).

Ejemplo: Calle 34 # 56 - 78

**address\_line\_2** `string`

La línea secundaria de la dirección de facturación del cliente (MAX 255; MIN 3).

Ejemplo: Apartamento 502, Torre I

**city** `string`

La ciudad considerada para la dirección de facturación (MAX 255; MIN 3).

Ejemplo: Bogotá

**country** `enum`

El país considerado para la dirección de facturación (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**state** `string`

El estado considerado para la dirección de facturación (MAX 255; MIN 3; [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) ).

Ejemplo: Cundinamarca

**zip\_code** `string`

El código postal considerado para la dirección de facturación (MAX 11; MIN 4).

Ejemplo: 111111

**neighborhood** `string`

El barrio de la línea de dirección del cliente (MAX 255; MIN 2)

Ejemplo: Barrio 11

**shipping\_address** `object`

Especifica el objeto de dirección de envío del cliente.

**propiedades**

**address\_line\_1** `string`

La línea principal de la dirección de envío del cliente (MAX 255; MIN 3).

Ejemplo: Calle 34 # 56 - 78

**address\_line\_2** `string`

La línea secundaria de la dirección de envío del cliente (MAX 255; MIN 3).

Ejemplo: Apartamento 502, Torre I

**city** `string`

La ciudad considerada para la dirección de envío (MAX 255; MIN 3).

Ejemplo: Bogotá

**country** `enum`

El país considerado para la dirección de envío (MAX 2; MIN 2; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) ).

Valores posibles del enum: consulta la [referencia de países](https://docs.y.uno/es/reference/country-reference.md).

**state** `string`

El estado considerado para la dirección de envío (MAX 255; MIN 3; [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) ).

Ejemplo: Cundinamarca

**zip\_code** `string`

El código postal considerado para la dirección de envío (MAX 10; MIN 5).

Ejemplo: 111111

**neighborhood** `string`

El barrio de la línea de dirección del cliente (MAX 255; MIN 2)

Ejemplo: Barrio 11

**metadata** `array of objects`

Especifica una lista de pares de clave y valor personalizados asociados al cliente (para referencias internas, segmentación o etiquetas de flujo de trabajo). Puedes agregar hasta 50 objetos de metadata.

**propiedades**

**metadata object** `object`

Especifica una clave de metadata y su valor correspondiente.

Úsalo para adjuntar contexto definido por el comercio (por ejemplo: `crm_id`, `segment`). Evita enviar datos sensibles o personales.

**propiedades**

**key** `string`

Especifica una clave de metadata.

Ejemplo: age

**value** `string`

Especifica el valor de la clave de metadata definida.

Ejemplo: 28

**created\_at** `timestamp`

Fecha y hora de creación del cliente (MAX 27; MIN 27; [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

**updated\_at** `timestamp`

Fecha y hora de la última actualización del cliente (MAX 27; MIN 27; [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ).

Ejemplo: 2022-05-09T20:46:54.786342Z

## Operaciones

* [Crear un cliente](https://docs.y.uno/es/reference/customers/create-customer.md)
* [Consultar un cliente](https://docs.y.uno/es/reference/customers/retrieve-customer.md)
* [Consultar por ID externo](https://docs.y.uno/es/reference/customers/retrieve-customer-by-external-id.md)
* [Actualizar un cliente](https://docs.y.uno/es/reference/customers/update-customer.md)
* [Eliminar un cliente](https://docs.y.uno/es/reference/customers/delete-customer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.