API e integrações (CRM, Make, n8n)

Pode listar e consultar esse recurso. Qualquer tentativa de criar, alterar ou arquivar recebe um erro 403 com o código PERMISO_DENEGADO e a permissão que lhe falta.

Além de consultar, pode criar, atualizar e arquivar nesse recurso. É a permissão de que uma sincronização bidirecional precisa.

As permissões são por recurso, e isso já se notou: ao acrescentar os fornecedores, as chaves que existiam — todas de clientes — NÃO ganharam acesso a eles. Foi preciso marcá-lo. O mesmo valerá para qualquer recurso acrescentado depois: uma integração nunca vê mais do que aquilo que lhe concedeste.

Os campos são os mesmos da ficha do cliente: nombre e tipo (particular ou empresa) são obrigatórios; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) e notas são opcionais. O identificador fiscal é guardado em maiúsculas e o email em minúsculas. Na resposta todas as chaves estão sempre presentes, com null quando não há valor, para que o mapeamento de campos na tua ferramenta não se parta. Atenção ao nome: nombre é o nome próprio (ou a designação comercial, se for uma empresa) e o apelido vai à parte, em apellidos, no plural.

Se o corpo trouxer uma chave que não existe (por exemplo firstName em vez de nombre, ou apellido no singular em vez de apellidos), o pedido não é recusado, mas esse dado não é guardado. Para não passar despercebido, a resposta ao criar e editar clientes inclui avisos.camposIgnorados com a lista dessas chaves; as da morada levam o caminho, como direccion.ciudad. Se aparecer, reveja o mapeamento de campos da sua integração. Os campos que a própria API devolve (id, codigo, createdAt…) não geram aviso, por isso pode ler um cliente, alterá-lo e devolvê-lo completo.

Só nombre é obrigatório. Opcionais: codigo, cif, email, telefono, telefonoSecundario, web, direccion (numa única linha, não é um objeto como em clientes), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica ou otro), formaPago, plazoPago (em dias; 0 é a pronto pagamento), cuentaCliente e notas. Cada contacto leva nombre —obrigatório—, cargo, telefono, email e notas; os contactos não têm identificador próprio.

A lista que envias SUBSTITUI a que lá estava. Se enviares uma lista vazia, apagam-se todos os contactos; se não enviares a chave (ou enviares null), ficam como estavam. É isso que te permite ler um fornecedor, alterar-lhe um campo e devolvê-lo inteiro sem efeitos estranhos.

Ao contrário do de cliente, o código do fornecedor (PROV-004) não é único: pode repetir-se mesmo dentro da tua própria oficina. Por isso GET /proveedores/{id} só aceita o id. Se o teu ERP só guarda o código, usa o filtro da listagem: GET /proveedores?codigo=PROV-004, que devolve todos os que correspondam e decides tu.

Cada ficha traz numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, as datas do ciclo (entrada, início e fim do diagnóstico e da reparação, aviso ao cliente, entrega e ultimoCambioEstado, quando passou ao estado atual), um resumo do cliente (id, codigo, codigoVisible, nombre, apellidos, razonSocial), o equipamento (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), o orçamento (numero, total, estado, fechaEnvio e fechaRespuesta, ou null se não existir), o técnico atribuído (só o nome) e plazoEntregaEstimado, o prazo indicado ao cliente no comprovativo de entrada. As notas internas, as assinaturas, as fotografias, os documentos e as palavras-passe do equipamento nunca são devolvidos.

Se o teu CRM ou a tua central telefónica abre a ficha do cliente quando entra uma chamada, usa GET /clientes?telefono=<número>. Pesquisa no telefone principal e no secundário e ignora a forma como o número está escrito: espaços, hífenes e o indicativo internacional do teu país (+351 ou 00351). Assim, «912 345 678» encontra um cliente guardado como «+351 912-345-678». São precisos pelo menos 6 dígitos.

GET /clientes/{id}/resumen devolve numa só chamada o que um CRM costuma mostrar na ficha do cliente: totalReparaciones, reparacionesAbiertas (o equipamento continua na oficina), porEstado, totalPresupuestado e totalPresupuestosAprobados (na moeda da oficina, que vem em moneda), primeraReparacion, ultimaReparacion e ultimaActividad (a última alteração em qualquer uma das suas fichas). Precisa do recurso Reparações, tal como as fichas.

As listagens aceitam page (a partir de 1) e limit (25 por omissão, 100 no máximo; se pedires mais, é cortado para 100). O campo busqueda pesquisa em nome, apelidos, razão social, identificador fiscal, email, código e telefone.

120 pedidos por minuto e por chave (de sobra para uma sincronização periódica; trava um ciclo acidental). 10 chaves ativas por organização. As listagens devolvem no máximo 100 registos por página. Se a organização estiver no plano gratuito com a quota mensal esgotada, a criação de clientes é cortada tal como na aplicação.

Assim podes revogar uma sem partir as outras, e na lista vês quando cada uma foi usada pela última vez.

Guarda-a no cofre de credenciais da tua ferramenta (ligações do Make, credenciais do n8n, variáveis de ambiente). Se a puseres num repositório ou num site, considera-a comprometida.

A revogação é imediata: a chave antiga começa a receber 401 CLAVE_REVOCADA. Atualiza a nova na tua ferramenta e está feito.

A referência técnica completa (rotas, parâmetros, esquemas e códigos de erro) está publicada em formato aberto em /api/v1/openapi.json, sem necessidade de chave. Por omissão sai em espanhol; acrescenta ?lang= com o teu idioma para a teres traduzida (por exemplo /api/v1/openapi.json?lang=pt-PT, ?lang=en ou ?lang=ro). Podes importá-la no Postman, Insomnia, Make ou n8n para teres todas as chamadas preparadas.