Capítulo 5 de 6 · 15 min

La API pública

Prendés la API, creás una API key y desde código creás un Contact, leés un Case y le cambiás el estado, con los permisos de quien creó la key.

La API pública trabaja directamente sobre los registros: crear, leer, listar, actualizar y borrar, en cualquier entidad. No hay automation en el medio, pero sí todo lo demás: las validaciones de los campos, las automations de la entidad, el historial y los permisos.

Método y ruta	Qué hace
`GET /public/v1/me`	Devuelve a quién pertenece la key. Sirve para probar la conexión
`GET /public/v1/data/{entidad}`	Lista registros, de a 50 (hasta 200 con `?limit=`)
`GET /public/v1/data/{entidad}/{id}`	Lee un registro
`POST /public/v1/data/{entidad}`	Crea un registro
`PATCH /public/v1/data/{entidad}/{id}`	Cambia sólo los campos que mandás
`DELETE /public/v1/data/{entidad}/{id}`	Borra un registro

{entidad} es el API name de la entidad, en singular: contact, case, account, opportunity. Lo ves entre paréntesis al lado de cada entidad, por ejemplo Case (case). Los campos van por su API name: subject, status, email.

Prendé la API

ConfiguraciónIntegraciones y APIEndpointsAPI Config

En Acceso al API, marcá Habilitar API Pública para este tenant. Se guarda en el momento. Mientras esté apagada, toda llamada con API key recibe 503 API_DISABLED: es el interruptor general para cortar todo sin revocar keys una por una.

Creá una API key

En la tarjeta API Keys, Crear API key:

Nombre: Backend de la tienda.
Rate limit (requests/minuto): dejá 1000.
Origins CORS permitidos: vacío. La tienda llama desde su servidor, no desde el navegador.
Allowlist de IP: si el servidor de la tienda tiene una IP fija, ponela (por ejemplo 203.0.113.10/32); así la key no sirve desde otro lado.

Hacé clic en Crear. Se abre API key ‘Backend de la tienda’ creada con el token: Copiar, guardalo en los secretos del servidor y Listo.

Diálogo Crear API key con el nombre Backend de la tienda y el rate limit en 1000 — La IP allowlist es la protección más barata: una key filtrada no sirve fuera de tu servidor.

Probá la conexión

curl "https://tu-workspace.nx-ar.com/public/v1/me" \
  -H "Authorization: Bearer nxar_api_REEMPLAZAR_POR_TU_KEY"

Responde con el usuario dueño de la key: su id, email, nombre y permisos.

Creá un Contact

curl -X POST "https://tu-workspace.nx-ar.com/public/v1/data/contact" \
  -H "Authorization: Bearer nxar_api_REEMPLAZAR_POR_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Gómez","email":"ana@ejemplo.com","phone":"+54 11 5555-0000"}'

Status 201 y el registro creado, con su id:

{"data":{"id":"b2d4…","data":{"name":"Ana Gómez","email":"ana@ejemplo.com","phone":"+54 11 5555-0000"},…},"meta":{}}

El cuerpo son los campos sueltos, sin envolver. Lo que la entidad exige se exige igual: sin name, que es obligatorio en Contact, la respuesta es 400 VALIDATION con el campo en details.

Resolvé un Case

Con el id de un Case (el case_id que devolvió el endpoint del capítulo 2, o el último tramo de la dirección cuando abrís el Case en Nxar):

curl -X PATCH "https://tu-workspace.nx-ar.com/public/v1/data/case/ID_DEL_CASE" \
  -H "Authorization: Bearer nxar_api_REEMPLAZAR_POR_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"Resolved"}'

PATCH cambia sólo status; el resto del Case queda como estaba. El valor tiene que ser uno de los del picklist tal como está guardado (New, In progress, Waiting customer, Resolved, Closed).

API Config con la API habilitada y la key Backend de la tienda con su último uso — Cada key muestra su prefijo, su rate limit y cuándo se usó por última vez. Desde acá se revoca.

Con qué permisos corre

La key actúa como el usuario que la creó. Todo lo que haga pasa por sus permisos y su visibilidad, igual que si esa persona estuviera usando Nxar, y los registros que cree quedan a su nombre. Si la creó Julieta, que es administradora, la key puede todo lo que puede Julieta. Por eso:

Tratala como una contraseña: nunca en el código de la página, en un repositorio ni en un mail.
Usá la allowlist de IP cuando puedas.
Si se filtró, Revocar en la lista. Revocada, deja de funcionar al instante y queda registro de que existió; Eliminar la borra del todo.

La API lista registros pero todavía no filtra por campo: no podés pedir “el Contact con este email”. Si necesitás buscar antes de escribir, armá un endpoint (capítulo 2) con un nodo Obtener registro que busque por email.

Para depurar las llamadas a /public/v1/data, prendé Loguear requests a endpoints standard en API Config: las llamadas aparecen en Audit Logs (en Endpoint, /data/* (records)) con su Request y su Response. Dejalo apagado cuando termines: guarda los cuerpos durante 30 días.

Cómo saber que te salió

GET /public/v1/me responde con tu usuario.
En Contacts está Ana Gómez, creada por la API, a tu nombre.
El Case que elegiste quedó en Resolved.
Si apagás Habilitar API Pública y repetís el curl de /me, recibís un error 503 API_DISABLED; prendela de nuevo al terminar.

¿Llegaste al resultado de arriba?

En la referencia