XubioCentro de ayuda

API

¿Cómo creo clientes con la API de Xubio?

¿Todavía no tenés token? — Pedilo siguiendo ¿Cómo obtengo un access token?.

Todos los llamados van a https://xubio.com/API/1.1/ y necesitan el token que obtuviste con tus credenciales. El token dura una hora.

Qué podés hacer

Cada operación es un llamado independiente.

Crear un cliente

POST /clienteBean

Con el nombre, el tipo de documento y la categoría fiscal alcanza. Ver detalle

Buscar clientes

GET /clienteBean

Por nombre, CUIT, mail o estado. Sin filtros te trae solo el id y el nombre. Ver detalle

Modificar un cliente

PUT /clienteBean/{id}

Reemplaza todos los campos, así que mandalo completo. Ver detalle

Eliminar un cliente

DELETE /clienteBean/{id}

Borra el cliente de tu cuenta. Ver detalle

Creá un cliente

POST /API/1.1/clienteBean

Ejemplo

{
  "nombre": "Distribuidora del Sur SA",
  "identificacionTributaria": { "codigo": "CUIT" },
  "CUIT": "30-71555555-3",
  "categoriaFiscal": { "codigo": "RI" },
  "email": "administracion@distribuidoradelsur.com"
}

Respuesta

{
  "cliente_id": 13848808,
  "nombre": "Distribuidora del Sur SA",
  "identificacionTributaria": { "ID": 9, "codigo": "CUIT", "id": 9 },
  "categoriaFiscal": { "ID": 1, "codigo": "RI", "id": 1 },
  "email": "administracion@distribuidoradelsur.com",
  "cuit": "30-71555555-3",
  "CUIT": "30-71555555-3"
}

Guardate el cliente_id que te devuelve: es el id con el que después modificás o eliminás el cliente. La respuesta es el cuerpo que mandaste con los catálogos resueltos, no el registro guardado; para ver cómo quedó, pedilo con GET /clienteBean/{id}.

Obligatorio
Campo Formato Qué es
nombre Texto El nombre o razón social. Si no lo mandás, el llamado falla con un error 500
identificacionTributaria Referencia → GET /identificacionTributaria El tipo de documento. Hay 38 opciones: CUIT, CUIL, DNI, LE, LC, PASAPORTE, SIN_IDENTIFICARVENTA_GLOBAL_DIARIA y otras. Si no la mandás, el llamado falla con un error 500
categoriaFiscal Referencia → GET /categoriaFiscal La condición frente al IVA: RI, MT, CF, EX, NA o CE. Si no la mandás, el llamado falla con un error 500
Opcional
Campo Formato Qué es
CUIT Texto con guiones: 30-71555555-3 ARCA lo exige al facturar. No puede repetirse en otro cliente o proveedor
email Texto Hasta 5 direcciones separadas por ; sin espacios: uno@ejemplo.com;dos@ejemplo.com. Se valida el formato de cada una
telefono, direccion, codigoPostal Texto Datos de contacto
provincia Referencia → GET /provinciaBean La provincia
localidad Referencia → GET /localidadBean Para ver las localidades de una provincia usá GET /localidadBean?provincia_id=43
usrCode Texto Tu código interno. No puede repetirse
pais Referencia → GET /paisBean Por defecto, Argentina
cuentaVenta_id, cuentaCompra_id Referencia → GET /cuenta Por defecto, DEUDORES_POR_VENTA y PROVEEDORES

Todas las referencias se mandan como un objeto con su codigo: { "codigo": "RI" }. Si mandás un código que no existe en el catálogo, el llamado falla con un error 500.

El CUIT va con guiones y se valida el dígito verificador Mandalo con el formato 30-71555555-3. Si lo mandás como once dígitos seguidos, o si el dígito verificador no cierra, la llamada falla con un error 500 del servidor en lugar de avisarte cuál es el inconveniente.
La razón social no se puede elegir — El campo razonSocial existe en el recurso, pero Xubio lo reescribe con el nombre en cada alta y en cada modificación. Si mandás una razón social distinta, la respuesta te la devuelve, pero el registro guardado queda con el nombre.

Los catálogos que vas a necesitar

Son de solo lectura: no se crean ni se modifican por API.

GET /API/1.1/identificacionTributaria
GET /API/1.1/categoriaFiscal
GET /API/1.1/provinciaBean
GET /API/1.1/localidadBean
GET /API/1.1/paisBean
GET /API/1.1/cuenta

Devuelven el id, el código y el nombre de cada opción. Conviene traerlos una vez al armar la integración y guardarte los códigos que usás.

Buscá un cliente

GET /API/1.1/clienteBean

Los filtros son opcionales y van en la URL.

Parámetro Valores
nombre El nombre completo. No distingue mayúsculas, tildes ni espacios, pero no busca por fragmentos
numeroIdentificacion El CUIT o documento tal cual está guardado, con guiones o puntos incluidos
tipoIdentificacion El código del catálogo: CUIT, CUIL, DNI. No distingue mayúsculas
email La dirección de mail completa. No distingue mayúsculas
activo 1 activos, 0 inactivos
esCliente 1 solo clientes, 0 solo proveedores

Ejemplo

curl "https://xubio.com/API/1.1/clienteBean?numeroIdentificacion=30-71555555-3&esCliente=1" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

