API e integracións (CRM, Make, n8n)

Pode listar e consultar ese recurso. Calquera intento de crear, modificar ou arquivar recibe un erro 403 co código PERMISO_DENEGADO e o permiso que lle falta.

Ademais de consultar, pode crear, actualizar e arquivar nese recurso. É o permiso que precisa unha sincronización bidireccional.

Os permisos son por recurso, e iso xa se notou: ao engadir os provedores, as chaves que existían —todas de clientes— NON gañaron acceso a eles. Houbo que marcalo. O mesmo valerá para calquera recurso que se engada despois: unha integración nunca ve máis do que lle concediches.

Os campos son os mesmos que na ficha do cliente: nombre e tipo (particular ou empresa) son obrigatorios; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) e notas son opcionais. O identificador fiscal gárdase en maiúsculas e o email en minúsculas. Na resposta todas as claves están sempre presentes, con null cando non hai valor, para que o mapeamento de campos na túa ferramenta non se rompa. Ollo co nome: nombre é o nome de pía (ou o nome comercial se é unha empresa) e o apelido vai á parte, en apellidos, en plural.

Se o corpo trae unha clave que non existe (por exemplo firstName en vez de nombre, ou apellido en singular en vez de apellidos), a petición non se rexeita, pero ese dato non se garda. Para que non pase desapercibido, a resposta de alta e de edición de clientes inclúe avisos.camposIgnorados coa lista desas claves; as do enderezo levan a súa ruta, como direccion.ciudad. Se che aparece, revisa o mapeamento de campos da túa integración. Os campos que devolve a propia API (id, codigo, createdAt…) non xeran aviso, así que podes ler un cliente, cambialo e devolvelo enteiro.

Só nombre é obrigatorio. Opcionais: codigo, cif, email, telefono, telefonoSecundario, web, direccion (nunha soa liña, non é un obxecto como en clientes), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica ou otro), formaPago, plazoPago (en días; 0 é ao contado), cuentaCliente e notas. Cada contacto leva nombre —obrigatorio—, cargo, telefono, email e notas; os contactos non teñen identificador propio.

A lista que envías SUBSTITÚE a que había. Se envías unha lista baleira, bórranse todos os contactos; se non envías a clave (ou envías null), quedan como estaban. É o que fai que poidas ler un provedor, cambiarlle un campo e devolvelo enteiro sen efectos raros.

A diferenza do de cliente, o código do provedor (PROV-004) non é único: pode repetirse mesmo dentro do teu propio taller. Por iso GET /proveedores/{id} só acepta o id. Se o teu ERP só garda o código, usa o filtro da listaxe: GET /proveedores?codigo=PROV-004, que devolve todos os que coincidan e decides ti.

Cada ficha trae numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, as datas do ciclo (entrada, inicio e fin da diagnose e da reparación, aviso ao cliente, entrega e ultimoCambioEstado, cando pasou ao seu estado actual), un resumo do cliente (id, codigo, codigoVisible, nombre, apellidos, razonSocial), o aparello (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), o orzamento (numero, total, estado, fechaEnvio e fechaRespuesta, ou null se non ten), o técnico asignado (só o seu nome) e plazoEntregaEstimado, o prazo que se lle indicou ao cliente no resgardo. Nunca saen as notas internas, as sinaturas, as fotos, os documentos nin os contrasinais do aparello.

Se o teu CRM ou a túa centraliña abre a ficha do cliente ao entrar unha chamada, usa GET /clientes?telefono=<número>. Busca no teléfono principal e no secundario e ignora como estea escrito: espazos, guións, o prefixo internacional do teu país (+34 ou 0034) e o 0 inicial. Así «612 345 678» atopa un cliente gardado como «+34 612-345-678». Fan falta polo menos 6 díxitos.

GET /clientes/{id}/resumen devolve nunha soa chamada o que adoita mostrar un CRM na ficha do cliente: totalReparaciones, reparacionesAbiertas (o aparello segue no taller), porEstado, totalPresupuestado e totalPresupuestosAprobados (na moeda do taller, que chega en moneda), primeraReparacion, ultimaReparacion e ultimaActividad (o último cambio en calquera das súas fichas). Precisa o recurso Reparacións, igual que as fichas.

As listaxes aceptan page (desde 1) e limit (25 por defecto, 100 como máximo; se pides máis recórtase a 100). O campo busqueda busca no nome, apelidos, razón social, identificador fiscal, email, código e teléfono.

120 peticións por minuto e chave (de sobra para unha sincronización periódica; frea un bucle accidental). 10 chaves activas por organización. As listaxes devolven como máximo 100 rexistros por páxina. Se a organización está no plan gratuíto coa cota mensual esgotada, a alta de clientes córtase igual que na aplicación.

Así podes revogar unha sen romper as demais, e na lista ves cando se usou cada unha por última vez.

Gárdaa no almacén de credenciais da túa ferramenta (conexións de Make, credenciais de n8n, variables de contorno). Se a subes a un repositorio ou a unha web, considéraa filtrada.

A revogación é inmediata: a chave antiga comeza a recibir 401 CLAVE_REVOCADA. Pon a nova na túa ferramenta e listo.

A referencia técnica completa (rutas, parámetros, esquemas e códigos de erro) está publicada en formato aberto en /api/v1/openapi.json, sen necesidade de chave. Sen máis, sae en castelán; engade ?lang= co teu idioma para tela traducida (por exemplo /api/v1/openapi.json?lang=en ou ?lang=ro). Podes importala en Postman, Insomnia, Make ou n8n para ter todas as chamadas preparadas.