Crear Clientes y/o Proveedores (Beneficiarios)
Los beneficiarios son las personas o empresas con las que su negocio vende y compra: sus clientes y proveedores. Este tutorial cubre cómo crearlos, importarlos, filtrarlos y consultarlos. Para agruparlos por condiciones comerciales, vea Categorías de Beneficiarios.
Crear un beneficiario
No puede emitir una factura ni registrar una compra sin tener registrado antes al beneficiario.
- Ir a "Configuraciones".
- Seleccionar "Beneficiarios".
- Click en "Nuevo Beneficiario".

Tipos de beneficiario
Un beneficiario puede ser proveedor, cliente o ambos:
- Proveedor: beneficiario al que le compra. Puede ser proveedor de bienes o de servicios; los proveedores de servicios se usan en el libro de compras.
- Cliente: beneficiario al que le vende.
- Cliente y proveedor: marque ambas casillas.
Las casillas "Proveedor" y "Cliente" se marcan al crear el beneficiario.
Campos del formulario
Estos son los campos del nuevo beneficiario, en el orden del formulario:
- Nombre: nombre comercial del cliente o proveedor (ej. Industrias de Hamburguesas, S.A.).
- Referencia: nombre común o sobrenombre (ej. McDonald's).
- Categoría de Beneficiario: categoría creada previamente (ej. Mayorista, Minorista). Puede vincularse a un listado de precios para manejar precios distintos.
- NIT: número de identificación tributaria.
- Moneda: moneda en que se factura o compra.
- Dirección: dirección del beneficiario.
- Dirección (Línea 2): segunda línea de la dirección.
- Dirección de Entrega: dirección de entrega de los productos.
- Página Web: sitio web del beneficiario.
- Teléfono: número de teléfono del beneficiario.
- Correo Electrónico: correo del beneficiario.
- Límite de Crédito (Monto): máximo saldo no pagado de las facturas al crédito; sin moneda, solo números.
- Facturas: cantidad de facturas al crédito no pagadas permitidas.
- Término de pago vencido: no permite nuevas facturas al crédito si hay saldo vencido no pagado.
- Contacto: nombre del contacto.
- Teléfono del Contacto: teléfono del contacto.
- Correo Electrónico del Contacto: correo del contacto.
- Contacto 2: nombre del segundo contacto.
- Teléfono de Contacto 2: teléfono del segundo contacto.
- Correo Electrónico del Contacto 2: correo del segundo contacto.
- Notas: notas sobre el beneficiario.
- Vendedor Exclusivo: vendedor asignado, se selecciona de la lista de empleados.
- Click en "Crear beneficiario" para guardar.

Campos adicionales
Además de los campos del formulario, un beneficiario puede tener:
- Actividad económica: actividad del beneficiario.
- Tipo de contribuyente: Pequeño Contribuyente, Gran Contribuyente o Exento.
- Agente de retención: si el beneficiario es agente de retención de impuestos.
- Sujeto a retención de impuestos: si el beneficiario está sujeto a retenciones.
- Cliente para exportación: si el beneficiario es cliente de exportación.
- País: país del beneficiario, útil para extranjeros.
- Extranjero: si el beneficiario es del extranjero.
- Ciudad y Distrito: ubicación del beneficiario.
- Término de pago por defecto: plazo que se asigna en las transacciones.
- Latitud y Longitud: coordenadas del beneficiario.
- Número de identificación personal (CUI): para personas individuales.
Importar beneficiarios
Si tiene demasiados clientes o proveedores para ingresarlos uno por uno, use las plantillas predefinidas de Excel:
- Ir a "Configuraciones".
- Seleccionar "Beneficiarios".
- Click en "Importar".
- Descargar la plantilla y llenar los campos; los obligatorios son "Nombre", "Moneda" y "Límite de crédito".
- Seleccionar el archivo de Excel.
- Click en "Importar beneficiarios". Si aparece algún error, revise que la plantilla cumpla las reglas de abajo.

Cada campo de la plantilla acepta:
- Booleano: TRUE o FALSE; si no se especifica, Zauru asume FALSE.
- Número entero: sin punto decimal ni separador de miles.
- Número con decimales: sin separador de miles.
- Texto: cualquier carácter.
- Cadena de texto: cualquier carácter, máximo 256.

Filtrar beneficiarios
El listado tiene filtros por tipo y una nube de etiquetas:
- Todos: todos los beneficiarios.
- Clientes: solo clientes.
- Proveedores: solo proveedores.
- Clientes y Proveedores: clientes y proveedores a la vez.
También puede seleccionar una etiqueta de la nube para mostrar solo los beneficiarios que la tengan asignada.
Exportar beneficiarios
- Ir a "Configuraciones".
- Seleccionar "Beneficiarios".
- Click en "Exportar a CSV" o "Exportar a Excel".
Si hay un filtro de etiquetas activo, la exportación incluye solo esos beneficiarios.
Sincronizar con CRM
Si su entidad tiene activo el módulo de CRM, en el detalle del beneficiario seleccione "Sincronizar con CRM" para crear o actualizar su contacto en el CRM.
Buscar por NIT o CUI
Con un servicio externo configurado para su entidad, puede buscar beneficiarios por NIT o CUI al crearlos y así validar sus datos tributarios.
API (llamadas desde sistemas externos)
Obtener listado de beneficiarios
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees.json
Esto devolverá un JSON similar a este:
[
{
"id": 1,
"zid": 2,
"id_number": null,
"active": true,
"name": "Proveedor Ejemplo A, S.A.",
"vendor": true,
"buyer": false,
"tin": "1111111-1",
"reference": "Referencia Ejemplo",
"address_line_1": "9 Avenida 34-00, zona 11 Guatemala, Guatemala",
"address_line_2": null,
"delivery_address": null,
"currency_id": 3,
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": "",
"email": "",
"contact": "",
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": "",
"entity_id": 4,
"updater_id": 5,
"created_at": "2016-06-17T20:54:25.123Z",
"updated_at": "2016-06-17T20:54:25.123Z",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": {
"url": null,
"thumbnail": {
"url": null
}
},
"image": {
"url": null,
"standard": {
"url": null
},
"thumbnail": {
"url": null
},
"pos": {
"url": null
}
},
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": 6
},
{
"id": 7,
"zid": 8,
"id_number": null,
"active": true,
"name": "Proveedor Ejemplo B, S.A.",
"vendor": true,
"buyer": false,
"tin": "2222222-0",
"reference": "",
"address_line_1": "21 Avenida 5-67, zona 11 Colonia El Mirador 1, Guatemala, Guatemala",
"address_line_2": null,
"delivery_address": null,
"currency_id": 3,
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": "5555-0005",
"email": "www.ejemplo.com",
"contact": "",
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": "",
"entity_id": 4,
"updater_id": 5,
"created_at": "2016-11-08T16:53:48.880Z",
"updated_at": "2016-11-08T16:53:48.880Z",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": {
"url": null,
"thumbnail": {
"url": null
}
},
"image": {
"url": null,
"standard": {
"url": null
},
"thumbnail": {
"url": null
},
"pos": {
"url": null
}
},
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": 6
}
]
Obtener listado de beneficiarios por tipo (datatables)
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X POST \
-d '{"start": "0", "length": "25", "scope": "clients"}' \
https://app.zauru.com/settings/payees/datatables.json
Esto devolverá un JSON similar a este:
{
"draw": 0,
"recordsTotal": 569,
"recordsFiltered": 569,
"data": [
{
"zid": "<a href=\"/settings/payees/109202\">521</a>",
"id_number": "<a href=\"/settings/payees/109202\"></a>",
"reference": "<a href=\"/settings/payees/109202\">RzM corp</a>",
"active": "<span style=\"color: red;\"><i class=\"fa fa-times\" alt=\"times\"></i></span>",
"name": "<a href=\"/settings/payees/109202\">Transemsa, S.A.</a>",
"tin": "3333333-3",
"address": "5 Avenida Ejemplo 19-96, Zona 14",
"payee_category": "4 a 6",
"phone": "5555-0006",
"email": "contabilidad@ejemplo.com",
"record_actions": "<a title=\"Detalles\" href=\"/settings/payees/109202\"><i class=\"fa fa-eye\"></i></a><a title=\"Editar\" href=\"/settings/payees/109202/edit\"><i class=\"fa fa-edit\"></i></a><a title=\"Destruirlo\" data-confirm=\"¿Está seguro de destruirlo?\" rel=\"nofollow\" data-method=\"delete\" href=\"/settings/payees/109202?destroy=true\"><i class=\"fa fa-trash-o\"></i></a>",
"DT_RowId": "settings-payee-109202"
},
{
"zid": "<a href=\"/settings/payees/258696\">725</a>",
"id_number": "<a href=\"/settings/payees/258696\"></a>",
"reference": "<a href=\"/settings/payees/258696\">Romar</a>",
"active": "<span style=\"color: red;\"><i class=\"fa fa-times\" alt=\"times\"></i></span>",
"name": "<a href=\"/settings/payees/258696\">Servicios Empresariales Mercantiles, S.A. </a>",
"tin": "4444444-4",
"address": "Ciudad ",
"payee_category": "",
"phone": "5555-0007",
"email": "info@ejemplo.com",
"record_actions": "<a title=\"Detalles\" href=\"/settings/payees/258696\"><i class=\"fa fa-eye\"></i></a><a title=\"Editar\" href=\"/settings/payees/258696/edit\"><i class=\"fa fa-edit\"></i></a><a title=\"Destruirlo\" data-confirm=\"¿Está seguro de destruirlo?\" rel=\"nofollow\" data-method=\"delete\" href=\"/settings/payees/258696?destroy=true\"><i class=\"fa fa-trash-o\"></i></a>",
"DT_RowId": "settings-payee-258696"
}
]
}
Crear beneficiario
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X POST \
-d '{
"payee": {
"name": "Cliente Prueba",
"tin": "12345678-9",
"reference": "alguna referencia",
"address_line_1": "1 calle 1-11",
"currency_id": "1",
"vendor": false,
"buyer": true
}
}' \
https://app.zauru.com/settings/payees.json
Esto devolverá un JSON similar a este:
{
"id": 1,
"zid": 2,
"id_number": null,
"active": true,
"name": "Cliente Prueba",
"vendor": false,
"buyer": true,
"tin": "12345678-9",
"reference": "alguna referencia",
"address_line_1": "1 calle 1-11",
"address_line_2": null,
"delivery_address": null,
"currency_id": 3,
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": null,
"email": null,
"contact": null,
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": null,
"entity_id": 4,
"updater_id": 5,
"created_at": "2026-08-06T04:16:49.555Z",
"updated_at": "2026-08-06T04:16:49.555Z",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": {
"url": null,
"thumbnail": {
"url": null
}
},
"image": {
"url": null,
"standard": {
"url": null
},
"thumbnail": {
"url": null
},
"pos": {
"url": null
}
},
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": null
}
Editar beneficiario
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X PUT \
-d '{
"payee": {
"name": "Cliente Prueba 2",
"tin": "12345678-9",
"reference": "referencia actualizada",
"address_line_1": "1 calle 2-22",
"currency_id": "1"
}
}' \
https://app.zauru.com/settings/payees/1.json
Esto devolverá un JSON similar a este:
{
"id": "2080191",
"zid": "87",
"id_number": null,
"active": true,
"name": "Cliente CRM",
"vendor": false,
"buyer": true,
"tin": "12345678-9",
"reference": null,
"address_line_1": null,
"address_line_2": null,
"delivery_address": null,
"currency_id": "1",
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": null,
"email": null,
"contact": null,
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": null,
"entity_id": "1303",
"updater_id": "23",
"created_at": "2026-08-06 04:12:08.19016",
"updated_at": "2026-08-06 04:12:08.19016",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": null,
"image": null,
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": null
}
Obtener detalles del beneficiario
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/1.json
Esto devolverá un JSON similar a este:
{
"id": "2080191",
"zid": "87",
"id_number": null,
"active": true,
"name": "Cliente CRM",
"vendor": false,
"buyer": true,
"tin": "12345678-9",
"reference": null,
"address_line_1": null,
"address_line_2": null,
"delivery_address": null,
"currency_id": "1",
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": null,
"email": null,
"contact": null,
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": null,
"entity_id": "1303",
"updater_id": "23",
"created_at": "2026-08-06 04:12:08.19016",
"updated_at": "2026-08-06 04:12:08.19016",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": null,
"image": null,
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": null
}
Eliminar beneficiario
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X DELETE \
https://app.zauru.com/settings/payees/1.json
En caso de éxito, retorna un código HTTP 204 No Content (sin cuerpo).
Exportar beneficiarios
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/export.csv
El mismo endpoint acepta export.xls y export.json.
Esto devolverá un JSON similar a este:
{
"id": "2080191",
"zid": "87",
"id_number": null,
"active": true,
"name": "Cliente CRM",
"vendor": false,
"buyer": true,
"tin": "12345678-9",
"reference": null,
"address_line_1": null,
"address_line_2": null,
"delivery_address": null,
"currency_id": "1",
"credit_limit": "0.0",
"payee_category_id": null,
"web": null,
"phone": null,
"email": null,
"contact": null,
"contact_phone": null,
"contact_email": null,
"contact2": null,
"contact2_phone": null,
"contact2_email": null,
"notes": null,
"entity_id": "1303",
"updater_id": "23",
"created_at": "2026-08-06 04:12:08.19016",
"updated_at": "2026-08-06 04:12:08.19016",
"employee_id": null,
"service_provider": true,
"invoices_in_credit_limit": null,
"payment_delay_in_credit_limit": false,
"pdf": null,
"image": null,
"excempt": false,
"small_taxpayer": false,
"foreign": false,
"latitude": null,
"longitude": null,
"great_contributor": null,
"tax_withholding_agent": false,
"subject_to_withholding_taxes": false,
"personal_identification_number": null,
"client_for_export": false,
"payee_activity_id": null,
"city_id": null,
"taxpayer_registry": null,
"district_id": null,
"default_payment_term_id": null,
"country_id": null
}
Obtener nube de etiquetas de beneficiarios
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/tag_cloud.json
Búsqueda de beneficiario por NIT
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X POST \
-d '{"tin": "12345678-9"}' \
https://app.zauru.com/settings/payees/search_payee.json
Esto devolverá un JSON similar a este:
{
"name": null,
"id": null,
"address": "Ciudad",
"tin": "12345678-9",
"err": "No se pudo conectar con certificador",
"phone": null,
"pin": null
}
Buscar beneficiario por NIT o CUI (devuelve nombre)
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X POST \
-d '{"tin": "12345678-9"}' \
https://app.zauru.com/settings/payees/search_payee_name.json
Esto devolverá un JSON similar a este:
{
"name": "",
"error": "no encontrado"
}
Obtener beneficiario por NIT o CUI
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/get_payee.json?payee=12345678-9&pin=0
Esto devolverá un JSON similar a este:
{
"name": null,
"id": null,
"address": null,
"tin": null,
"email": null,
"phone": null,
"pin": null,
"foreign": false,
"client_for_export": false,
"country_code": null
}
Autocompletar beneficiario
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/autocomplete.json?term=cliente
Esto devolverá un JSON similar a este:
[
"Buscar NIT cliente en Infile FEL"
]
Autocompletar beneficiario por CUI
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/autocomplete_pin.json?term=123456789
Esto devolverá un JSON similar a este:
[]
Autocompletar beneficiario extranjero
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/autocomplete_foreign_payee.json?term=cliente
Esto devolverá un JSON similar a este:
[]
Sincronizar beneficiario con CRM
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
https://app.zauru.com/settings/payees/1/sync_payee_to_crm.json
Crear importación de beneficiarios
curl -v \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "X-User-Email: prueba@zauru.com" \
-H "X-User-Token: XSDFKK09238487DLFS" \
-X POST \
-d '{
"payee_import": {
"file": "archivo_excel.xlsx"
}
}' \
https://app.zauru.com/settings/payees/payee_imports.json
Esto devolverá un JSON similar a este:
{}