Clientes

Un cliente es a quien le vendés o le cobrás. Las tarjetas guardadas, los cobros y las suscripciones cuelgan de un cliente, así que es lo primero que se crea.

Crear o recuperar un cliente

POST /api/v1/clientes
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "nombre": "Ana Pérez",
  "referenciaIntegrador": "usuario-4821",
  "email": "ana@ejemplo.com",
  "telefono": "099123456"
}

{
  "data": {
    "id": "7e6d5c4b-3a2f-4e1d-9c8b-7a6f5e4d3c2b",
    "nombre": "Ana Pérez",
    "referenciaIntegrador": "usuario-4821",
    "tipoDocumento": null,
    "documento": null,
    "email": "ana@ejemplo.com",
    "telefono": "099123456",
    "pais": "UY"
  },
  "meta": { "creado": true }
}

Es un upsert. El cliente se busca primero por referenciaIntegrador —tu identificador del cliente, único por empresa— y, si no, por su documento:

• si existe, se actualiza con lo que mandes (lo que omitís se conserva) y responde 200 con meta.creado: false;
• si no, se crea y responde 201.

Por eso podés llamarlo cada vez que lo necesites, sin guardar nuestro id: con la misma referencia siempre devuelve el mismo cliente, y un reintento no crea duplicados. Tenés que mandar al menos una de las dos identidades (la referencia o el documento).

Campo	Obligatorio	Descripción
nombre	sí	Nombre o razón social
referenciaIntegrador	uno de los dos	Tu id del cliente. Letras, dígitos y . _ : / -, hasta 128
tipoDocumento + documento	uno de los dos	Van juntos. RUC, CI, Pasaporte, DNI, NIFE, NIE u Otros. Se valida el dígito verificador
email, telefono	no	Contacto
direccion, ciudad, departamento	no	Aparecen en el comprobante
pais	no	ISO de 2 letras. Por defecto UY

Cualquier otro campo es un 422: la lista es cerrada.

Para leer un cliente: GET /api/v1/clientes/{id}. Para buscarlo, GET /api/v1/clientes (ver Listar y buscar).

El documento es opcional

Para guardarle una tarjeta y cobrarle no hace falta su documento. El documento sólo se necesita para identificarlo en un comprobante fiscal:

Comprobante	Cliente sin documento
e-Ticket	Sale como consumidor final. Por encima del tope de 5.000 UI, DGI exige identificar al receptor y la emisión se rechaza
e-Factura	Se rechaza: exige receptor con RUC
e-Factura de exportación, e-Resguardo	Se rechaza: exigen identificar al receptor

Se lo podés agregar después con otra llamada con la misma referenciaIntegrador. Lo que no se puede es quitarlo: un cliente con comprobantes emitidos no pierde su identidad fiscal.

Cuando las identidades se contradicen

La referencia y el documento no pueden apuntar a clientes distintos. Si pasa, la respuesta es 409 con el cliente existente en error.details.clienteId, y no se modifica nada:

Código	Qué pasó
CLIENTE_DOCUMENTO_DISTINTO	Esa referencia ya es de un cliente con otro documento
CLIENTE_DOCUMENTO_EN_USO	Ese documento ya es de otro cliente de la empresa
CLIENTE_REFERENCIA_EN_CONFLICTO	El cliente de ese documento ya tiene otra referencia

Un documento con dígito verificador incorrecto es 422 CLIENTE_DOCUMENTO_INVALIDO.

Alcances

Los clientes tienen alcances propios, disponibles en toda empresa:

Operación	Alcance
POST /api/v1/clientes (crear o actualizar)	clientes:escribir
GET /api/v1/clientes (listar y buscar)	clientes:leer o clientes:escribir
GET /api/v1/clientes/{id}	clientes:leer o clientes:escribir

Una credencial que guarda tarjetas o cobra necesita además clientes:escribir para dar de alta a sus clientes: el preset Solo pagos del panel ya lo incluye.

Listar y buscar

GET /api/v1/clientes?busqueda=perez&pagina=1&porPagina=50
GET /api/v1/clientes?referenciaIntegrador=usuario-4821

busqueda es parcial (nombre, nombre de fantasía, documento, referencia y email); referenciaIntegrador es igualdad exacta y, si no existe, el listado sale vacío. La paginación viaja en meta.paginacion.

Siguiente paso: guardarle una tarjeta y cobrarle.