Clientes: buscar, crear y mantener

Cómo resolver el cliente antes de emitir un documento: buscarlo por RUT, crearlo si no existe y mantener sus datos. El objetivo típico de una integración es obtener el código de cliente para usarlo en facturas (IdCliente), pedidos y como receptor de guías (codigoClienteReceptor).

Prerrequisitos: Primeros pasos.

Buscar un cliente

GET /clientes/buscar/rut/{rut}          # por RUT (acepta parcial)
GET /clientes/{codigo}                  # por código interno
GET /clientes/buscar/telefono/{fono}    # por teléfono
GET /clientes/buscar/codigo-interno/{codigoInternoReceptor}
GET /clientes/lista/rut/{rut}           # todas las sucursales de un RUT exacto

El flujo estándar de un checkout con factura:

1. El cliente ingresa su RUT en la tienda.
2. GET /clientes/buscar/rut/76543210: si existe, toma su codigo y listo.
3. Si no existe, créalo (abajo) y usa el codigo que devuelve.

Un mismo RUT puede tener varias fichas (casas matrices y sucursales); lista/rut/{rut} las devuelve todas para que el usuario elija.

Listados con filtros

GET /clientes/lista?razonSocial=&comuna=&estado=&giro=...

Filtros combinables por razón social, RUT, ciudad, comuna, estado, giro, rubro y email. Útil para sincronizar la cartera completa hacia un CRM.

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": "Comercial Ejemplo SpA",
    "giro": "Venta al por menor",
    "direccion": "Av. Principal 123",
    "comuna": "Santiago", "ciudad": "Santiago",
    "email": "contacto@ejemplo.cl",
    "emailDte": "dte@ejemplo.cl",
    "telefono": "+56 2 2345 6789",
    "activo": true
  }'

Campos que conviene conocer:

Campo	Para qué sirve
rut + digito	Identificación tributaria (el dígito verificador va aparte)
razonSocial, giro, direccion, comuna, ciudad	Datos del receptor que van en los DTE
emailDte	Correo al que se envía la copia del DTE (distinto del email de contacto)
diasPlazo, creditoAprobado, idCondicionVenta	Condiciones de crédito (ventas a plazo)
listaPrecio	Lista de precios que le aplica
codigoInternoReceptor	Código que el cliente exige que aparezca en sus facturas (retail grande)

Actualizar es el mismo patrón de productos: GET /clientes/{codigo}, modificar y PUT /clientes/{codigo} con el objeto completo.

Dónde se usa el código de cliente

• Factura por API: Venta.IdCliente en procesar/json; la API completa los datos del receptor desde la ficha (ver Emitir DTE).
• Pedidos: idCliente en POST /documento/notaventa (ver Pedidos con nota de venta).
• Receptor de guías multi-razón-social: codigoClienteReceptor al documentar; la razón social receptora debe existir como cliente.
• Consultas: documentos emitidos por cliente, cuenta corriente, crédito.

Consultas rápidas de la ficha

GET /clientes/{codigo}/rut      # solo el RUT
GET /clientes/{codigo}/email    # solo el email principal

Útiles cuando ya tienes el código y necesitas un dato puntual sin traer la ficha completa.