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 está faltando.

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á apareceu na prática: ao acrescentar os fornecedores, as chaves que já existiam — todas de clientes — NÃO ganharam acesso a eles. Foi preciso marcar. O mesmo valerá para qualquer recurso acrescentado depois: uma integração nunca vê mais do que você concedeu.

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 é salvo em maiúsculas e o e-mail 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 sua ferramenta não quebre. Atenção ao nome: nombre é o primeiro nome (ou o nome fantasia, se for empresa) e o sobrenome 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), a requisição não é recusada, mas esse dado não é salvo. Para não passar despercebido, a resposta ao criar e editar clientes inclui avisos.camposIgnorados com a lista dessas chaves; as do endereço levam o caminho, como direccion.ciudad. Se aparecer, revise o mapeamento de campos da sua integração. Os campos que a própria API devolve (id, codigo, createdAt…) não geram aviso, então você pode ler um cliente, alterá-lo e enviá-lo de volta inteiro.

Só nombre é obrigatório. Opcionais: codigo, cif, email, telefono, telefonoSecundario, web, direccion (em uma ú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 é à vista), cuentaCliente e notas. Cada contato leva nombre —obrigatório—, cargo, telefono, email e notas; os contatos não têm identificador próprio.

A lista que você envia SUBSTITUI a que havia. Se enviar uma lista vazia, todos os contatos são apagados; se não enviar a chave (ou enviar null), eles ficam como estavam. É o que permite ler um fornecedor, mudar 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 se repetir até dentro da sua própria oficina. Por isso GET /proveedores/{id} só aceita o id. Se o seu ERP guarda apenas o código, use o filtro da listagem: GET /proveedores?codigo=PROV-004, que devolve todos os que combinarem e você decide.

Cada ordem traz numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, as datas do ciclo (entrada, início e fim do diagnóstico e do reparo, aviso ao cliente, entrega e ultimoCambioEstado, quando passou para o status atual), um resumo do cliente (id, codigo, codigoVisible, nombre, apellidos, razonSocial), o aparelho (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), o orçamento (numero, total, estado, fechaEnvio e fechaRespuesta, ou null se não houver), o técnico responsável (só o nome) e plazoEntregaEstimado, o prazo informado ao cliente no comprovante de entrada. Notas internas, assinaturas, fotos, documentos e senhas do aparelho nunca são retornados.

Se o seu CRM ou o seu PABX abre a ficha do cliente quando entra uma ligação, use GET /clientes?telefono=<número>. A busca é feita no telefone principal e no secundário e ignora como o número está escrito: espaços, hífens, parênteses, o código internacional do seu país (+55 ou 0055) e o 0 inicial. Assim, “(11) 91234-5678” encontra um cliente salvo como “+55 11 91234 5678”. São necessários pelo menos 6 dígitos.

GET /clientes/{id}/resumen retorna em uma única chamada o que um CRM costuma mostrar na ficha do cliente: totalReparaciones, reparacionesAbiertas (o aparelho ainda está na assistência), porEstado, totalPresupuestado e totalPresupuestosAprobados (na moeda da assistência, que vem em moneda), primeraReparacion, ultimaReparacion e ultimaActividad (a última alteração em qualquer uma das ordens dele). Precisa do recurso Reparos, assim como as ordens.

As listagens aceitam page (a partir de 1) e limit (25 por padrão, 100 no máximo; se pedir mais, é cortado para 100). O campo busqueda procura em nome, sobrenome, razão social, identificador fiscal, e-mail, código e telefone.

120 requisições por minuto por chave (mais do que suficiente para uma sincronização periódica; freia um loop acidental). 10 chaves ativas por organização. As listagens devolvem no máximo 100 registros por página. Se a organização estiver no plano gratuito com a cota mensal esgotada, o cadastro de clientes é bloqueado, igual ao aplicativo.

Assim você pode revogar uma sem quebrar as outras, e na lista vê quando cada uma foi usada pela última vez.

Guarde-a no cofre de credenciais da sua ferramenta (conexões do Make, credenciais do n8n, variáveis de ambiente). Se ela for parar em um repositório ou em um site, considere-a vazada.

A revogação é imediata: a chave antiga passa a receber 401 CLAVE_REVOCADA. Atualize a nova na sua ferramenta e pronto.

A referência técnica completa (rotas, parâmetros, esquemas e códigos de erro) está publicada no formato aberto em /api/v1/openapi.json, sem precisar de chave. Por padrão ela vem em espanhol; adicione ?lang= com o seu idioma para tê-la traduzida (por exemplo /api/v1/openapi.json?lang=pt, ?lang=en ou ?lang=ro). Você pode importá-la no Postman, Insomnia, Make ou n8n para ter todas as chamadas prontas.