Elegir qué expone tu API y cambiarlo después

Decides, recurso por recurso y campo por campo, qué datos de tu taller puede leer tu sistema, y lo ajustas cuando cambie lo que necesita.

Antes de empezar#

• Necesitas el permiso de «Integraciones» con alcance de «Toda la empresa» (de fábrica, el Superadministrador y el Administrador) y el plan Empresarial.
• Pregúntale a quien te integra qué datos necesita de verdad. Lo que no marques no sale.
• Los campos aparecen con el nombre con el que tu sistema los va a recibir, por ejemplo folio o email. Qué significa cada uno está en la documentación pública, que se abre con el botón «Documentación».

Pasos#

1. Al generar tu API, ve al panel «Qué expone». Nada viene marcado.
2. Marca el recurso que tu sistema va a leer, por ejemplo «Clientes». Debajo se abre la lista de sus campos.
3. Marca los campos uno por uno, o pulsa «Elegir todo». Si el recurso trae muchos campos, arriba de la lista aparece «Buscar» para encontrar uno por su nombre. El renglón del recurso lleva la cuenta, por ejemplo «3 campos marcados».
4. Si el recurso trae datos personales, lee el aviso antes de marcar: «Estás por sacar datos personales de tus clientes a un sistema externo. Márcalos solo si tu sistema de verdad los necesita.» Esos campos llevan la marca «Dato personal».
5. Repite con cada recurso y termina de crear la API.
6. Para cambiarlo después, abre la API desde «Integraciones» y pulsa «Editar campos». El botón «Editar» del panel «Qué expone» hace lo mismo.
7. Marca o desmarca recursos y campos, y pulsa «Guardar». Debe quedar al menos un recurso.
8. En «Confirma que eres tú», escribe tu «Contraseña actual» y pulsa «Confirmar». Verás el aviso «Cambios guardados».

Resultado#

El panel «Qué expone» lista cada recurso con cuántos campos tiene marcados. Tu sistema recibe esos campos y ninguno más. La llave no cambia: no hay que volver a entregarla.

Preguntas frecuentes#

¿Qué recursos puedo exponer? Los de tu operación, con el nombre que tienen en el taller: «Órdenes de servicio», «Partidas de la orden», «Clientes», «Vehículos», «Citas», «Productos», «Existencias de inventario», «Catálogo de servicios», «Proveedores», «Cobros», «Facturas (CFDI)», «Gastos», «Pagos de gastos», «Categorías de gasto», «Remisiones» y «Sucursales», entre otros. La lista completa está en la pantalla.

¿Mi sistema puede saber cuándo vino un cliente por última vez? Sí. En «Clientes», marca el campo lastVisitAt («última visita»): la fecha en que se abrió la orden más reciente del cliente, en cualquier sucursal, o vacío si no tiene. Se pone al día al abrir, mover o borrar órdenes, pero no cambia la fecha de actualización del cliente; si tu sistema lo copia, que relea la lista de clientes de vez en cuando o siga sus órdenes. El detalle técnico está en el portal para desarrolladores.

Quiero seguir una compra hasta su pago. ¿Qué expongo? Tres recursos que se encadenan: la compra en «Recepciones de mercancía», su cuenta por pagar en «Facturas de proveedor» —la factura de la compra, con la recepción, la orden de compra y el proveedor, su RFC y UUID, lo pagado, el saldo y el estado; ya no viaja en «Gastos», porque la compra de mercancía no es un gasto— y la salida del dinero en «Pagos de gastos», cuyo identificador de gasto apunta a un gasto o a una factura de compra. Para leer la categoría con nombre, expón también «Categorías de gasto» (el vocabulario con que tu taller clasifica lo que debe, de solo lectura). Antes de sumar: el pago de gasto viaja en negativo —sale dinero— y su reversa en positivo; el importe del gasto más sus pagos es lo que falta por pagar.

¿Puedo exponer las notas internas de una orden? No. No aparecen en la lista para nadie. Los costos sí se pueden marcar, porque son de tu propio taller.

Mi marca tiene un robot que lee las «visitas» de cada sucursal. ¿Qué expongo? El recurso «Visitas»: una fila por orden terminada con factura o remisión (sin notas de crédito ni canceladas), con las columnas de la tabla que ese robot ya consulta (fecha, sucursal, contacto, total, placas, marca, modelo, servicios, razón social, RFC…). Lleva datos personales: esos campos salen marcados «Dato personal» y solo una llave de empresa los ve. Para que cada fila diga su sucursal, captura antes sus «Referencias externas» en «Sucursales» › «Datos fiscales»: Capturar los datos fiscales de tu sucursal.

Pitflo agregó un dato nuevo. ¿Sale solo por mi API? No. Un dato nuevo nunca sale solo: entra a «Editar campos» y márcalo.

Quité un recurso. ¿Qué pasa con los avisos a mi sistema? Un webhook solo avisa eventos de recursos que tu API expone. Si quitas el recurso, sus eventos dejan de avisarse.