[API] - Criar 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 solicitaçã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 cadastro de informações para apropriação de um ou mais instrumento(s) de cobrança(s) e envio ao Sistema Integrado de Administração Financeira do Governo Federal (SIAFI) para geração do respectivo documento hábil (DH) em casos de sucesso ou resposto do eventual erro.
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), 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 os id_inst_cobranca enviados sejam vinculado ao mesmo contrato;
Perfil de acesso: Execução Financeira e Acesso API;
Deve validar se a despesa_antecipada for "True" e retorna mensagem "Erro - Sistema não está preparado para fazer apropriação com despesa antecipada";
Cada requisição enviada para os contratos deve validar a autenticação do usuário antes de utilizar a API.
Além disso, cada requisição enviada para os contratos deve verificar se a Unidade Gestora (UG) do contrato vinculado aos instrumento de cobrança pertence às unidades do usuário (sejam primárias ou secundárias).
Permitir a apropriação somente se todos os id_inst_cobranca estiverem exclusivamente na base de dados do CONTRATOS com status "Pendente" ou "Erro Siafi".
Caso a apropriação tenha AtencipaGov deverá enviar os dados registrado previamente no contrato da antecipação.
Retornar a "mensagem" do CONTRATOS somente se não houver mensagem do SIAFI.
Como responsável por realizar a 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 apropriação de instrumentos de cobrança,
Para que seja possível 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: Apropriar Instrumento de Cobrança
1.2. Método: POST
1.3. URI do recurso: /api/v1/contrato/instrumento_cobranca/apropriar
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 | inst_cobranca | Array | Sim | Bloco de informação que representam os ids dos instrumentos de cobranças |
2.1 | id_inst_cobranca | Integer | Sim | Id do instrumento de cobrança |
3 | tipo_dh | Boolean | Sim | Indicador do código do Tipo DH Padrão (NP, RP) |
4 | cod_ug_emitente | Integer | Sim | Código da Ug Emitente do DH |
5 | data_emissao_contabil | Date (8) | Sim | Data de emissão contábil (YYYY-MM-DD) |
6 | data_vencimento | Date (8) | Sim | Data de vencimento (YYYY-MM-DD) |
7 | taxa_cambio | Number (15,2) | Sim | Valor da taxa de câmbio ($float) |
8 | processo | String (255) | Sim | Número do processo (00000.000000/0000-00) |
9 | data_ateste | Date (8) | Sim | Data de ateste (YYYY-MM-DD) |
10 | observacao | String (468) | Não | Texto de observação |
11 | informacoes_adicionais | String (500) | Sim | Texto de informações adicionais |
12 | sf_pco | Array | Sim | Bloco de informação que representam as situações dos instrumentos de cobranças |
12.1 | cod_situacao | String (255) | Sim | Código da situação SIAFI (DSP000) |
12.2 | indicador_contrato | Boolean | Sim | Indicador se tem contrato (true, false) |
12.3 | despesa_antecipada | Boolean | Sim | Indicador se é despesa antecipada (true, false) |
12.4 | txtinscrd | String (500) | Não | campo variavel txt d |
12.5 | numclassd | String (500) | Não | campo variavel class d |
12.6 | txtinscre | String (500) | Não | campo variavel txt e |
12.7 | numclasse | String (500) | Não | campo variavel class e |
12.8 | sf_pco_item | Array | Sim | Bloco de informação que representam os empenhos dos instrumentos de cobranças por situação |
12.8.1 | numero_empenho | String (255) | Sim | Número do empenho |
12.8.2 | subelemento | Integer | Sim | Código do subelemento |
12.8.3 | indicador_liquidado | Boolean | Sim | Indicador se o empenho está liquidado (true, false) |
12.8.4 | valor_item | Number (15,2) | Sim | Valor do item ($float) |
12.8.5 | txtinscra | String (500) | Não | campo variavel txt a |
12.8.6 | numclassa | String (500) | Não | campo variavel class a |
12.8.7 | txtinscrb | String (500) | Não | campo variavel txt b |
12.8.8 | numclassb | String (500) | Não | campo variavel class b |
12.8.9 | txtinscrc | String (500) | Não | campo variavel txt c |
12.8.10 | numclassc | String (500) | Não | campo variavel class c |
13 | data_pagamento | Date (8) | Sim | Data de pagamento (YYYY-MM-DD) |
14 | sf_centro_custo | Array | Não | Bloco de informação que representam os centros de custo dos instrumentos de cobranças |
14.1 | cod_centro_custo | String (255) | Não | Número sequencial do centro de custo |
14.2 | mes | Integer | Não | Mês de referência |
14.3 | ano | Integer | Não | Ano de referência |
14.4 | codigo_siorg | Integer | Não | Código do SIORG |
14.5 | ug_beneficiada | Integer | Não | Código da Ug do Empenho |
14.6 | item_vlrcc | Objeto | Sim | Bloco de informação que representam as situações do centro de custo dos instrumentos de cobranças |
14.6.1 | cod_situacao | String (255) | Sim | Código da situação SIAFI (DSP000) |
14.6.2 | Numero_empenho | String (255) | Sim | Número do empenho |
14.6.3 | valor_item | Number (15,2) | Sim | Valor do item ($float) |
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.5 | numero_dh | Integer | Sim | Número do DH criado no SIAFI |
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 inclusão. | Erro | Operação não concluída, status da apropriação não permiti inclusão |
Campo {campo} é obrigatório. | Erro | Requisição não atende aos requisitos do contrato da API devido à falta de campo |
Instrumentos de cobrança não estão vinculado ao mesmo contrato | 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 |
Instrumento de cobrança não encontrado | Erro | Instrumento de cobrança especificada não foi encontrado |
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. tipo_dh (Indicador do código do tipo DH padrão)
- (código = NP) Nota de Pagamento: Utilizado na API do item 1.1.1.
- (código = RP) Recibo de Pagamento: Utilizado na API do item 1.1.1.
2. 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.
3. 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.
4. 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 com sucesso
Pré-condições:
O sistema está funcionando corretamente. O usuário possui autorização para a ação no contrato. Os instrumentos de cobrança estão vinculados ao mesmo contrato. Ação:
O usuário faz uma requisição válida para a API "Apropriar Instrumento de Cobrança". Validações:
Verificar se a requisição é bem-sucedida (código HTTP 200). Verificar se o ID da apropriação de instrumento de cobrança é retornado. Verificar se o status retornado é "SUCESSO". Verificar se a mensagem de retorno é apropriada. Verificar se a situação da apropriação no Contratos é atualizada corretamente.
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 "Apropriar Instrumento de Cobrança" com um token expirado. Validações:
Verificar se a requisição retorna um código de erro 401 (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 "Apropriar Instrumento de Cobrança" com o mesmo código Nonce. Validações:
Verificar se a requisição retorna um código de erro 400 (Código Nonce em outra requisição).
Cenário 4: Falta de permissão no contrato para apropriaçã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 "Apropriar Instrumento de Cobrança". Validações:
Verificar se a requisição retorna um código de erro 400 (Usuário sem permissão no contrato para apropriação).
Cenário 5: Falta de permissão no sistema
Pré-condições:
O sistema está funcionando corretamente. O usuário não possui permissão para utilizar a API. Ação:
O usuário faz uma requisição para a API "Apropriar Instrumento de Cobrança". Validações:
Verificar se a requisição retorna um código de erro 400 (Usuário sem permissão no sistema).
Cenário 6: Status da apropriação não permite inclusão
Pré-condições:
O sistema está funcionando corretamente. O status da apropriação não permite a inclusão. Ação:
O usuário faz uma requisição para a API "Apropriar Instrumento de Cobrança". Validações:
Verificar se a requisição retorna um código de erro 409 (Status da apropriação não permite inclusão).
Cenário 7: Apropriação não encontrada
Pré-condições:
O sistema está funcionando corretamente. A apropriação especificada não existe. Ação:
O usuário faz uma requisição para a API "Apropriar Instrumento de Cobrança" com um ID de apropriação inexistente. Validações:
Verificar se a requisição retorna um código de erro 404 (Apropriação não encontrada).
Cenário 8: Requisição inválida devido à falta de campo obrigatório
Pré-condições:
O sistema está funcionando corretamente. Ação:
O usuário faz uma requisição para a API "Apropriar Instrumento de Cobrança" com campos obrigatórios em falta. Validações:
Verificar se a requisição retorna um código de erro 422 (Campo {campo} é obrigatório) para cada campo obrigatório ausente.
Cenário 9: Instrumentos de cobrança não estão vinculados ao mesmo contrato
Pré-condições:
O sistema está funcionando corretamente. Os instrumentos de cobrança não estão vinculados ao mesmo contrato. Ação:
O usuário faz uma requisição para a API "Apropriar Instrumento de Cobrança" com instrumentos de cobrança vinculados a contratos diferentes. Validações:
Verificar se a requisição retorna um código de erro 422 (Instrumentos de cobrança não estão vinculados ao mesmo contrato).
Cenário 10: 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 "Apropriar Instrumento de Cobrança" durante um erro interno do servidor. Validações:
Verificar se a requisição retorna um código de erro 500 (Erro interno do servidor).
Cenário 11: 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 (código HTTP 200). Verificar se o ID da apropriação de instrumento de cobrança é retornado novamente. Verificar se o status retornado é "SUCESSO".