Clientes: buscar, crear y mantener¶

Cómo resolver al cliente antes de emitir un documento: buscarlo por RUT, crearlo si no existe y mantener sus datos al día.

Prerrequisitos: Primeros pasos.

Cuándo necesitas un cliente¶

Vas a emitir	¿Necesitas cliente?
Boleta a consumidor final	No. Sale sin identificar al comprador.
Boleta a nombre de alguien	Basta enviar sus datos en el documento.
Factura, guía o nota de crédito	Sí: RUT, razón social, giro, dirección, comuna y ciudad son obligatorios.
Venta a crédito o con lista de precios propia	Sí, y conviene que tenga ficha en OpenTPV.

La ficha y el código de cliente¶

Cada cliente registrado en OpenTPV tiene una ficha con sus datos y un código (un número, por ejemplo 1234). El código es la forma más segura de referirse a un cliente, porque el RUT no siempre alcanza:

Un mismo RUT puede tener varias fichas

Una empresa con casa matriz y sucursales suele tener una ficha por cada local, todas con el mismo RUT y distinta dirección. Por eso, cuando hay más de una, hay que elegir la ficha por su código, no por el RUT.

Buscar un cliente¶

curl https://api.opentpv.cl/clientes/buscar/rut/76543210 \
  -H "Authorization: Bearer eyJhbGciOi..."

[
  { "codigo": 1234, "rut": "76543210", "digito": "K",
    "razonSocial": "Empresa Cliente SPA", "direccion": "Av. Principal 123",
    "comuna": "Santiago", "esCasaMatriz": true },
  { "codigo": 1567, "rut": "76543210", "digito": "K",
    "razonSocial": "Empresa Cliente SPA - Suc. Las Condes", "direccion": "Av. Apoquindo 4500",
    "comuna": "Las Condes", "esCasaMatriz": false }
]

El RUT va sin puntos y debe estar completo: la búsqueda es exacta, no encuentra por una parte del número. Puedes enviarlo con o sin dígito verificador (76543210 o 76543210-K). La respuesta siempre es una lista:

Lista vacía ([]): el cliente no existe. Créalo.
Un elemento: usa su codigo.
Varios elementos: son las fichas de ese RUT. Muéstraselas al usuario para que elija, o toma la que tiene esCasaMatriz en true.

Otras búsquedas:

GET /clientes/{codigo}                                        # la ficha completa, por código
GET /clientes/buscar/telefono/{fono}                          # por teléfono
GET /clientes/buscar/codigo-interno/{codigoInternoReceptor}   # por el código que usa el cliente
GET /clientes/lista/rut/{rut}                                 # fichas de un RUT, con datos de matriz y sucursales
GET /clientes/lista?razonSocial=&comuna=&estado=&giro=        # listado con filtros

/clientes/lista combina filtros por razón social, RUT, ciudad, comuna, estado, giro, rubro y email. Sirve para llevar la cartera completa a otro sistema.

Crear un cliente¶

curl -X POST https://api.opentpv.cl/clientes \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "rut": "76543210", "digito": "K",
    "razonSocial": "Empresa Cliente SPA",
    "nomFantasia": "Empresa Cliente",
    "giro": "Venta al por menor de productos varios",
    "direccion": "Av. Principal 123",
    "comuna": "Santiago", "ciudad": "Santiago",
    "telefono": "+56912345678",
    "email": "contacto@empresacliente.cl",
    "emailDte": "dte@empresacliente.cl",
    "estado": 1
  }'

La respuesta (201) devuelve la ficha creada con su codigo:

{ "codigo": 1234, "rut": "76543210", "digito": "K", "razonSocial": "Empresa Cliente SPA" }

Obligatorios: rut, digito y razonSocial. Para que el cliente sirva en facturas y guías, completa además giro, direccion, comuna y ciudad.

Campo	Para qué sirve
`rut` + `digito`	Identificación tributaria. El dígito verificador va aparte.
`razonSocial`, `giro`, `direccion`, `comuna`, `ciudad`	Los datos del receptor que salen en los documentos.
`emailDte`	Correo donde el cliente recibe la copia de sus documentos. Es distinto del correo de contacto.
`diasPlazo`, `creditoAprobado`, `idCondicionVenta`	Condiciones de crédito para ventas a plazo.
`listaPrecio`	Lista de precios que se le aplica (1 a 5).
`codigoInternoReceptor`	Código que el cliente exige ver en sus facturas (habitual en grandes cadenas).

Si el RUT ya existe, la API crea igual una segunda ficha: así se registran las sucursales. Por eso busca antes de crear, para no duplicar por error.

Actualizar un cliente¶

PUT /clientes/{codigo} reemplaza la ficha completa con lo que envíes. El patrón seguro es leer, modificar y devolver:

GET /clientes/1234
Cambia los campos que necesites en ese mismo objeto.
PUT /clientes/1234 con el objeto completo.

Si envías solo los campos que cambiaron, los demás quedan vacíos.

Usar al cliente al emitir¶

Hay tres formas de indicar el receptor en una factura, guía o nota, y se pueden combinar:

Envías	Qué hace la API
Todos los datos del receptor en el documento	Los usa tal cual. No necesita ficha.
`IdCliente` (el código)	Completa desde la ficha los datos que no enviaste.
Solo `Rut`	Completa desde la ficha, si ese RUT tiene una sola ficha. Si tiene varias no completa nada: envía `IdCliente`.

La regla de fondo: lo que envías en el documento manda, y la ficha solo rellena lo que falta. Detalle en Emitir documentos.

El código de cliente también se usa en:

Pedidos: idCliente al crear la nota de venta (ver Pedidos con nota de venta).
Guías a otra razón social: codigoClienteReceptor al documentar.
Consultas: documentos emitidos, pagos y deuda del cliente.

El flujo típico de una compra con factura¶

1. El comprador escribe su RUT en tu sistema.
2. GET /clientes/buscar/rut/{rut}
   → lista vacía:    pedir razón social, giro y dirección, y crear con POST /clientes
   → un resultado:   usar su código
   → varios:         dejar que elija la sucursal
3. Emitir la factura con IdCliente = código elegido.

Consultas útiles sobre un cliente¶

GET /clientes/{codigo}/documentos-pendientes   # documentos con saldo por pagar
GET /clientes/{codigo}/total-pendiente         # cuánto debe en total
GET /clientes/{codigo}/ventas                  # sus ventas
GET /clientes/{codigo}/pagos                   # sus pagos
GET /clientes/{codigo}/ultima-compra           # cuándo compró por última vez
GET /clientes/{codigo}/lista-precio            # qué lista de precios tiene
GET /clientes/{codigo}/descuento               # su descuento general
GET /clientes/{codigo}/correos                 # sus correos registrados

El detalle de cada una está en la referencia.

Errores frecuentes¶

Buscar con el RUT con puntos, o con solo una parte del número: no encuentra nada.
Crear sin buscar antes: queda una ficha duplicada.
Tomar "el primero" cuando el RUT tiene varias fichas: el documento sale con la dirección de otra sucursal.
Actualizar enviando solo un campo: PUT reemplaza la ficha completa.
Crear el cliente sin giro ni dirección y después intentar facturarle: la factura se rechaza por falta de datos del receptor.