---
name: fluig-integracoes
description: Integracoes REST, SOAP, Datasul/Protheus e APIs externas no TOTVS Fluig. Use quando precisar consumir APIs REST, chamar WebServices SOAP, iniciar processos via servico, ou sincronizar datasets com sistemas externos.
license: MIT
metadata:
  version: "1.0.0"
  author: Nevoa
  category: development
  platform: totvs-fluig
---

# Skill: fluig-integracoes

> Integracoes REST, SOAP, Datasul/Protheus e APIs externas no TOTVS Fluig.

## Quando Usar

- Dataset que consome API REST externa (CEP, CNPJ, ERP)
- Dataset que chama WebService SOAP via ServiceManager
- Chamada HTTP direta (java.net.URL) em eventos de processo
- Integracao com Datasul/Protheus via ExecBO ou REST
- Consumo de API com autenticacao (Basic, Bearer, token)
- Dataset sincronizado (onSync) para cache offline de API

## Tipos de Integracao

### 1. REST via fluigAPI (AuthorizeClientService)
**Metodo recomendado** - usa servico cadastrado no Painel do Fluig.

```javascript
// O servico deve estar cadastrado em:
// Painel do Fluig > Configuracoes > Servicos > Novo Servico REST

var clientService = fluigAPI.getAuthorizeClientService();
var data = {
    companyId: getValue("WKCompany") + '',
    serviceCode: 'nomeServico',      // codigo cadastrado no painel
    endpoint: '/recurso/123',         // path complementar
    method: 'GET',                    // GET, POST, PUT, DELETE
    timeoutService: '10000'           // timeout em ms (opcional)
};
var vo = clientService.invoke(JSON.stringify(data));
var resultado = JSON.parse(vo.getResult());
```

**Vantagens:**
- Autenticacao gerenciada pelo Fluig (Basic, OAuth, etc)
- URL base configurada no painel (nao hardcoded)
- Timeout configuravel
- Log automatico

### 2. REST via java.net.URL (HTTP direto)
Para quando nao ha servico cadastrado ou precisa de controle total.

```javascript
var url = new java.net.URL('https://api.exemplo.com/recurso');
var con = url.openConnection();
con.setRequestMethod('POST');
con.setDoOutput(true);
con.setDoInput(true);
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("charset", "utf-8");
con.connect();

// Enviar body
var printout = new java.io.DataOutputStream(con.getOutputStream());
var body = new java.lang.String(JSON.stringify(dados));
printout.write(body.getBytes("UTF-8"));
printout.flush();
printout.close();

// Ler resposta
var responseCode = con.getResponseCode();
var reader = new java.io.BufferedReader(
    new java.io.InputStreamReader(con.getInputStream()));
var linha = "";
var conteudo = "";
while ((linha = reader.readLine()) != null) {
    conteudo += linha;
}
reader.close();
var json = JSON.parse(conteudo);
```

### 3. SOAP via ServiceManager
Para WebServices WSDL cadastrados no Painel do Fluig.

```javascript
// Servico cadastrado em: Painel > Configuracoes > Servicos
var serviceProvider = ServiceManager.getService("nomeServico");
var serviceLocator = serviceProvider.instantiate("com.pacote.ServicoServiceLocator");
var service = serviceLocator.getServicoPort();

// Chamar metodo
var resultado = service.metodoDoServico(param1, param2);
```

### 4. Datasul ExecBO via ServiceManager
Para chamar procedures de business objects do Datasul.

```javascript
var serviceProvider = ServiceManager.getService("NomeServicoExecBO");
var serviceLocator = serviceProvider.instantiate("com.classe.Locator");
var service = serviceLocator.getPort();

var token = service.userLogin(usuario);
var resp = service.callProcedureWithToken(
    token, programName, procedureName, jsonParams);
```

### 5. Dataset Sincronizado (onSync)
Para cache offline de dados de API externa.

