Exibir origem

Produto:	Datasul
Ocorrência:	Documentação de API
Nome físico:	cdp/rules/cadNbsRules.p

Objetivo

Esta API tem como objetivo gerenciar as regras de negócio da entidade Cadastro NBS (Tabela cad-nbs), permitindo operações de inclusão, alteração, exclusão, consulta, além de importação e exportação de dados via arquivos CSV.

A API valida as regras de integridade (formato do código, duplicidade) e persiste os dados no banco.

Funcionamento

A API fornece uma série de métodos que podem ser executados individualmente. A sintaxe para a chamada da API deve ser feita de forma persistente em Progress:

RUN cdp/rules/cadNbsRules.p PERSISTENT set h-handle.

A variável denominada h-handle irá receber o “handle” do programa, permitindo o acesso aos “métodos” internos da API.

Método Negócio

Quando a API estiver executada em modo persistente, os seguintes métodos estarão disponíveis para execução:

pi-query-v1

Requisito

Nenhum.

Descrição

Realiza a busca de registros de NBS com suporte a paginação e filtros.

Parâmetros Tipo Input/Output Descrição

oInput

JsonObject

INPUT

Parâmetros de filtro e paginação:

queryParams:

• searchBy: Array de strings para busca rápida (filtra por código ou descrição).

• pageSize: Quantidade de registros por página (Default: 20).

• startRow: Registro inicial.

{
  "queryParams": {
    "searchBy": ["Serviço"],
    "pageSize": 10
  }
}

aOutput JsonArray OUTPUT Lista de registros encontrados (vide estrutura CadNbs).

lHasNext Logical OUTPUT Indica se existem mais páginas a serem buscadas.

RowErrors Temp-table OUTPUT Informações sobre erros ocorridos.

RowErrors Temp-table OUTPUT Informações sobre os erros ocorridos durante o processo.

Retorno

Retorna a lista de códigos NBS ou erros ocorridos durante a busca.

pi-get-v1
Requisito	Nenhum.
Descrição	Retorna os dados detalhados de um único registro de NBS com base na chave informada.
	Parâmetros	Tipo	Input/Output	Descrição
	oInput	JsonObject	INPUT	pathParams: Deve conter o ID do registro (`codNbs`).
	oOutput	JsonObject	OUTPUT	Objeto contendo os dados do registro (vide estrutura `CadNbs`).
	RowErrors	Temp-table	OUTPUT	Informações sobre erros ocorridos (ex: Registro não encontrado).
Retorno	Retorna os dados detalhados de um único registro de NBS com base na chave informada.

pi-create-v1

Requisito

Nenhum.

Descrição

Cria um novo registro na tabela de NBS.

Parâmetros Tipo Input/Output Descrição

oInput

JsonObject

INPUT

Payload contendo os dados:

• codNbs: Código do NBS (Obrigatório, chave única).

• descNbs: Descrição do NBS.

{
  "codNbs": "1.0101.20.10",
  "descNbs": "Análise e desenvolvimento de sistemas"
}

oOutput JsonObject OUTPUT Retorna o registro criado.

RowErrors Temp-table OUTPUT Erros de validação (ex: registro duplicado).

pi-update-v1
Requisito	Nenhum.
Descrição	Altera um registro existente na tabela de NBS.
	Parâmetros	Tipo	Input/Output	Descrição
	oInput	JsonObject	INPUT	pathParams: ID do registro (`codNbs`). Payload: Campos a serem alterados (ex: `descNbs`).
	oOutput	JsonObject	OUTPUT	Retorna o registro atualizado.

pi-delete-v1
Requisito	Nenhum.
Descrição	Exclui um registro existente na tabela de NBS.
	Parâmetros	Tipo	Input/Output	Descrição
	oInput	JsonObject	INPUT	pathParams: Informar o `codNbs` do registro a ser eliminado.
	RowErrors	Temp-table	OUTPUT	Retorna erros caso o registro não possa ser excluído.

pi-delete-list-v1

Requisito

Nenhum.

Descrição

Exclui uma lista de registros (lote).

Parâmetros Tipo Input/Output Descrição

oInput

JsonObject

INPUT

Payload: Array de objetos contendo a chave codNbs para exclusão.

[
  { "codNbs": "1.0101.20" },
  { "codNbs": "1.0101.21" }
]

aDeletedIdList JsonArray OUTPUT Lista dos IDs que foram excluídos com sucesso.

pi-import-v1
Requisito	Nenhum.
Descrição	Realiza a importação de um arquivo CSV para a tabela de NBS. Regras de validação aplicadas linha a linha: Código ou descrição não podem ser vazios. Tamanho do código deve ser de 9 caracteres (contando pontuação). O código deve ser numérico (removendo pontuação). Verifica duplicidade de chave.
	Parâmetros	Tipo	Input/Output	Descrição
	oInput	JsonObject	INPUT	Payload: Deve conter o array `multiPartFile`. O conteúdo do arquivo deve vir em Base64 no atributo `content`.
	oOutput	JsonObject	OUTPUT	Se houver linhas com erro, retorna um arquivo CSV (`ErrosImportacaoNBS.csv`) listando as linhas rejeitadas e o motivo. Se sucesso total, retorna "OK".

pi-export-v1
Requisito	Nenhum.
Descrição	Gera um arquivo CSV contendo todos os registros da tabela `cad-nbs`.
	Parâmetros	Tipo	Input/Output	Descrição
	oInput	JsonObject	INPUT	Parâmetros gerais (vazio para exportação total).
	oOutput	JsonObject	OUTPUT	Retorna objeto com: • `FN_File`: Nome do arquivo (`ModeloCadastroNbs.csv`). • `DN_File`: Conteúdo do arquivo em Base64.

pi-download-v1
Requisito	Nenhum.
Descrição	Disponibiliza o download de um modelo (template) vazio de arquivo CSV para ser utilizado na importação.
	Parâmetros	Tipo	Input/Output	Descrição
	oOutput	JsonObject	OUTPUT	Retorna o arquivo de modelo em Base64.

Temp-Tables

RowErrors				Entrada/Saída
Temp-table com dados dos erros ocorridos durante o processo				Saída
Atributo	Tipo	Descrição	Obrigatório	Evolução
`ErrorSequence`	INTEGER	Número da sequência do erro.	Sim	Não se aplica
`ErrorNumber`	INTEGER	Código do erro.	Sim	Não se aplica
`ErrorDescription`	CHARACTER	Descrição detalhada do erro.	Não	Não se aplica
`ErrorType`	CHARACTER	Tipo do erro (Ex: ERROR, INTERNAL).	Não	Não se aplica
`ErrorSubType`	CHARACTER	Subtipo do erro.	Não	Não se aplica

CadNbs					Entrada/Saída
Temp-table com os campos a serem retornados na busca dos códigos de NBS.					Saída
Atributo	Nome no Objeto (JSON)	Tipo	Descrição	Obrigatório	Evolução
`cod-nbs`	codNbs	Character	Código da Nomenclatura Brasileira de Serviços (Chave).	Sim	Não se aplica
`desc-nbs`	descNbs	Character	Descrição do serviço.	Sim	Não se aplica