[
  {
    "cliente_id": 13848808,
    "nombre": "Distribuidora del Sur SA",
    "razonSocial": "Distribuidora del Sur SA",
    "identificacionTributaria": { "ID": 9, "nombre": "CUIT", "codigo": "CUIT", "id": 9 },
    "categoriaFiscal": { "ID": 1, "nombre": "Responsable Inscripto", "codigo": "RI", "id": 1 },
    "email": "administracion@distribuidoradelsur.com",
    "cuentaVenta_id": { "ID": -3, "nombre": "Deudores as Venta", "codigo": "DEUDORES_POR_VENTA", "id": -3 },
    "cuentaCompra_id": { "ID": -7, "nombre": "Proveedores", "codigo": "PROVEEDORES", "id": -7 },
    "pais": { "ID": 1, "nombre": "Argentina", "codigo": "ARGENTINA", "id": 1 },
    "esclienteextranjero": 0,
    "esProveedor": 0,
    "cuit": "30-71555555-3",
    "responsabilidadOrganizacionItem": [],
    "CUIT": "30-71555555-3"
  }
]

La respuesta es siempre una lista. Si no hay coincidencias te devuelve una lista vacía.

Tenelo en cuenta — En cuanto usás cualquier filtro, la búsqueda recorre clientes y proveedores. Si querés solo clientes, agregá esCliente=1 a la consulta.

Sin ningún parámetro el llamado te trae todos los clientes de tu cuenta, pero con dos campos nada más:

[
  { "cliente_id": 13103455, "nombre": "24" },
  { "cliente_id": 13159157, "nombre": "25 HORAS S. A. (MP 2217990432)" }
]

Para traer un cliente con todos sus datos, agregá su id:

GET /API/1.1/clienteBean/13848808

Modificá un cliente

PUT /API/1.1/clienteBean/13848808

La modificación reemplaza todos los campos con lo que mandes: los que omitas quedan en blanco. Si solo querés cambiar el mail, traé primero el cliente con GET, modificá ese campo y mandá el objeto entero.

Además del cuerpo completo, el PUT tiene dos requisitos propios que no aplican en el alta:

  • El cliente_id tiene que ir dentro del cuerpo y coincidir con el id de la URL.
  • cuentaVenta_id y cuentaCompra_id son obligatorios. A diferencia del POST, la modificación no completa los valores por defecto: si los omitís, el llamado falla con un error 500 y el cliente queda como estaba.

Ejemplo

{
  "cliente_id": 13848808,
  "nombre": "Distribuidora del Sur SA",
  "identificacionTributaria": { "codigo": "CUIT" },
  "CUIT": "30-71555555-3",
  "categoriaFiscal": { "codigo": "RI" },
  "email": "cobranzas@distribuidoradelsur.com",
  "telefono": "1145678900",
  "cuentaVenta_id": { "codigo": "DEUDORES_POR_VENTA" },
  "cuentaCompra_id": { "codigo": "PROVEEDORES" }
}

Respuesta

{
  "cliente_id": 13848808,
  "nombre": "Distribuidora del Sur SA",
  "identificacionTributaria": { "ID": 9, "codigo": "CUIT", "id": 9 },
  "categoriaFiscal": { "ID": 1, "codigo": "RI", "id": 1 },
  "email": "cobranzas@distribuidoradelsur.com",
  "telefono": "1145678900",
  "cuentaVenta_id": { "ID": -3, "codigo": "DEUDORES_POR_VENTA", "id": -3 },
  "cuentaCompra_id": { "ID": -7, "codigo": "PROVEEDORES", "id": -7 },
  "cuit": "30-71555555-3",
  "CUIT": "30-71555555-3"
}

Igual que en el alta, la respuesta es el cuerpo que mandaste con los catálogos resueltos. Para ver cómo quedó el registro, pedilo con GET /clienteBean/{id}.

Qué se borra si mandás el cuerpo incompleto Un PUT con los campos mínimos deja en blanco email, telefono, direccion, codigoPostal, provincia, localidad y usrCode. El pais es la excepción: si lo omitís, queda como estaba.

Eliminá un cliente

DELETE /API/1.1/clienteBean/13848808

No lleva cuerpo y responde 204 sin contenido. Borra el cliente de la cuenta: no lo deja inactivo. Después de eliminarlo, GET /clienteBean/{id} contesta “El cliente no existe”, y si volvés a pedir la baja del mismo id, el llamado falla con un error 500.

Preguntas frecuentes

¿Necesito el CUIT para crear un cliente?
No para darlo de alta: podés mandar el tipo de documento sin el número, o usar SIN_IDENTIFICARVENTA_GLOBAL_DIARIA. Pero sí para facturarle, porque ARCA lo exige según el tipo de comprobante. Conviene cargarlo desde el principio.
¿Qué pasa si el CUIT ya está cargado en otro cliente?
El llamado falla con un error 500: el número de identificación no puede repetirse entre clientes y proveedores. Lo mismo pasa con el nombre y con el usrCode. Si el mismo CUIT es cliente y proveedor a la vez, se usa un único registro con las dos marcas activadas.
Busqué un cliente por nombre y no me lo trajo, ¿por qué?
El filtro nombre compara el texto completo, no fragmentos: "Distribuidora" no encuentra a "Distribuidora del Sur SA". Lo que sí podés es escribirlo en minúsculas o sin tildes, porque esas diferencias no cuentan. Con email pasa lo mismo: tiene que ser la dirección completa.
¿Puedo dar de alta proveedores con este mismo recurso?
No: los proveedores tienen su propio recurso, ProveedorBean (con la P mayúscula), con la misma lógica de campos obligatorios.
¿Ya tengo los clientes cargados y quiero facturarles?
Seguí con ¿Cómo facturo con la API de Xubio?, que explica el flujo completo de emisión y la solicitud del CAE.