orkasa
ENEntrar

Recursos

Documentos, firmas y agentes

Tres recursos de solo lectura, deliberadamente estrechos.

GET /documents?scope=&status=&type=&lead_id=&operation_id=&property_id=
GET /signatures?status=&template=&operation_id=&property_id=&signer_email=
GET /agents?role=&office_id=&email=

signer_email y email emparejan sin distinguir mayúsculas.

Solo lectura, y a propósito

Cada uno tiene su propio serializador que nombra uno por uno los campos que devuelve. Ninguno es un select *. Lo que dejan fuera es el punto:

  • un documento expone su referencia de archivo, pero ninguna ruta de almacenamiento y ninguna URL de descarga;
  • una firma expone su estado y su firmante, pero nunca el token de firma, la ruta del PDF ni el bloque de variables desde el que se compuso;
  • un agente expone la identidad profesional que un Zap necesita para encaminar trabajo — nombre, correo, rol, oficina — y nada más.

Una integración puede enterarse de que un mandato se firmó sin recibir con ello los medios para abrirlo.

Y sus permisos de escritura no existen

documents:write, signatures:write y agents:write están en el vocabulario para que la gramática sea uniforme y un endpoint futuro no obligue a migrar nada. Hoy ninguna ruta los consume: concederlos no compra nada.

El estado de un documento tiene dos valores que significan « ya está »: received y verified. Un filtro que compare solo contra received deja atascado lo que alguien ya verificó.

La identidad conectada

curl "$ORKASA_API/me" -H "Authorization: Bearer $ORKASA_KEY"
{
  "brokerage_id": "0d1f…",
  "brokerage_name": "Casa Móvil Panamá",
  "scopes": ["leads:read", "leads:write", "operations:read"]
}

GET /me vive fuera del conjunto de recursos y devuelve un objeto plano, sin envoltorio data, para que Zapier pueda usarlo tal cual como prueba y etiqueta de la conexión. Requiere leads:read.