Ir al contenido
Desarrolladores

Primeros pasos

De cero al primer pedido: qué necesita la cuenta, cómo se crea el token y tres pedidos con curl para comprobar que todo anda.

Antes de empezar

  • La cuenta tiene que tener activo API y MCP, dentro de Administración. Si no aparece en el menú, se pide a Kaptativa.
  • Tu usuario necesita permiso para crear tokens en esa pantalla.
  • La cuenta tiene que estar en período de prueba, activa o en gracia. Una cuenta suspendida no responde por la API.

1. Creá un token en el panel

  1. Entrá al panel y abrí Administración > API y MCP.
  2. En Crear un token, ponele un nombre que te deje reconocerlo después, como el del sistema que lo va a usar.
  3. En Qué puede hacer elegí Solo ver, Ver y hacer cambios o Elegir por módulo (son los alcances), y en Vence, cuándo deja de valer: en 30 días, en 90 días, en un año o no vence.
  4. Tocá Crear el token y copialo en ese momento.
El token se muestra una sola vez

Kaptativa guarda solo su huella, no el token. Si lo perdés, revocalo y creá otro. Guardalo como una contraseña: en un gestor de secretos o en una variable de entorno, nunca en el código ni en un repositorio.

El token empieza con kpt_ y es de la persona que lo creó: actúa con sus permisos de hoy. Si a esa persona le sacan un permiso, el token también lo pierde.

2. Probá el token

Guardalo en una variable para no pegarlo en cada comando. En los ejemplos del portal aparece como TU_TOKEN.

Guardar el token en la terminal
export KAPTATIVA_TOKEN="TU_TOKEN"

El primer pedido no cambia nada: dice a qué cuenta llega el token y cuántas operaciones puede usar.

Primer pedido
curl "https://panel.kaptativa.app/api/v1" \
  -H "Authorization: Bearer $KAPTATIVA_TOKEN"
Respuesta, 200
{
  "version": "v1",
  "cuenta": {
    "nombre": "Inmobiliaria del Centro"
  },
  "token": {
    "nombre": "Sistema de gestión",
    "alcance": "Ver y hacer cambios",
    "alcances": [
      "*:lectura",
      "*:escritura"
    ],
    "de": "Ana García"
  },
  "herramientas": 80
}

Si responde 401, el token está mal copiado, venció o se revocó. Si responde 403 con el código no_activo, la cuenta no tiene activa la API. El detalle de cada código está en Errores.

3. Mirá qué puede hacer

Este pedido lista las operaciones que ese token puede usar hoy, cada una con el esquema JSON de su entrada. Depende de los módulos activos de la cuenta, de los alcances del token y de los permisos de su persona.

Operaciones disponibles para el token
curl "https://panel.kaptativa.app/api/v1/herramientas" \
  -H "Authorization: Bearer $KAPTATIVA_TOKEN"

4. Leé un dato

Busca clientes por nombre, email o documento y muestra su tipo, contacto y vendedor; sin texto, los más recientes.

GET /v1/gestion/clientes
curl "https://panel.kaptativa.app/api/v1/gestion/clientes?limite=25" \
  -H "Authorization: Bearer $KAPTATIVA_TOKEN"

Un recurso responde 200 con el objeto tal cual; un listado como este trae datos y paginacion (mirá Paginación). Los campos de cada operación están en la referencia.

5. Hacé un cambio

Da de alta un cliente con nombre y, si se sabe, apellido, email y teléfono; queda con el tipo Cliente. Necesita un token con escritura en el módulo (gestion:escritura).

POST /v1/gestion/clientes
curl -X POST "https://panel.kaptativa.app/api/v1/gestion/clientes" \
  -H "Authorization: Bearer $KAPTATIVA_TOKEN" \
  -H "Idempotency-Key: 8b1f6c1e-2d0a-4a53-9c0b-0c4e3d7a9f21" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Ana","apellido":"García","email":"ana@ejemplo.com"}'

El encabezado Idempotency-Key deja repetir el pedido sin crear el cliente dos veces si se corta la conexión: está explicado en Idempotencia. Lo que cambia queda en la Actividad de la cuenta, a nombre del token y de su persona.

Si un campo está mal, 422
{
  "error": {
    "codigo": "entrada",
    "mensaje": "email: Invalid email address",
    "pedido": "ped_3f9a1c0b7d2e4f6a8b1c2d3e4f5a6b7c",
    "detalles": [
      {
        "campo": "email",
        "mensaje": "Invalid email address"
      }
    ]
  }
}

Por dónde seguir