```javascript
function defineStructure() {
    addColumn("campo1");
    addColumn("campo2");
    setKey(["campo1"]);
    addIndex(["campo1", "campo2"]);
}

function onSync(lastSyncDate) {
    var dataset = DatasetBuilder.newDataset();
    // Chamar API e popular dataset
    // Usar addOrUpdateRow para upsert
    dataset.addOrUpdateRow(new Array(valor1, valor2));
    return dataset;
}

function createDataset(fields, constraints, sortFields) {
    // Retorna dados do cache local
}
```

## Servicos Comuns

Servicos REST: ViaCEP, ReceitaWS, Protheus REST, Datasul REST.
Servicos SOAP: ECMWorkflowEngineService, Document, ExecBO.

> Tabela completa de servicos, endpoints e classes: [references/servicos-e-endpoints.md](./references/servicos-e-endpoints.md)

## Checklist de Producao

- [ ] Servico REST cadastrado no Painel do Fluig (preferir fluigAPI)
- [ ] Timeout definido para evitar travamento
- [ ] try/catch em toda chamada externa
- [ ] Log de entrada e saida (log.info)
- [ ] Tratamento de erro HTTP (responseCode != 200)
- [ ] Credenciais NAO hardcoded (usar dataset de config ou servico)
- [ ] Conexoes fechadas em finally (java.net.URL)
- [ ] JSON.parse com try/catch (resposta pode nao ser JSON)
- [ ] Constraint para parametros (nao executar sem filtro)

## Prompts Estrategicos Disponiveis

- `criar-integracao-rest-fluigapi-authorize-client.md` - REST via `AuthorizeClientService` (padrao recomendado).
- `refatorar-integracao-http-java-url-hardening.md` - Hardening de integracao HTTP direta com `java.net.URL`.
- `implementar-integracao-soap-execbo-erp.md` - Integracao SOAP/ExecBO com ERP (Datasul/Protheus).
- `diagnosticar-integracao-fluig-erp-rest-soap.md` - Troubleshooting de integracoes Fluig x ERP (REST/SOAP).

Use estes prompts para implementacao e diagnostico de integracoes com foco em seguranca e observabilidade.
## Skills Relacionadas

- [fluig-datasets](../fluig-datasets/SKILL.md) — Datasets JDBC, ServiceManager, compostos
- [fluig-scripts-avancados](../fluig-scripts-avancados/SKILL.md) — Sub-processos, GED via WebService
- [fluig-eventos-processo](../fluig-eventos-processo/SKILL.md) — Eventos que disparam integracoes

## Templates Disponiveis

| Template | Descricao |
|---|---|
| `dataset-rest-fluigapi.js` | REST via fluigAPI.getAuthorizeClientService() |
| `dataset-rest-java-url.js` | REST via java.net.URL (POST/GET direto) |
| `dataset-soap-startprocess.js` | SOAP para iniciar processos via WebService |
| `dataset-sync-api.js` | Dataset sincronizado com onSync para cache de API |

## Recursos Adicionais

- Para templates base, consulte [templates/](./templates/)
- Para exemplos de implementacao real, consulte [examples/](./examples/)
### Exemplos recomendados
- [exemplo_01_datasul_execbo_helper_servicemanager](./examples/exemplo_01_datasul_execbo_helper_servicemanager/): helper base para integracao Datasul/ExecBO via `ServiceManager`.
- [exemplo_02_authorizeclient_rest_crud_substituto](./examples/exemplo_02_authorizeclient_rest_crud_substituto/): REST via `AuthorizeClientService` com operacoes CRUD e tratamento.
- Para referencia tecnica de servicos e endpoints, consulte [references/servicos-e-endpoints.md](./references/servicos-e-endpoints.md)
- Para prompts de uso, consulte [prompts/](./prompts/)

---

## Curadoria de Contexto Local

Para buscar exemplos reais no acervo local `Contexto`, consulte [references/contexto-curadoria.md](./references/contexto-curadoria.md).
Abra essa referencia quando a tarefa exigir aderencia a legado/producao ou comparacao com implementacoes existentes.
