APIs, autenticação e integrações

O NEO expõe principalmente dois modelos de integração:

• RPC via métodos whitelisted;

• REST via api/resource.

RPC com métodos whitelisted

import neo

@neo.whitelist()
def get_open_tasks():
    return neo.get_list("Task", filters={"status": "Open"}, fields=["name", "subject"])

Cliente:

neo.call({
    method: "biblioteca.api.get_open_tasks",
    callback(r) {
        console.log(r.message);
    }
});

REST nativo por DocType

Operação	Endpoint
Criar	POST /api/resource/Task
Ler por nome	GET /api/resource/Task/TASK-0001
Atualizar	PUT /api/resource/Task/TASK-0001
Remover	DELETE /api/resource/Task/TASK-0001
Listar	GET /api/resource/Task

Quando usar RPC e quando usar REST

RPC

Melhor para comandos de negócio como aprovar, recalcular, consolidar ou sincronizar.

REST

Melhor para manipulação padronizada de recursos por sistemas externos.

Autenticação

A autenticação pode envolver:

• sessão/cookie;

• login interativo;

• chaves de API;

• mecanismos corporativos adicionais.

Desk e portal tendem a usar sessão. Integrações servidor-servidor normalmente usam chave ou fluxo dedicado.

Consumo pelo front-end do NEO

No Desk ou no portal, neo.call é a forma mais comum de consumir o backend.

Boas práticas:

• métodos pequenos e claros;

• validação de permissões no servidor;

• retorno enxuto;

• feedback de erro na UI.

Exemplo de endpoint para botão de formulário

import neo

@neo.whitelist()
def renew_membership(name, new_to_date):
    doc = neo.get_doc("Library Membership", name)
    doc.to_date = new_to_date
    doc.save()
    return {"name": doc.name, "to_date": doc.to_date}

Cliente:

neo.call({
    method: "biblioteca.membership.api.renew_membership",
    args: {
        name: frm.doc.name,
        new_to_date: values.to_date
    },
    callback(r) {
        frm.reload_doc();
        neo.msgprint(`Nova data final: ${r.message.to_date}`);
    }
});

Segurança em métodos whitelisted

Ao expor um método:

• valide usuário e contexto;

• cheque permissões;

• não aceite filtros arbitrários sem controle;

• evite retornar dados sensíveis.

Integrações assíncronas

Quando a operação é custosa:

1. a UI chama a API;

2. o backend valida;

3. o job é enfileirado;

4. a interface recebe confirmação imediata;

5. o resultado chega por refresh ou realtime.