POST /v1/clients

Registra un cliente en tu empresa y devuelve el id que usarás como clientId al facturar.

Un cliente solo es obligatorio para ventas exoneradas. Las ventas ordinarias pueden omitirlo.

Solicitud

POST /v1/clients
Authorization: Bearer ctd_sk_...
Content-Type: application/json

{
  "clientName": "Servicios Digitales S. de R.L.",
  "email": "facturacion@cliente.hn",
  "legalId": "08011999123456",
  "phone": "+504 9999-9999",
  "address": "Tegucigalpa, Honduras"
}

Campo	Tipo	Req.	Notas
clientName	string	Sí	Máx. 255 caracteres.
email	string	Sí	Debe ser un correo válido.
legalId	string	No	RTN. Si lo mandas, debe tener exactamente 14 dígitos. Obligatorio si algún día vas a emitirle facturas exoneradas.
phone	string	No	Máx. 32 caracteres.
address	string	No	Máx. 255 caracteres.

aviso

Campos desconocidos se rechazan

El body se valida en modo estricto: mandar un campo que no está en esta tabla produce 400 VALIDATION_FAILED. No se ignoran silenciosamente.

Respuesta 201

{
  "id": 1042,
  "clientName": "Servicios Digitales S. de R.L.",
  "email": "facturacion@cliente.hn",
  "legalId": "08011999123456",
  "phone": "+504 9999-9999",
  "address": "Tegucigalpa, Honduras",
  "createdAt": "2026-08-10T15:04:05.000Z"
}

Campo	Tipo	Descripción
id	number	Úsalo como clientId en POST /v1/invoices.
clientName	string
email	string
legalId	string | null
phone	string | null
address	string | null
createdAt	string	ISO 8601.

consejo

Guarda el id en tu base de datos

Guárdalo junto a tu propio id de cliente en el mismo commit en que lo recibes. Si lo pierdes, puedes recuperarlo con GET /v1/clients, pero ese endpoint devuelve la lista completa y no filtra por RTN ni por nombre: es para carga inicial y reconciliación, no para resolver un cliente en cada venta.

Errores

HTTP	code	Causa
400	VALIDATION_FAILED	Falta clientName o email, tipos inválidos, o campo desconocido.
400	INVALID_RTN_FORMAT	El legalId no tiene 14 dígitos.
401	MISSING_API_KEY / INVALID_API_KEY	Credencial ausente o inválida.
403	INTEGRATION_NOT_ENABLED	La empresa no tiene la integración habilitada.
409	UQ_CLIENT_CODE_COMPANY / UQ_IHCAFE_CODE_CLIENT	Ya existe un cliente con ese código o RTN.

Ver el catálogo completo de errores.