[API] - Editar solicitação de apropriação
Origem
A origem dessa demanda provém de uma parceria estabelecida com o Fundo Nacional de Desenvolvimento da Educação (FNDE).
A necessidade subjacente é a criação de endpoint para recebimento de alteração de apropriação de instrumento(s) de cobrança(s).
Isso envolve garantir que o CONTRATOS receba a operação e que, ao mesmo tempo, sejam enviados ao SIAFI por meio do endpoint já utilizado pelo sistema.
Além disso, é imprescindível que as mesmas validações que fazemos em tela, sejam replicadas para a API durante a requisição.
Descrição
A demanda em questão requer a criação de 01 (um) endpoint, ou seja, criar API para editar informações de uma apropriação cadastrada no CONTRATOS com status "Apropriacao em Andamento", ou seja, não enviada para o Sistema Integrado de Administração Financeira do Governo Federal (SIAFI).
A validação dos dados, devem seguir de acordo com a existente no CONTRATOS (Gestão Financeira > Apropriação > Instrumento Cobrança > Ações > Apropriação de Fatura > Editar), ou seja, garantir a precisão das informações.
Cada requisição enviada para o Contratos, deverá ter um número único de identificação (NONCE);
Deve garantir que todos o "id_apropriacao_inst_cobranca" enviado esteja com status "Apropriacao em Andamento" e que não haja nenhuma outra apropriação vinculada as instrumento de cobrança;
Perfil de acesso: Execução Financeira e Acesso API;
Cada requisição enviada para os contratos deve validar a autenticação do usuário antes de utilizar a API.
Cada requisição enviada deve excluir os dados anteriormente enviados e considerar sempre as informações do último envio.
Além disso, cada requisição enviada para os contratos deve verificar se a Unidade Gestora (UG) do contrato vinculado a apropriação do instrumento de cobrança pertence às unidades do usuário (sejam primárias ou secundárias).
Retornar a "mensagem" do CONTRATOS somente se não houver mensagem do SIAFI.
Como responsável por realizar a edição de apropriação de instrumentos de cobranças,
Quero receber de sistemas financeiros de órgãos da Administração pública que utilizam o SIAFI com o sistema Contratos.gov.br as informações de edição de uma apropriação de instrumentos de cobrança,
Para que seja possível editar e salvar na base de dados do Contratos e enviar para o SIAFI para geração do DH.
Critérios de Aceitação
1. Criar API
1.1. Nome: Editar Apropriação de Instrumento de Cobrança
1.2. Método: PUT
1.3. URI do recurso: /api/v1/contrato/apropriacao/editar
1.4. Dados de Entrada
Id | Campo | Tipo | Obrigatório | Descrição |
---|---|---|---|---|
1 | nonce | String (100) | Sim | Código único que identifica a requisição |
2 | cod_ug_emitente | Integer | Sim | Código da Ug Emitente do DH |
3 | id_apropriacao_inst_cobranca | Integer | Sim | ID da apropriação do instrumento de cobrança |
4 | data_emissao_contabil | Date (8) | Sim | Data de emissão contábil (YYYY-MM-DD) |
5 | data_vencimento | Date (8) | Sim | Data de vencimento (YYYY-MM-DD) |
6 | taxa_cambio | Number (15,2) | Sim | Valor da taxa de câmbio ($float) |
7 | processo | String (255) | Sim | Número do processo (00000.000000/0000-00) |
8 | ateste | Date (8) | Sim | Data de ateste (YYYY-MM-DD) |
9 | observacao | String (468) | Não | Texto de observação |
10 | informacoes_adicionais | String (500) | Sim | Texto de informações adicionais |
11 | situacao | Objeto | Sim | Bloco de informação que representam as situações dos instrumentos de cobranças |
11.1 | cod_situacao | String (255) | Sim | Código da situação SIAFI (DSP000) |
11.2 | indicador_contrato | Boolean | Sim | Indicador se tem contrato (true, false) |
11.3 | despesa_antecipada | Boolean | Não | Indicador se é despesa antecipada (true, false) |
11.4 | txtinscrd | String (500) | Não | campo variavel txt d |
11.5 | txtinscre | String (500) | Não | campo variavel txt e |
11.6 | numclassd | String (500) | Não | campo variavel class d |
11.7 | numclasse | String (500) | Não | campo variavel class e |
11.8 | Empenho | Objeto | Sim | Bloco de informação que representam os empenhos dos instrumentos de cobranças por situação |
11.8.1 | numero_empenho | String (255) | Sim | Número do empenho |
11.8.2 | subelemento | Integer | Sim | Código do subelemento |
11.8.3 | indicador_liquidado | Boolean | Sim | Indicador se o empenho está liquidado (true, false) |
11.8.4 | valor_item | Number (15,2) | Sim | Valor do item ($float) |
11.8.5 | txtinscra | String (500) | Não | campo variavel txt a |
11.8.6 | txtinscrb | String (500) | Não | campo variavel txt b |
11.8.7 | txtinscrc | String (500) | Não | campo variavel txt c |
11.8.8 | numclassa | String (500) | Não | campo variavel class a |
11.8.9 | numclassb | String (500) | Não | campo variavel class b |
11.8.10 | numclassc | String (500) | Não | campo variavel class c |
12 | data_pagamento | Date (8) | Sim | Data de pagamento (YYYY-MM-DD) |
13 | centro_custo | Objeto | Não | Bloco de informação que representam os centros de custo dos instrumentos de cobranças |
13.1 | item_centro_custo | Objeto | Sim | Bloco de informação que representam as situações do centro de custo dos instrumentos de cobranças |
13.1.1 | cod_situacao | String (255) | Sim | Código da situação SIAFI (DSP000) |
13.1.2 | Numero_empenho | String (255) | Sim | Número do empenho |
13.1.3 | valor_item | Number (15,2) | Sim | Valor do item ($float) |
13.2 | cod_centro_custo | String (255) | Não | Número sequencial do centro de custo |
13.3 | mes | Integer | Não | Mês de referência |
13.4 | ano | Integer | Não | Ano de referência |
13.5 | codigo_siorg | Integer | Não | Código do SIORG |
13.6 | ug_beneficiada | Integer | Não | Código da Ug do Empenho |
1.4. Dados de Retorno
Id | Campo | Tipo | Obrigatório | Descrição |
---|---|---|---|---|
1 | Apropriacao | Objeto | Não | Bloco de informações que representam os IDs das apropriações dos instrumentos de cobrança |
1.1 | id_apropriacao_inst_cobranca | Integer | Sim | ID da apropriação do instrumento de cobrança |
1.2 | status | String | Sim | Status retornado pela API (SUCESSO/ERRO) |
1.3 | mensagem | String | Sim | Mensagem retornada pela API |
1.4 | situacao | String | Sim | Situação da apropriação no contratos |
1.4. Códigos de Retorno
Mensagem | Tipo | Descrição |
---|---|---|
Apropriação incluída com sucesso. | Sucesso | Operação de inclusão da apropriação bem-sucedida |
Token expirado. | Erro | Falha de autorização devido à expiração do token |
Código Nonce em outra requisição | Erro | Ação não executada devido ao uso prévio do código Nonce em outra requisição |
Usuário sem permissão no contrato para apropriação. | Erro | Falta de permissão do usuário para ação no contrato |
Usuário sem permissão no sistema | Erro | Falta de permissão do usuário para utilizar a API |
Status da apropriação não permiti edição. | Erro | Operação não concluída, status da apropriação não permiti edição |
Apropriação não encontrada. | Erro | Apropriação especificada não foi encontrada |
Campo {campo} é obrigatório. | Erro | Requisição não atende aos requisitos do contrato da API devido à falta de campo |
Erro interno do servidor | Erro | Erro interno no servidor, a aplicação está inacessível |
3. É necessário gravar no banco de dados todas as requisições enviadas para o módulo Contratos, mesmo que sejam repetidas.
4. Atualizar documentação da API no Swagger do sistema
Observações para o desenvolvedor
Tabelas de Domínio
1. indicador_contrato (Indicador se tem contrato)
- (código = true) Tem contrato: Utilizado na API do item 1.1.1.
- (código = false) Não tem contrato: Utilizado na API do item 1.1.1.
2. despesa_antecipada (Indicador se é despesa antecipada)
- (código = true) É despesa antecipada: Utilizado na API do item 1.1.1.
- (código = false) Não é despesa antecipada: Utilizado na API do item 1.1.1.
3. indicador_liquidado (Indicador se o empenho está liquidado)
- (código = true) Está liquidado: Utilizado na API do item 1.1.1.
- (código = false) Não está liquidado: Utilizado na API do item 1.1.1.
Roteiro de Testes
Cenário 1: Requisição válida de edição com sucesso*
Pré-condições:
O sistema está funcionando corretamente. O usuário possui autorização para a ação no contrato. A apropriação do instrumento de cobrança possui o status "Apropriação em Andamento". Não há outras apropriações vinculadas ao mesmo instrumento de cobrança. Ação:
O usuário faz uma requisição válida para a API "Editar Apropriação de Instrumento de Cobrança". Validações:
Verificar se a requisição é bem-sucedida. Verificar se a apropriação do instrumento de cobrança é atualizada corretamente. Verificar se o status retornado é "SUCESSO". Verificar se a mensagem de retorno é apropriada.
Cenário 2: Token expirado
Pré-condições:
O sistema está funcionando corretamente. O token de autenticação expirou. Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança" com um token expirado. Validações:
Verificar se a requisição retorna um código de erro (Token expirado).
Cenário 3: Código Nonce em outra requisição
Pré-condições:
O sistema está funcionando corretamente. O código Nonce já foi utilizado em outra requisição. Ação:
O usuário faz uma nova requisição para a API "Editar Apropriação de Instrumento de Cobrança" com o mesmo código Nonce. Validações:
Verificar se a requisição retorna um código de erro (Código Nonce em outra requisição).
Cenário 4: Falta de permissão no contrato para edição
Pré-condições:
O sistema está funcionando corretamente. O usuário não possui permissão para a ação no contrato. Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança". Validações:
Verificar se a requisição retorna um código de erro (Usuário sem permissão no contrato para edição).
Cenário 5: Status da apropriação não permite edição
Pré-condições:
O sistema está funcionando corretamente. A apropriação do instrumento de cobrança possui um status que não permite a edição. Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança". Validações:
Verificar se a requisição retorna um código de erro (Status da apropriação não permite edição).
Cenário 6: Apropriação não encontrada
Pré-condições:
O sistema está funcionando corretamente. A apropriação do instrumento de cobrança especificada não existe. Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança" com um ID de apropriação inexistente. Validações:
Verificar se a requisição retorna um código de erro (Apropriação não encontrada).
Cenário 7: Requisição inválida devido à falta de campo obrigatório
Pré-condições:
O sistema está funcionando corretamente. A apropriação do instrumento de cobrança possui o status "Apropriação em Andamento". Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança" com campos obrigatórios em falta. Validações:
Verificar se a requisição retorna um código de erro (Campo {campo} é obrigatório) para cada campo obrigatório ausente.
Cenário 8: Dados anteriores excluídos e atualização correta
Pré-condições:
O sistema está funcionando corretamente. A apropriação do instrumento de cobrança possui o status "Apropriação em Andamento". Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança" e atualiza os dados da apropriação. Validações:
Verificar se a requisição é bem-sucedida. Verificar se a apropriação do instrumento de cobrança é atualizada corretamente com os novos dados. Verificar se os dados anteriores foram excluídos. Verificar se o status retornado é "SUCESSO". Verificar se a mensagem de retorno é apropriada.
Cenário 9: Erro interno do servidor
Pré-condições:
O sistema enfrenta um erro interno. Ação:
O usuário faz uma requisição para a API "Editar Apropriação de Instrumento de Cobrança" durante um erro interno do servidor. Validações:
Verificar se a requisição retorna um código de erro (Erro interno do servidor).
Cenário 10: Requisição repetida
Pré-condições:
O sistema está funcionando corretamente. A requisição é uma repetição da anterior. Ação:
O usuário faz uma nova requisição idêntica à anterior. Validações:
Verificar se a requisição é bem-sucedida. Verificar se a apropriação do instrumento de cobrança é atualizada corretamente com os novos dados. Verificar se os dados anteriores foram excluídos. Verificar se o status retornado é "SUCESSO". Verificar se o ID da apropriação de instrumento de cobrança é retornado novamente. Verificar se a mensagem de retorno é apropriada.
Cenário 11: Atualização da documentação da API no Swagger
Pré-condições:
O sistema está funcionando corretamente. Ação:
O responsável atualiza a documentação da API no Swagger do sistema conforme os requisitos. Validações:
Verificar se a documentação da API no Swagger foi atualizada corretamente e reflete os campos e requisitos especificados.