API a integrace (CRM, Make, n8n)

Může daný zdroj vypisovat a prohlížet. Každý pokus o vytvoření, změnu nebo archivaci dostane chybu 403 s kódem PERMISO_DENEGADO a oprávněním, které mu chybí.

Kromě prohlížení může v daném zdroji vytvářet, aktualizovat a archivovat. Toto oprávnění potřebuje obousměrná synchronizace.

Oprávnění jsou vázaná na zdroj a už se to projevilo: když přibyli dodavatelé, klíče, které existovaly — všechny pro zákazníky — k nim přístup NEZÍSKALY. Bylo je třeba zaškrtnout. Totéž bude platit pro každý zdroj, který přibude později: integrace nikdy nevidí víc, než jste jí povolili.

Pole jsou stejná jako v kartě zákazníka: nombre a tipo (particular nebo empresa) jsou povinná; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) a notas jsou nepovinná. Daňový identifikátor se ukládá velkými písmeny a e-mail malými. V odpovědi jsou vždy přítomny všechny klíče, s hodnotou null, když hodnota chybí, aby se mapování polí ve vašem nástroji nerozbilo. Pozor na jméno: nombre je křestní jméno (u firmy obchodní název) a příjmení se uvádí zvlášť v apellidos, v množném čísle.

Pokud tělo obsahuje klíč, který neexistuje (například firstName místo nombre nebo apellido v jednotném čísle místo apellidos), požadavek se neodmítne, ale tato hodnota se neuloží. Aby to nezůstalo bez povšimnutí, odpověď při vytvoření a úpravě zákazníka obsahuje avisos.camposIgnorados se seznamem těchto klíčů; pole adresy mají uvedenou cestu, např. direccion.ciudad. Pokud se objeví, zkontrolujte mapování polí ve své integraci. Pole, která vrací samo API (id, codigo, createdAt…), upozornění nikdy nevyvolají, takže můžete zákazníka načíst, změnit a poslat zpět celého.

Povinné je jen nombre. Nepovinné: codigo, cif, email, telefono, telefonoSecundario, web, direccion (na jednom řádku, není to objekt jako u zákazníků), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica nebo otro), formaPago, plazoPago (ve dnech; 0 znamená platbu ihned), cuentaCliente a notas. Každý kontakt má nombre — povinné — a dále cargo, telefono, email a notas; kontakty nemají vlastní identifikátor.

Seznam, který odešlete, NAHRADÍ ten, který tam byl. Když odešlete prázdný seznam, všechny kontakty se smažou; když klíč neodešlete (nebo odešlete null), zůstanou tak, jak byly. Právě díky tomu si můžete dodavatele načíst, změnit mu jedno pole a poslat celý objekt zpátky bez podivných následků.

Na rozdíl od kódu zákazníka není kód dodavatele (PROV-004) jedinečný: může se opakovat i uvnitř vašeho vlastního servisu. Proto GET /proveedores/{id} přijímá pouze id. Pokud vaše ERP ukládá jen kód, použijte filtr v seznamu: GET /proveedores?codigo=PROV-004 vrátí všechny, které odpovídají, a rozhodnete se sami.

Každá zakázka obsahuje numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, data průběhu (příjem, začátek a konec diagnostiky a opravy, upozornění zákazníka, předání a ultimoCambioEstado, tedy kdy zakázka přešla do aktuálního stavu), souhrn zákazníka (id, codigo, codigoVisible, nombre, apellidos, razonSocial), zařízení (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), nabídku (numero, total, estado, fechaEnvio a fechaRespuesta, nebo null, pokud žádná není), přiděleného technika (jen jméno) a plazoEntregaEstimado, tedy termín dokončení, který zákazník dostal na potvrzení o převzetí. Interní poznámky, podpisy, fotky, dokumenty ani hesla zařízení se nikdy nevracejí.

Pokud vaše CRM nebo telefonní ústředna otevírá při příchozím hovoru kartu zákazníka, použijte GET /clientes?telefono=<číslo>. Hledá se v hlavním i vedlejším telefonu bez ohledu na to, jak je číslo zapsané: mezery, pomlčky a mezinárodní předvolba (+420 nebo 00420) se ignorují. Takže „601 234 567“ najde zákazníka uloženého jako „+420 601-234-567“. Je potřeba alespoň 6 číslic.

GET /clientes/{id}/resumen vrátí jedním voláním to, co CRM obvykle zobrazuje na kartě zákazníka: totalReparaciones, reparacionesAbiertas (zařízení je stále v servisu), porEstado, totalPresupuestado a totalPresupuestosAprobados (v měně servisu, která přijde v moneda), primeraReparacion, ultimaReparacion a ultimaActividad (poslední změna v kterékoli z jeho zakázek). Stejně jako zakázky vyžaduje zdroj Opravy.

Seznamy přijímají page (od 1) a limit (výchozí 25, nejvýše 100; pokud si vyžádáte víc, ořízne se na 100). Pole busqueda hledá ve jménu, příjmení, obchodním názvu, daňovém identifikátoru, e-mailu, kódu a telefonu.

120 požadavků za minutu na klíč (pro pravidelnou synchronizaci víc než dost; zastaví nechtěnou smyčku). 10 aktivních klíčů na organizaci. Seznamy vrací nejvýše 100 záznamů na stránku. Pokud je organizace v bezplatném tarifu s vyčerpaným měsíčním limitem, zakládání zákazníků se zastaví stejně jako v aplikaci.

Můžete tak jeden zneplatnit, aniž byste rozbili ostatní, a v seznamu vidíte, kdy byl každý naposledy použit.

Uchovávejte ho v úložišti přihlašovacích údajů svého nástroje (připojení v Make, credentials v n8n, proměnné prostředí). Pokud se dostane do repozitáře nebo na web, považujte ho za uniklý.

Zneplatnění je okamžité: starý klíč začne dostávat 401 CLAVE_REVOCADA. Aktualizujte nový ve svém nástroji a hotovo.

Úplná technická reference (cesty, parametry, schémata a chybové kódy) je publikována v otevřeném formátu na /api/v1/openapi.json, bez nutnosti klíče. Ve výchozím stavu je ve španělštině; přidejte ?lang= s kódem svého jazyka a dostanete ji přeloženou (například ?lang=cs nebo /api/v1/openapi.json?lang=en). Můžete ji importovat do nástrojů Postman, Insomnia, Make nebo n8n a mít všechna volání připravená.