> ## 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.

# Crear cliente

> Crea un recurso de cliente con datos personales, de facturación y de envío para iniciar el checkout

Esta solicitud crea un recurso de cliente. Debes proporcionar varios parámetros del cliente en el cuerpo de la solicitud, entre ellos el identificador único del cliente en el comercio externo, la información personal y las direcciones de facturación y de envío.

Al crear un cliente se genera un `id` de cliente que puedes usar para iniciar el checkout.

> [!NOTE]
>
> **`merchant_customer_id` tiene alcance de organización, no de cuenta**
>
> Si tu organización tiene varias cuentas, `merchant_customer_id` debe ser único entre todas ellas. Si creas un cliente desde una cuenta con un id que ya usa otra cuenta de la misma organización, se devuelve `CUSTOMER_ID_DUPLICATED`. Consulta [Cuentas](https://docs.y.uno/es/docs/using-yuno/organization/accounts.md#customers-and-payment-methods-are-organization-scoped) para saber cómo estructurar los ids si gestionas varias empresas dentro de una organización.

> [!WARNING]
>
> **Importante**
>
> Hay ciertos objetos que no son obligatorios al crear un "cliente". Sin embargo, cuanta más información proporciones, más puede ayudar a mejorar las tasas de aprobación, conversión y prevención del fraude.


## OpenAPI

````yaml openapi/es/customers/create-customer.json POST /customers
openapi: 3.1.0
info:
  title: customer-api
  version: 1.0.2
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /customers:
    post:
      summary: Crear cliente
      operationId: create-customer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - merchant_customer_id
              properties:
                merchant_customer_id:
                  type: string
                  description: >-
                    El identificador único del cliente en el comercio externo
                    (MAX 255; MIN 3). Es único por organización, no por cuenta:
                    reutilizar un id ya usado por otra cuenta de la misma
                    organización devuelve CUSTOMER_ID_DUPLICATED.
                merchant_customer_created_at:
                  type: string
                  description: >-
                    Fecha de registro del cliente en la plataforma del comercio
                    (MAX 27; MIN 27; [ISO
                    8601](https://en.wikipedia.org/wiki/ISO_8601))
                  format: date-time
                first_name:
                  type: string
                  description: El nombre del cliente (MAX 255; MIN 3).
                last_name:
                  type: string
                  description: El apellido del cliente (MAX 255; MIN 3).
                gender:
                  type: string
                  description: El género del cliente.
                date_of_birth:
                  type: string
                  description: >-
                    La fecha de nacimiento del cliente en formato YYYY-MM-DD
                    (MAX 10; MIN 10).
                email:
                  type: string
                  description: El correo electrónico del cliente (MAX 255; MIN 3).
                nationality:
                  type: string
                  description: >-
                    La nacionalidad del cliente (MAX 2; MIN 2; [ISO
                    3166-1](country-reference)).
                  enum:
                    - AF
                    - AX
                    - AL
                    - DZ
                    - AS
                    - AD
                    - AO
                    - AI
                    - AQ
                    - AG
                    - AR
                    - AM
                    - AW
                    - AU
                    - AT
                    - AZ
                    - BS
                    - BH
                    - BD
                    - BB
                    - BY
                    - BE
                    - BZ
                    - BJ
                    - BM
                    - BT
                    - BO
                    - BQ
                    - BA
                    - BW
                    - BV
                    - BR
                    - IO
                    - BN
                    - BG
                    - BF
                    - BI
                    - CV
                    - KH
                    - CM
                    - CA
                    - KY
                    - CF
                    - TD
                    - CL
                    - CN
                    - CX
                    - CC
                    - CO
                    - KM
                    - CG
                    - CD
                    - CK
                    - CR
                    - CI
                    - HR
                    - CU
                    - CW
                    - CY
                    - CZ
                    - DK
                    - DJ
                    - DM
                    - DO
                    - EC
                    - EG
                    - SZ
                    - GQ
                    - ER
                    - EE
                    - ET
                    - FK
                    - FO
                    - FJ
                    - FI
                    - FR
                    - GF
                    - PF
                    - TF
                    - GA
                    - GM
                    - GE
                    - DE
                    - GH
                    - GI
                    - GR
                    - GL
                    - GD
                    - GP
                    - GU
                    - GT
                    - GG
                    - GN
                    - GW
                    - GY
                    - HT
                    - HM
                    - VA
                    - HN
                    - HK
                    - HU
                    - IS
                    - IN
                    - ID
                    - IR
                    - IQ
                    - IE
                    - IM
                    - IL
                    - IT
                    - JM
                    - JP
                    - JE
                    - JO
                    - KZ
                    - KE
                    - KI
                    - KR
                    - KW
                    - KG
                    - LA
                    - LV
                    - LB
                    - LS
                    - LR
                    - LY
                    - LI
                    - LT
                    - LU
                    - MO
                    - MK
                    - MG
                    - MW
                    - MY
                    - MV
                    - ML
                    - MT
                    - MH
                    - MQ
                    - MR
                    - MU
                    - YT
                    - MX
                    - FM
                    - MD
                    - MC
                    - MN
                    - ME
                    - MS
                    - MA
                    - MZ
                    - MM
                    - NA
                    - NR
                    - NP
                    - NL
                    - NC
                    - NZ
                    - NI
                    - NE
                    - NG
                    - NU
                    - NF
                    - MP
                    - 'NO'
                    - OM
                    - PK
                    - PW
                    - PS
                    - PA
                    - PG
                    - PY
                    - PE
                    - PH
                    - PN
                    - PL
                    - PT
                    - PR
                    - QA
                    - RE
                    - RO
                    - RU
                    - RW
                    - BL
                    - SH
                    - KN
                    - LC
                    - MF
                    - PM
                    - VC
                    - WS
                    - SM
                    - ST
                    - SA
                    - SN
                    - RS
                    - SC
                    - SL
                    - SG
                    - SX
                    - SK
                    - SI
                    - SB
                    - SO
                    - ZA
                    - GS
                    - SS
                    - ES
                    - LK
                    - SD
                    - SR
                    - SJ
                    - SE
                    - CH
                    - SY
                    - TW
                    - TJ
                    - TZ
                    - TH
                    - TL
                    - TG
                    - TK
                    - TO
                    - TT
                    - TN
                    - TR
                    - TM
                    - TC
                    - TV
                    - UG
                    - UA
                    - AE
                    - GB
                    - US
                    - UM
                    - UY
                    - UZ
                    - VU
                    - VE
                    - VN
                    - VG
                    - VI
                    - WF
                    - EH
                    - YE
                    - ZM
                    - ZW
                country:
                  type: string
                  description: >-
                    El país del cliente (MAX 2; MIN 2; [ISO
                    3166-1](country-reference)).
                  enum:
                    - AF
                    - AX
                    - AL
                    - DZ
                    - AS
                    - AD
                    - AO
                    - AI
                    - AQ
                    - AG
                    - AR
                    - AM
                    - AW
                    - AU
                    - AT
                    - AZ
                    - BS
                    - BH
                    - BD
                    - BB
                    - BY
                    - BE
                    - BZ
                    - BJ
                    - BM
                    - BT
                    - BO
                    - BQ
                    - BA
                    - BW
                    - BV
                    - BR
                    - IO
                    - BN
                    - BG
                    - BF
                    - BI
                    - CV
                    - KH
                    - CM
                    - CA
                    - KY
                    - CF
                    - TD
                    - CL
                    - CN
                    - CX
                    - CC
                    - CO
                    - KM
                    - CG
                    - CD
                    - CK
                    - CR
                    - CI
                    - HR
                    - CU
                    - CW
                    - CY
                    - CZ
                    - DK
                    - DJ
                    - DM
                    - DO
                    - EC
                    - EG
                    - SZ
                    - GQ
                    - ER
                    - EE
                    - ET
                    - FK
                    - FO
                    - FJ
                    - FI
                    - FR
                    - GF
                    - PF
                    - TF
                    - GA
                    - GM
                    - GE
                    - DE
                    - GH
                    - GI
                    - GR
                    - GL
                    - GD
                    - GP
                    - GU
                    - GT
                    - GG
                    - GN
                    - GW
                    - GY
                    - HT
                    - HM
                    - VA
                    - HN
                    - HK
                    - HU
                    - IS
                    - IN
                    - ID
                    - IR
                    - IQ
                    - IE
                    - IM
                    - IL
                    - IT
                    - JM
                    - JP
                    - JE
                    - JO
                    - KZ
                    - KE
                    - KI
                    - KR
                    - KW
                    - KG
                    - LA
                    - LV
                    - LB
                    - LS
                    - LR
                    - LY
                    - LI
                    - LT
                    - LU
                    - MO
                    - MK
                    - MG
                    - MW
                    - MY
                    - MV
                    - ML
                    - MT
                    - MH
                    - MQ
                    - MR
                    - MU
                    - YT
                    - MX
                    - FM
                    - MD
                    - MC
                    - MN
                    - ME
                    - MS
                    - MA
                    - MZ
                    - MM
                    - NA
                    - NR
                    - NP
                    - NL
                    - NC
                    - NZ
                    - NI
                    - NE
                    - NG
                    - NU
                    - NF
                    - MP
                    - 'NO'
                    - OM
                    - PK
                    - PW
                    - PS
                    - PA
                    - PG
                    - PY
                    - PE
                    - PH
                    - PN
                    - PL
                    - PT
                    - PR
                    - QA
                    - RE
                    - RO
                    - RU
                    - RW
                    - BL
                    - SH
                    - KN
                    - LC
                    - MF
                    - PM
                    - VC
                    - WS
                    - SM
                    - ST
                    - SA
                    - SN
                    - RS
                    - SC
                    - SL
                    - SG
                    - SX
                    - SK
                    - SI
                    - SB
                    - SO
                    - ZA
                    - GS
                    - SS
                    - ES
                    - LK
                    - SD
                    - SR
                    - SJ
                    - SE
                    - CH
                    - SY
                    - TW
                    - TJ
                    - TZ
                    - TH
                    - TL
                    - TG
                    - TK
                    - TO
                    - TT
                    - TN
                    - TR
                    - TM
                    - TC
                    - TV
                    - UG
                    - UA
                    - AE
                    - GB
                    - US
                    - UM
                    - UY
                    - UZ
                    - VU
                    - VE
                    - VN
                    - VG
                    - VI
                    - WF
                    - EH
                    - YE
                    - ZM
                    - ZW
                document:
                  type: object
                  description: >-
                    Especifica el objeto de documento del cliente, con su número
                    y tipo. Este objeto no es obligatorio. Sin embargo, si
                    envías esta información, mejorarás la experiencia de pago de
                    tu usuario.
                  properties:
                    document_number:
                      type: string
                      description: >-
                        El número de documento del cliente (MAX 40; MIN 3). Este
                        campo es obligatorio si el objeto 'document' se incluye
                        en la solicitud.
                    document_type:
                      type: string
                      description: >-
                        El tipo de documento del cliente (MAX 6, MIN 3;
                        [Referencia de países](country-reference)).
                phone:
                  type: object
                  description: >-
                    Especifica el objeto de número de teléfono del cliente. Este
                    objeto no es obligatorio. Sin embargo, si envías esta
                    información, mejorarás la experiencia de pago de tu usuario.
                  properties:
                    country_code:
                      type: string
                      description: >-
                        El código de país del teléfono del cliente (MAX 3; MIN
                        1). Valores posibles: consulta la [Referencia de
                        países.](country-reference) Este campo es obligatorio si
                        el objeto 'phone' se incluye en la solicitud.
                    number:
                      type: string
                      description: >-
                        El número de teléfono del cliente, sin el código de país
                        (MAX 32; MIN 1). Este campo es obligatorio si la
                        solicitud incluye el objeto 'phone'.
                billing_address:
                  type: object
                  description: >-
                    Especifica el objeto de dirección de facturación del
                    cliente. Este objeto no es obligatorio. Sin embargo, si
                    envías esta información, mejorarás la experiencia de pago de
                    tu usuario.
                  properties:
                    address_line_1:
                      type: string
                      description: >-
                        La línea principal de la dirección de facturación del
                        cliente (MAX 255; MIN 3). Este campo es obligatorio si
                        la solicitud incluye el objeto 'billing_address'.
                    address_line_2:
                      type: string
                      description: >-
                        La línea secundaria de la dirección de facturación del
                        cliente (MAX 255; MIN 3).
                    building_number_1:
                      type: string
                      description: >-
                        El número principal del edificio del cliente (MAX 255;
                        MIN 3)
                    building_number_2:
                      type: string
                      description: >-
                        El número secundario del edificio del cliente (MAX 255;
                        MIN 3)
                    city:
                      type: string
                      description: >-
                        La ciudad de la dirección de facturación (MAX 255; MIN
                        3). Este campo es obligatorio si la solicitud incluye el
                        objeto 'billing_address'.
                    country:
                      type: string
                      description: >-
                        El país de la dirección de facturación (MAX 2; MIN 2;
                        [ISO 3166-1](country-reference)). Este campo es
                        obligatorio si la solicitud incluye el objeto
                        'billing_address'.
                      enum:
                        - AF
                        - AX
                        - AL
                        - DZ
                        - AS
                        - AD
                        - AO
                        - AI
                        - AQ
                        - AG
                        - AR
                        - AM
                        - AW
                        - AU
                        - AT
                        - AZ
                        - BS
                        - BH
                        - BD
                        - BB
                        - BY
                        - BE
                        - BZ
                        - BJ
                        - BM
                        - BT
                        - BO
                        - BQ
                        - BA
                        - BW
                        - BV
                        - BR
                        - IO
                        - BN
                        - BG
                        - BF
                        - BI
                        - CV
                        - KH
                        - CM
                        - CA
                        - KY
                        - CF
                        - TD
                        - CL
                        - CN
                        - CX
                        - CC
                        - CO
                        - KM
                        - CG
                        - CD
                        - CK
                        - CR
                        - CI
                        - HR
                        - CU
                        - CW
                        - CY
                        - CZ
                        - DK
                        - DJ
                        - DM
                        - DO
                        - EC
                        - EG
                        - SZ
                        - GQ
                        - ER
                        - EE
                        - ET
                        - FK
                        - FO
                        - FJ
                        - FI
                        - FR
                        - GF
                        - PF
                        - TF
                        - GA
                        - GM
                        - GE
                        - DE
                        - GH
                        - GI
                        - GR
                        - GL
                        - GD
                        - GP
                        - GU
                        - GT
                        - GG
                        - GN
                        - GW
                        - GY
                        - HT
                        - HM
                        - VA
                        - HN
                        - HK
                        - HU
                        - IS
                        - IN
                        - ID
                        - IR
                        - IQ
                        - IE
                        - IM
                        - IL
                        - IT
                        - JM
                        - JP
                        - JE
                        - JO
                        - KZ
                        - KE
                        - KI
                        - KR
                        - KW
                        - KG
                        - LA
                        - LV
                        - LB
                        - LS
                        - LR
                        - LY
                        - LI
                        - LT
                        - LU
                        - MO
                        - MK
                        - MG
                        - MW
                        - MY
                        - MV
                        - ML
                        - MT
                        - MH
                        - MQ
                        - MR
                        - MU
                        - YT
                        - MX
                        - FM
                        - MD
                        - MC
                        - MN
                        - ME
                        - MS
                        - MA
                        - MZ
                        - MM
                        - NA
                        - NR
                        - NP
                        - NL
                        - NC
                        - NZ
                        - NI
                        - NE
                        - NG
                        - NU
                        - NF
                        - MP
                        - 'NO'
                        - OM
                        - PK
                        - PW
                        - PS
                        - PA
                        - PG
                        - PY
                        - PE
                        - PH
                        - PN
                        - PL
                        - PT
                        - PR
                        - QA
                        - RE
                        - RO
                        - RU
                        - RW
                        - BL
                        - SH
                        - KN
                        - LC
                        - MF
                        - PM
                        - VC
                        - WS
                        - SM
                        - ST
                        - SA
                        - SN
                        - RS
                        - SC
                        - SL
                        - SG
                        - SX
                        - SK
                        - SI
                        - SB
                        - SO
                        - ZA
                        - GS
                        - SS
                        - ES
                        - LK
                        - SD
                        - SR
                        - SJ
                        - SE
                        - CH
                        - SY
                        - TW
                        - TJ
                        - TZ
                        - TH
                        - TL
                        - TG
                        - TK
                        - TO
                        - TT
                        - TN
                        - TR
                        - TM
                        - TC
                        - TV
                        - UG
                        - UA
                        - AE
                        - GB
                        - US
                        - UM
                        - UY
                        - UZ
                        - VU
                        - VE
                        - VN
                        - VG
                        - VI
                        - WF
                        - EH
                        - YE
                        - ZM
                        - ZW
                    state:
                      type: string
                      description: >-
                        El estado considerado para la dirección de facturación
                        (MAX 255; MIN 3).
                    zip_code:
                      type: string
                      description: >-
                        El código postal considerado para la dirección de
                        facturación (MAX 10; MIN 5).
                    neighborhood:
                      type: string
                      description: >-
                        El barrio de la línea de dirección del cliente (MAX 255;
                        MIN 1).
                  required:
                    - address_line_1
                    - city
                shipping_address:
                  type: object
                  description: >-
                    Especifica el objeto de dirección de envío del cliente. Este
                    objeto no es obligatorio. Sin embargo, si envías esta
                    información, mejorarás la experiencia de pago de tu usuario.
                  properties:
                    address_line_1:
                      type: string
                      description: >-
                        La línea principal de la dirección de envío del cliente
                        (MAX 255; MIN 3). Este campo es obligatorio si la
                        solicitud incluye el objeto 'shipping_address'.
                    address_line_2:
                      type: string
                      description: >-
                        La línea secundaria de la dirección de envío del cliente
                        (MAX 255; MIN 3).
                    building_number_1:
                      type: string
                      description: >-
                        El número principal del edificio del cliente (MAX 255;
                        MIN 3)
                    building_number_2:
                      type: string
                      description: >-
                        El número secundario del edificio del cliente (MAX 255;
                        MIN 3)
                    city:
                      type: string
                      description: >-
                        La ciudad de la dirección de envío (MAX 255; MIN 3).
                        Este campo es obligatorio si la solicitud incluye el
                        objeto 'shipping_address'.
                    country:
                      type: string
                      description: >-
                        El país considerado para la dirección de envío (MAX 2;
                        MIN 2; [ISO 3166-1](country-reference)). Este campo es
                        obligatorio si el objeto 'shipping_address' se incluye
                        en la solicitud.
                      enum:
                        - AF
                        - AX
                        - AL
                        - DZ
                        - AS
                        - AD
                        - AO
                        - AI
                        - AQ
                        - AG
                        - AR
                        - AM
                        - AW
                        - AU
                        - AT
                        - AZ
                        - BS
                        - BH
                        - BD
                        - BB
                        - BY
                        - BE
                        - BZ
                        - BJ
                        - BM
                        - BT
                        - BO
                        - BQ
                        - BA
                        - BW
                        - BV
                        - BR
                        - IO
                        - BN
                        - BG
                        - BF
                        - BI
                        - CV
                        - KH
                        - CM
                        - CA
                        - KY
                        - CF
                        - TD
                        - CL
                        - CN
                        - CX
                        - CC
                        - CO
                        - KM
                        - CG
                        - CD
                        - CK
                        - CR
                        - CI
                        - HR
                        - CU
                        - CW
                        - CY
                        - CZ
                        - DK
                        - DJ
                        - DM
                        - DO
                        - EC
                        - EG
                        - SZ
                        - GQ
                        - ER
                        - EE
                        - ET
                        - FK
                        - FO
                        - FJ
                        - FI
                        - FR
                        - GF
                        - PF
                        - TF
                        - GA
                        - GM
                        - GE
                        - DE
                        - GH
                        - GI
                        - GR
                        - GL
                        - GD
                        - GP
                        - GU
                        - GT
                        - GG
                        - GN
                        - GW
                        - GY
                        - HT
                        - HM
                        - VA
                        - HN
                        - HK
                        - HU
                        - IS
                        - IN
                        - ID
                        - IR
                        - IQ
                        - IE
                        - IM
                        - IL
                        - IT
                        - JM
                        - JP
                        - JE
                        - JO
                        - KZ
                        - KE
                        - KI
                        - KR
                        - KW
                        - KG
                        - LA
                        - LV
                        - LB
                        - LS
                        - LR
                        - LY
                        - LI
                        - LT
                        - LU
                        - MO
                        - MK
                        - MG
                        - MW
                        - MY
                        - MV
                        - ML
                        - MT
                        - MH
                        - MQ
                        - MR
                        - MU
                        - YT
                        - MX
                        - FM
                        - MD
                        - MC
                        - MN
                        - ME
                        - MS
                        - MA
                        - MZ
                        - MM
                        - NA
                        - NR
                        - NP
                        - NL
                        - NC
                        - NZ
                        - NI
                        - NE
                        - NG
                        - NU
                        - NF
                        - MP
                        - 'NO'
                        - OM
                        - PK
                        - PW
                        - PS
                        - PA
                        - PG
                        - PY
                        - PE
                        - PH
                        - PN
                        - PL
                        - PT
                        - PR
                        - QA
                        - RE
                        - RO
                        - RU
                        - RW
                        - BL
                        - SH
                        - KN
                        - LC
                        - MF
                        - PM
                        - VC
                        - WS
                        - SM
                        - ST
                        - SA
                        - SN
                        - RS
                        - SC
                        - SL
                        - SG
                        - SX
                        - SK
                        - SI
                        - SB
                        - SO
                        - ZA
                        - GS
                        - SS
                        - ES
                        - LK
                        - SD
                        - SR
                        - SJ
                        - SE
                        - CH
                        - SY
                        - TW
                        - TJ
                        - TZ
                        - TH
                        - TL
                        - TG
                        - TK
                        - TO
                        - TT
                        - TN
                        - TR
                        - TM
                        - TC
                        - TV
                        - UG
                        - UA
                        - AE
                        - GB
                        - US
                        - UM
                        - UY
                        - UZ
                        - VU
                        - VE
                        - VN
                        - VG
                        - VI
                        - WF
                        - EH
                        - YE
                        - ZM
                        - ZW
                    state:
                      type: string
                      description: >-
                        El estado considerado para la dirección de envío (MAX
                        255; MIN 3).
                    zip_code:
                      type: string
                      description: >-
                        El código postal considerado para la dirección de envío
                        (MAX 10; MIN 5).
                    neighborhood:
                      type: string
                      description: >-
                        El barrio de la línea de dirección del cliente (MAX 255;
                        MIN 1).
                  required:
                    - address_line_1
                    - city
                    - country
                metadata:
                  type: array
                  description: >-
                    Especifica una lista de objetos de metadatos. Puedes agregar
                    hasta 50 objetos de metadatos.
                  items:
                    properties:
                      key:
                        type: string
                        description: La clave de la metadata (MAX 48).
                      value:
                        type: string
                        description: El valor de la clave de la metadata (MAX 512).
                    required:
                      - key
                      - value
                    type: object
            examples:
              Customer (full data):
                value:
                  merchant_customer_id: '4321'
                  merchant_customer_created_at: '2022-05-09T20:46:54.786342Z'
                  first_name: John
                  last_name: Doe
                  email: john.doe@email.com
                  gender: M
                  date_of_birth: '1990-02-28'
                  nationality: US
                  country: US
                  document:
                    document_type: SSN
                    document_number: 123-45-6789
                  phone:
                    number: '5551234567'
                    country_code: '1'
                  billing_address:
                    address_line_1: 123 Main St
                    address_line_2: Apt 4B
                    country: US
                    state: NY
                    city: New York
                    zip_code: '10001'
                    neighborhood: Manhattan
                  shipping_address:
                    address_line_1: 123 Main St
                    address_line_2: Apt 4B
                    country: US
                    state: NY
                    city: New York
                    zip_code: '10001'
                    neighborhood: Manhattan
                  metadata:
                    - key: ID
                      value: '123456'
              Customer (min. data):
                value:
                  merchant_customer_id: '4321'
                  first_name: John
                  last_name: Doe
                  email: john.doe@email.com
      responses:
        '201':
          description: '201'
          content:
            application/json:
              examples:
                Customer (full data):
                  value:
                    id: bf64527c-5531-4ece-bf2c-51a8e775d8e1
                    merchant_customer_id: AAAAAAAAAAAAAA0002
                    first_name: John
                    last_name: Doe
                    gender: M
                    date_of_birth: '1990-02-28'
                    email: john.doe@email.com
                    nationality: US
                    country: US
                    document:
                      document_type: SSN
                      document_number: 123-45-6789
                    phone:
                      number: '5551234567'
                      country_code: '1'
                    billing_address:
                      address_line_1: 123 Main St
                      address_line_2: Apt 4B
                      country: US
                      state: NY
                      city: New York
                      zip_code: '10001'
                      neighborhood: Manhattan
                    shipping_address:
                      address_line_1: 123 Main St
                      address_line_2: Apt 4B
                      country: US
                      state: NY
                      city: New York
                      zip_code: '10001'
                      neighborhood: Manhattan
                    metadata:
                      - key: ID
                        value: '123456'
                    created_at: '2025-04-24T18:54:54.351969Z'
                    updated_at: '2025-04-24T18:54:54.351971Z'
                    merchant_customer_created_at: '2022-05-09T20:46:54.786342Z'
                Customer (min. data):
                  value:
                    id: fe17085f-e9fd-4882-a42a-21eacc10fbb6
                    merchant_customer_id: AAAAAAA000001
                    first_name: John
                    last_name: Doe
                    gender: null
                    date_of_birth: null
                    email: john.doe@email.com
                    nationality: null
                    country: null
                    document: null
                    phone: null
                    billing_address: null
                    shipping_address: null
                    created_at: '2025-04-24T18:54:15.805086Z'
                    updated_at: '2025-04-24T18:54:15.805088Z'
                    merchant_customer_created_at: null
              schema:
                oneOf:
                  - title: Cliente (datos completos)
                    type: object
                    properties:
                      id:
                        type: string
                        example: bf64527c-5531-4ece-bf2c-51a8e775d8e1
                      merchant_customer_id:
                        type: string
                        example: AAAAAAAAAAAAAA0002
                      first_name:
                        type: string
                        example: John
                      last_name:
                        type: string
                        example: Doe
                      gender:
                        type: string
                        example: M
                      date_of_birth:
                        type: string
                        example: '1990-02-28'
                      email:
                        type: string
                        example: john.doe@email.com
                      nationality:
                        type: string
                        example: US
                      country:
                        type: string
                        example: US
                      document:
                        type: object
                        properties:
                          document_type:
                            type: string
                            example: SSN
                          document_number:
                            type: string
                            example: 123-45-6789
                      phone:
                        type: object
                        properties:
                          number:
                            type: string
                            example: '5551234567'
                          country_code:
                            type: string
                            example: '1'
                      billing_address:
                        type: object
                        properties:
                          address_line_1:
                            type: string
                            example: 123 Main St
                          address_line_2:
                            type: string
                            example: Apt 4B
                          country:
                            type: string
                            example: US
                          state:
                            type: string
                            example: NY
                          city:
                            type: string
                            example: New York
                          zip_code:
                            type: string
                            example: '10001'
                          neighborhood:
                            type: string
                            example: Manhattan
                      shipping_address:
                        type: object
                        properties:
                          address_line_1:
                            type: string
                            example: 123 Main St
                          address_line_2:
                            type: string
                            example: Apt 4B
                          country:
                            type: string
                            example: US
                          state:
                            type: string
                            example: NY
                          city:
                            type: string
                            example: New York
                          zip_code:
                            type: string
                            example: '10001'
                          neighborhood:
                            type: string
                            example: Manhattan
                      metadata:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              example: ID
                            value:
                              type: string
                              example: '123456'
                      created_at:
                        type: string
                        example: '2025-04-24T18:54:54.351969Z'
                      updated_at:
                        type: string
                        example: '2025-04-24T18:54:54.351971Z'
                      merchant_customer_created_at:
                        type: string
                        example: '2022-05-09T20:46:54.786342Z'
                  - title: Cliente (datos mínimos)
                    type: object
                    properties:
                      id:
                        type: string
                        example: fe17085f-e9fd-4882-a42a-21eacc10fbb6
                      merchant_customer_id:
                        type: string
                        example: AAAAAAA000001
                      first_name:
                        type: string
                        example: John
                      last_name:
                        type: string
                        example: Doe
                      gender: {}
                      date_of_birth: {}
                      email:
                        type: string
                        example: john.doe@email.com
                      nationality: {}
                      country: {}
                      document: {}
                      phone: {}
                      billing_address: {}
                      shipping_address: {}
                      created_at:
                        type: string
                        example: '2025-04-24T18:54:15.805086Z'
                      updated_at:
                        type: string
                        example: '2025-04-24T18:54:15.805088Z'
                      merchant_customer_created_at: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - Invalid request
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid Credentials
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_CREDENTIALS
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid Credentials
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    code: AUTHORIZATION_REQUIRED
                    messages:
                      - The merchant has no authorization to use this API
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: AUTHORIZATION_REQUIRED
                  messages:
                    type: array
                    items:
                      type: string
                      example: The merchant has no authorization to use this API
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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