Per a responsables d'integració

Connectar una integració de manera segura

Autentica les sol·licituds i limita l'accés al que necessita la integració. Aquest article s'adreça a responsables que actuen sobre el seu equip o àmbit de gestió.

Índex de continguts

Abans de començar

L'API permet que una integració autoritzada treballi amb informació de Talento. Cada credencial pertany a una persona activa de l'empresa: les sol·licituds s'executen amb els seus permisos i dins del mateix compte.

Aquest disseny permet aplicar el mateix control d'accés que a l'aplicació. També implica que triar la identitat, els permisos i la custòdia del token forma part de la seguretat de la integració.

Avís

Un token d'API funciona com una contrasenya. No l'enganxis en xats, tiquets, documents, adreces web ni repositoris de codi. Desa'l al gestor de secrets de la integració i transmet-lo únicament mitjançant HTTPS.

Autenticar una sol·licitud amb Bearer

Envia el token a la capçalera HTTP Authorization amb l'esquema Bearer:

Authorization: Bearer TU_TOKEN

Substitueix TU_TOKEN al sistema segur de configuració de la integració; no escriguis el valor real en exemples, registres ni codi font. Fes les crides contra l'adreça de l'empresa i el recurs d'API documentat per a l'operació.

L'API comprova tres condicions abans d'acceptar la sol·licitud:

que el token sigui vàlid;
que l'accés a l'API continuï actiu i la persona estigui activa;
que la persona tingui permís per a l'operació sol·licitada.

Registra els errors i els identificadors tècnics necessaris per al suport, però configura l'aplicació perquè oculti la capçalera Authorization i qualsevol secret.

Enviar mètriques de leads sense un endpoint dedicat

Un producte extern pot utilitzar camps personalitzats genèrics de Lead sense necessitar un endpoint propi a Talento. Primer crea o actualitza una definició a /api/v3/custom_field_definitions amb target_type: "Lead", un field_type escalar i track_history: true. Les definicions i les opcions de selecció utilitzen els UUID públics. Crear un Lead sempre valida tots els camps obligatoris de Lead, encara que s'ometi custom_fields.

Registra cada mesura a /api/v3/leads/{lead_uuid}/custom_field_observations amb l'UUID de la definició, un value del tipus correcte i, opcionalment, observed_at en ISO 8601, source i idempotency_key. El valor pot ser escalar, { "amount": 18, "currency_code": "eur" } per a moneda o null per buidar-lo. Reutilitzar una clau d'idempotència amb la mateixa sol·licitud canònica retorna l'observació original; si canvia la sol·licitud, retorna 409. Un valor invàlid, el seguiment desactivat o una data amb més de cinc minuts en el futur retorna 422.

Llista el mateix recurs per obtenir l'historial del més recent al més antic i filtrar-lo per definició o dates d'observació. Les respostes de llista i detall de Leads mostren les files de camps existents, inclosos observed_at i source; una definició que mai no s'ha establert s'omet.

Resoldre una resposta no autoritzada

Davant d'una resposta 401 No autoritzat, comprova, en aquest ordre:

que la capçalera utilitzi exactament l'esquema Bearer i no enviï el token a l'URL;
que el secret configurat sigui el token vigent i no un d'anterior a una rotació;
que l'accés a l'API continuï activat;
que la persona estigui activa i pertanyi a l'empresa des de la qual es fa la crida;
que l'adreça i el recurs sol·licitat siguin correctes.

Si l'autenticació funciona però no es permet una operació concreta, revisa els permisos de la persona. Concedeix només l'accés imprescindible; no converteixis la identitat en administradora per resoldre una integració limitada.

Problemes freqüents

Si una opció no apareix, pot dependre dels teus permisos, dels mòduls actius o de la configuració de l'empresa. Demana a administració que revisi aquest accés; no cal que repeteixis la tasca ni que triïs una alternativa que no correspongui.