Conectar Xero con Boris

Xero se conecta por OAuth2. La parte que confunde a casi todo el mundo es que una cuenta de Xero puede administrar varias organizaciones, así que además del token hay que fijar cuál es la tuya.

1. Crear la app en Xero

1. Entrá a developer.xero.com con tu usuario de Xero.
2. My Apps → New app. Elegí el tipo Web app.
3. Poné como Redirect URI exactamente la URL que Boris te muestra en la pantalla de la integración.
4. Copiá el Client ID y generá un Client Secret.

2. Autorizar

Pegá las dos claves en Boris, guardá y pulsá Autorizar con Xero. Xero te va a pedir que elijas la organización: esa elección es la que Boris guarda y usa en todas las llamadas (viaja en la cabecera Xero-tenant-id). Si tenés varias empresas, prestá atención a este paso.

Los permisos que pide Boris son accounting.transactions, accounting.contacts, accounting.settings y offline_access. El último es el que permite renovar el acceso sin volver a autorizar.

3. Elegir cuenta e impuesto

Pulsá Importar cuentas e impuestos: Boris trae tu plan de cuentas de ingresos y tus tipos de IVA reales, y los muestra en una tabla.

• Cuenta de ingresos: el código al que van todas las líneas de factura. En un plan estándar de Xero suele ser 200 (Sales).
• Tipo de impuesto: el TaxType de Xero (por ejemplo OUTPUT2). Si lo dejás vacío, Xero aplica el que tenga la cuenta por defecto.
• Cuenta de banco para cobros: obligatoria si querés que los cobros se registren. Es el código de la cuenta bancaria donde entra el dinero.

Qué hace Boris dentro de Xero

• Busca el contacto por nombre (GET /Contacts?where=Name=="...") y solo lo crea si no existe (PUT /Contacts). El id de Boris queda en el campo AccountNumber como BORIS-123.
• Crea la factura con PUT /Invoices, tipo ACCREC, importes tax exclusive y tu número de factura en InvoiceNumber.
• Las notas de crédito van a PUT /CreditNotes como ACCRECCREDIT.
• Los cobros van a PUT /Payments contra el InvoiceID.

Ojo con los verbos: en Xero PUT crea y POST actualiza-o-crea. Boris usa siempre PUT a propósito, para que un reintento nunca pise en silencio una factura que tu contable ya tocó.

Cosas a tener en cuenta

• Xero rechaza un InvoiceNumber repetido. Eso es exactamente lo que querés: el número de Boris es la clave del documento en los dos lados.
• El nombre del contacto es único en Xero. Dos clientes distintos con el mismo nombre terminarán en el mismo contacto: si te pasa, diferenciá el nombre en la ficha del cliente.
• El refresh token rota en cada uso y caduca a los 60 días de inactividad. Un espacio que deja de facturar dos meses tiene que volver a autorizar.
• Límites de la API: 60 llamadas por minuto y 5.000 por día por organización. Una factura consume entre 2 y 4.

Cómo probarlo sin riesgo

Xero te deja crear una organización de demo gratuita desde tu cuenta, y la app de desarrollador funciona contra ella igual que contra la real. Es el mejor sitio para la primera prueba. Alternativamente, activá el modo simulación en Boris y revisá las peticiones antes de enviar nada.