Manual de uso do conector-modelo

Este manual é destinado aos programadores que irão consumir o conector-modelo pelo catálogo de mensagens do SISC. Ele também serve como padrão de qualidade para novos manuais: documente o que o conector faz, quais mensagens ele aceita, quais campos entram em payload.dados, como interpretar a saída e quais cuidados o consumidor deve tomar.

Identificação

Conector: conector-modelo
Destino SISC: conector__conector-modelo
catalogo modular: web-api/catalogo-conector-modelo.json
idmensagem principal: conector-modelo.eco
Formato de dados: conectores/conector-modelo/formatos/formato-conector-modelo.json

Objetivo

Demonstrar um conector simples e previsível. A mensagem conector-modelo.eco recebe um texto, valida os campos de entrada e devolve uma confirmação com o texto recebido. Conectores reais devem substituir esta operação demonstrativa pelo serviço integrado, mantendo a documentação focada na mensagem do catalogo, nos campos do payload e na resposta esperada.

Operações disponíveis

Operação	idmensagem	Campos principais	Descrição
Eco	`conector-modelo.eco`	`operacao`, `texto`	Retorna confirmação com o texto recebido. É uma operação sem efeito externo.

Payload de entrada

Os dados de negócio devem ser enviados em payload.dados. O consumidor não precisa conhecer a implementação interna do conector; basta usar o idmensagem publicado no catalogo e preencher os campos abaixo.

Campo	Tipo	Obrigatório	Descrição
`operacao`	string	sim	Deve ser `eco`.
`texto`	string	sim	Texto não vazio que será devolvido ao consumidor.

Exemplo de payload simples

{
  "operacao": "eco",
  "texto": "mensagem de validacao local"
}

Exemplo de mensagem SISC

{
  "_protocolo": {
    "origem": "sistema__operador",
    "destino": "conector__conector-modelo",
    "idmensagem": "conector-modelo.eco"
  },
  "payload": {
    "dados": {
      "operacao": "eco",
      "texto": "mensagem de validacao local"
    }
  }
}

Exemplo de envelope completo para teste controlado

{
  "_sistema": {
    "criadoPor": "sistema__operador"
  },
  "_protocolo": {
    "nome": "siscore-protocolo-objetos",
    "versao": 1,
    "processoId": "proc-conector-modelo-0001",
    "mensagemId": "msg-conector-modelo-0001",
    "origem": "sistema__operador",
    "destino": "conector__conector-modelo",
    "tipo": "comando",
    "prioridade": "normal",
    "idempotencia": {
      "chave": "modelo-eco-001",
      "escopo": "conector-modelo.eco"
    }
  },
  "payload": {
    "idmensagem": "conector-modelo.eco",
    "dados": {
      "operacao": "eco",
      "texto": "mensagem de validacao local"
    }
  }
}

Saída esperada

A resposta de sucesso informa se a operação foi aceita, qual conector processou a mensagem, a operação executada e o texto normalizado. Consumidores devem tratar campos extras como extensões compatíveis.

{
  "sucesso": true,
  "conector": "conector-modelo",
  "operacao": "eco",
  "texto": "mensagem de validacao local",
  "mensagemId": "msg-conector-modelo-0001",
  "processoId": "proc-conector-modelo-0001"
}

Programa de exemplo

O pacote traz um programa PHP de exemplo em conectores/conector-modelo/exemplos/exemplo-uso.php. Ele demonstra como um consumidor monta a mensagem do catalogo e o objeto payload.dados para a operação eco.

php conectores/conector-modelo/exemplos/exemplo-uso.php

O mesmo programa possui modo de autoverificação, usado para comprovar que o exemplo produz o JSON que declara produzir.

php conectores/conector-modelo/exemplos/exemplo-uso.php --self-test

Credenciais necessárias

Este conector não usa credenciais reais. O arquivo de exemplo secretos/conector-modelo.sample.json existe apenas para documentar a decisão.

Em conectores reais, esta seção deve dizer exatamente quais credenciais o operador do ambiente precisa configurar, sem expor valores reais. O manual deve conter nomes de campos e finalidade, nunca senhas, tokens, chaves privadas ou certificados privados.

Erros comuns

Erro	Causa provável	Ação recomendada
`operacao invalida`	`payload.dados.operacao` não é `eco`.	Enviar `operacao=eco`.
`campo texto e obrigatorio`	Campo `texto` ausente, vazio ou de tipo incorreto.	Enviar `texto` como string não vazia.
`payload.dados ausente`	A mensagem não colocou os dados no local esperado.	Montar a mensagem com o objeto `payload.dados`.
`idmensagem desconhecido`	O consumidor usou nome de mensagem diferente do declarado no catalogo.	Usar `conector-modelo.eco` ou consultar a versão atual do catalogo.

Limites

Item	Limite ou regra
Tamanho do texto	Deve ser pequeno o suficiente para trafegar como payload textual comum do SISC.
Efeito externo	Nenhum. Este conector é demonstrativo.
Compatibilidade	Novos campos de saída devem ser opcionais para consumidores antigos.

Segurança de uso

Não envie segredos no payload. Mesmo quando um conector real exigir credenciais, elas pertencem à configuração do ambiente, não à mensagem de negócio.

Use idempotencia estável para evitar repetição acidental de operações públicas.
Use apenas o idmensagem declarado no catalogo do conector.
Não dependa de nomes de arquivos, scripts ou detalhes internos do servidor para consumir a integração.
Registre no seu sistema consumidor o processoId e o mensagemId quando precisar auditar uma chamada.

Boas práticas para consumidores

Validar campos obrigatórios antes de publicar a mensagem.
Tratar resposta de erro de forma explícita, sem assumir sucesso.
Ignorar campos desconhecidos de saída para manter compatibilidade futura.
Consultar este manual e o catalogo modular sempre que o conector mudar de versão.