FacturaApiClienteDto

Identifies the recipient of the document. Required for FE, NC, and ND; optional for TE.


interface FacturaApiClienteDto {
  /** ID of an existing customer. If provided, the other fields are ignored. */
  idCliente?: number | null;
 
  /** Recipient's ID number (cédula). Alternative to idCliente: it's looked up in
      the tenant and, if it doesn't exist, is created with the fields below. */
  identificacion?: string | null;
 
  /** ID type. See Hacienda catalog. Required if creating
      by identificacion. */
  tipoIdentificacion?: string | null;
 
  /** Legal name or full name. */
  nombre?: string | null;
 
  /** Email to automatically send the document to. */
  correo?: string | null;
 
  /** Phone number with country code. */
  telefono?: string | null;
}

Fields

Field	Type	Required	Description
`idCliente`	`number`	One of the two	ID of the existing customer in the tenant’s catalog. If present, the other fields are ignored.
`identificacion`	`string`	One of the two	Recipient’s ID number. It’s looked up in the tenant and, if it doesn’t exist, is created.
`tipoIdentificacion`	`string`	If creating	ID type per Hacienda catalog.
`nombre`	`string`	If creating	Legal name or full name.
`correo`	`string`	Optional	Email the document will be automatically sent to.
`telefono`	`string`	Optional	Phone number with country code.

Usage modes

Mode A — Existing customer (recommended)


{ "idCliente": 42 }

LX CloudPos looks up the customer by ID in the tenant’s catalog. If it doesn’t exist, 400.

Mode B — By ID number, with automatic creation


{
  "identificacion": "3-101-123456",
  "tipoIdentificacion": "02",
  "nombre": "Comercializadora Ejemplo S.A.",
  "correo": "facturas@ejemplo.cr",
  "telefono": "22001100"
}

This is the intended mode for integrators: you don’t need to know LX CloudPos’s internal identifiers.

If a customer with that ID number already exists in the tenant, it’s reused — it isn’t duplicated, nor are its data updated. Modifying it is done from the POS.
If it doesn’t exist, it’s created with the data sent. tipoIdentificacion and nombre become required; if missing, a 400 is returned indicating exactly which one is missing.
The phone number and email are validated and normalized the same way as in the POS. A malformed email produces a 400, instead of a document that Hacienda accepts and the customer never receives.
The customer is created with paga_timbre set to false. If that customer is subject to the stamp tax (timbre), it must be adjusted from the POS: it’s not a value assumed on an automatic creation.