# Documentação API: integração App e-Bolsa

## :gear: API

### BaseAddress
>
> :globe_with_meridians: API Dev: https://api-ebolsa-dev.educadventista.org
> :globe_with_meridians: API Live: https://api-ebolsa.educadventista.org

### Documentation
> :green_book: Swagger: /api/doc

---

## Endpoints

### :closed_lock_with_key: Autenticação

1. Chamada Post obter o token
- >[post]=[/api/v2/identity/token]
- Exemplo de body:

    {
      "username": "string",
      "password": "string",
      "baseUri": "string"
    }

- Passar no parâmetro baseUri do body a URL: https://ebolsa.educadventista.org
- O userId, Name and SurName estao dentro do token
- A imagem do usuario pode ser uma imagem estática padrao por enquanto
- Exemplo de retorno

    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImQwYWFmYmQyLTU5ZGItNDhmNC1iYTUzLTZlYmRlOTRlMWU3NSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6ImplZmZlcnNvbi5wYXNzb3NAdWNiLm9yZy5iciIsImVtYWlsY29uZmlybWVkIjoiVHJ1ZSIsImZ1bGxOYW1lIjoiSmVmZmVyc29uIEJyaXRvIFBhc3NvcyBkb3MgU2FudG9zIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvbmFtZSI6IkplZmZlcnNvbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3N1cm5hbWUiOiJTYW50b3MiLCJpcEFkZHJlc3MiOiIiLCJpbWFnZV91cmwiOiIiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9kbnMiOiJlYm9sc2EuZWR1Y2FkdmVudGlzdGEub3JnIiwibmJmIjoiMTY1Njk2NTI1MyIsImV4cCI6MTY1NzEzODA1MywiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjpbIk93bmVyIiwiU3VwZXIgQWRtaW4iXX0.s6lZf9puMLafDLgB-YmprujUJcuwJdzr2fxrdOIPmyo",
      "refreshToken": "Mru5TkvdXv+jfyHKTxCi2vSsQkxdtkKQ2rCbZaEnIwI=",
      "refreshTokenExpiryTime": "2022-07-11T20:07:33.7137747Z"
    }

2. Forgot Password

- Endpoint para receber um e-mail para redefinição de senha
- - > [post]=[/api/v2/identity/account/forgot-password]

    {
      "userName": "string",
      "origin": "string"
    }

- Passar no parâmetro origin do body a URL: https://ebolsa.educadventista.org
- Irá retornar o e-mail para o qual o link de redefinição foi enviado de forma obsfucada

    {
        "email": "je*************[e-mail]"
    }

### :house: Home

1. Chamada Get para obter a lista de anos
- >[get]=[/api/v2/scholarships/process-periods/year-processes/years]
- Ira retornar apenas os anos em que o responsavel autenticado possui registro de bolsa.

2. Chamada Get para obter a lista de ProcessPeriod para o ano especificado no parametro.
- >[get]=[/api/v2/year-processes/{year}/process-periods]
- Para identificar se o processo é de renovação ou de novos, usa-se o campo *processType* que representa o enum com os seguintes valores: Renew = 1, New = 2

3. Chamada Get para obter o Scholarship passando o ProcessPeriodId como parametro.
- >[get]=[/api/v2/process-periods/{process-period-id}/scholarship]
- exibir o status do processo com base no campo enum "ScholarshipStatus" que representa os seguintes valores [NotFinished = 0, Applied = 1,Documentation = 2,Reviewed = 3,Analysis = 4,Result = 5].

* 0: A inscrição ainda está em andamento (não finalizada)
* 1: Incrição finalizada (formulário)
- Exibir botão para envio de documentação
* 2: Documentação enviada (no digital) ou entregue (no presencial)
- Exibir botão caso existam pendências ou documentos complementares
* 3: Revisão finalizada sem pendências
- Exibir botão caso existam pendências ou documentos complementares
* 4: Analise socioeconômica finalizada
* 5: Resultado liberado (para um, ou todos os candidatos)

4. Com base no objeto scholarship, caso (DigitalProcess = 1 and CompletedStep = 5), exibir o botao "Iniciar envio".
- Existe uma data limite para envio da documentação. O botão deve ser exibido apenas se estiver dentro do prazo. A data limite será retornada no objeto ProcessPeriod e campo "documentationUploadDeadLine".

5. Com base no registro mais recente (usando o campo createdAt) de ScholarshipReview (objeto filho de Scholarship), caso o campo ReviewStatus = 1, exibir o botao "Reenviar documentos".
- O campo ReviewStatus é do tipo enum com os seguintes valores: ReviewStarted = 0, Pendent = 1, Resent = 2, Done = 3, None = 4, NotFinished = 5.

6. O texto com o protocolo precisaremos retirar da tela inicial, pois o protocolo é por candidato. Para exibir de forma correta, precisariamos exibir a lista de candidatos que compoe aquele scholarship e exibir lá um protocolo para cada candidato.

---

### :bell: Push Notification

* O endpoint utiliza o verbo http Path (mais detalhes em: JSON Patch | jsonpatch.com);
* O nome do campo onde gravaremos o token será: **FcmRegistrationToken**;
* O userId pode ser recuperado no payload do Token, no claim **nameidentifier**;
* Após o request, o endpoint retornará o status code de sucesso **204 No Content**;

**Endpoint:**
- >[PATCH]=[/api/v2/users/{userId}]
- Exemplo de body:

    {
      "op": "replace",
      "path": "/fcmregistrationtoken",
      "value": "4116-b086-7ba912dabd5"
    }
---

### :newspaper: Listar Comprovantes

#### Ao acionar o botão "Iniciar envio", deve-se ir para tela para iniciar o envio da documentação.

1. Obter a lista de membros familiares passando o ScholarshipId.
    - >[Get]=[/api/v2/scholarships/{scholarshipId}/family-members]

2. Chamada Get para obter a lista de comprovantes passando o ScholarshipId como parâmetro.
    - >[Get]=[/api/v2/scholarships/{scholarshipId}/scholarship-proofs]
    - Os parâmetros *familyMemberId*, *isFamilyGroup* e *proofReference* podem ser usados para filtrar e obter os documentos específicos de um membro familiar, ou por tipo a que o documento se refere. 
    - O campo *proofReference* é do tipo enum com os seguintes valores (FamilyGroup = 0, FamilyMember = 1, Student = 2, Ocupation = 3, AssetsPropriety = 4, AssetsFinancing = 5, AssetsVehicle = 6)
    - Para se obter a lista de comprovantes de um membro específico, passa-se o id do membro familiar.
    - Para se obter a lista de comprovantes que são referente a grupo familiar (documentos que não são referentes a uma pessoa), informa-se no parâmetro *isFamilyGroup* o valor de "true".

3. Chamada Get para obter a lista de itens do comprovante, passando o scholarshipProofId como parâmetro.

    - > [Get]=[/api/v2/scholarship-proofs/{scholarshipProofId}/scholarship-proof-documents]
---

### :paperclip: Upload

1. Listar tipos de documentos aceitos pelo comprovante
    - > ~~[Get]=[[/api/v2/document-entity-proofs/{entityProofId}]~~
    
    - > ~~[Get]=[/api/v2/entity-proof-itens/{entityProofItemId}/document-entity-proofs]~~

    - > [Get]=[/api/v2/proof-item-configs/{proofItemConfigId}/proof-document-configs]
    - Caso o usuário selecione da lista um item que seja do tipo declaração, ou seja, o campo document.isDeclaration == true, deve se exibir o termo de aceite da teclaração e enviar o aceite no request ao fazer o **PUT** para upload do documento.
    
2. Envio de documento

    - > [Put]=[api/v2/scholarship-proof-documents/{scholarshipProofDocumentId}/upload]
    - Enviar usando multipart/form-data
    ![](https://i.imgur.com/GmKQk8v.png)

3. Substituição de documento

    - Para substituir um documento, a mesma chamada POST deve ser enviada com os mesmos parâmetros, pois a exclusão/inserção do novo documento será feita de forma automática pela API.

4. Get de um documento enviado
 
    - Após o upload, o objeto ScholarshipProofDocument terá o fileId populado, sendo possível recuperar os dados do arquivo através do endpoint abaixo:
    - > [Get]=[/api/v2/files/{id}]
    - Exemplo de retorno:

{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"purpose": 1,
"fileKey": "string",
"cloudType": 1,
"contentType": "string",
"createdAt": "2022-07-13T13:48:12.123Z",
"filename": "string",
"size": 0,
"title": "string",
"url": "string"
}

5. Finalizar envio
    
    - Para finalizar o envio dos documentos, o seguinte endpoint deve ser chamado passando o scholarshipId na rota, conforme exemplo abaixo:
    - > [Put]=[/api/v2/scholarship/{scholarshipId}/step-six]

### :heavy_exclamation_mark: Reenvio de Documento (re-upload das pendências pós revisão)

1. Listar apenas membros familiares com pendencias de documentação com base na última  revisão.
    - > [Get]=[/api/v2/scholarships/{scholarshipId}/family-members?hasPendences=true]

2. Listar ultima revisão

    - Endpoint para listar sempre a revisão mais recente
    - > [Get]=[/api/v2/scholarships/{scholarshipId}/scholarship-reviews/latest]

2. Listar comprovantes pendentes de uma revisão

    - > [Get]=[/api/v2/scholarship-reviews/{scholarshipReviewId}/scholarship-proofs]
    - Os parâmetros *familyMemberId*, *isFamilyGroup* e *proofReference* podem ser usados para filtrar e obter os documentos específicos de um membro familiar, ou por tipo a que o documento se refere. 
    - O campo *proofReference* é do tipo enum com os seguintes valores (FamilyGroup = 0, FamilyMember = 1, Student = 2, Ocupation = 3, AssetsPropriety = 4, AssetsFinancing = 5, AssetsVehicle = 6)
    - Para se obter a lista de comprovantes de um membro específico, passa-se o id do membro familiar.
    - Para se obter a lista de comprovantes que são referente a grupo familiar (documentos que não são referentes a uma pessoa), informa-se no parâmetro *isFamilyGroup* o valor de "true".

3. Enviar documento de uma revisão
    - O reenvio do documento pendente após uma revisão ter sido feita, deve ser feito por outro endpoint para upload, com o parâmetro adiconal da revisão correspondente.
    - > [Put]=[/api/v2/scholarship-reviews/{scholarshipReviewId}/scholarship-proof-documents/{scholarshipProofDocumentId}/upload]
    - Exemplo de body:

{
"File": Srting($binary)
"ScholarshipProofDocumentId": "6bbd0975-220d-4ae5-a8b9-224ae586c084",
"DocumentId": "ba779fd8-c2ed-4f98-ada7-60aa2751e48c",
"AcceptTerm": false,
"scholarshipReviewId": "24764fcb-9792-4b5d-88ca-c74d194a416c"
}

4. Finalizar envio
    
    - Para finalizar o envio dos documentos, o seguinte endpoint deve ser chamado passando o scholarshipRevewId na rota, conforme exemplo abaixo:
    - > [Put]=[/api/v2/scholarship-reviews/{scholarshipReviewId}]
    - Exemplo de body:

{
"ScholarshipId": "6bbd0975-220d-4ae5-a8b9-224ae586c084",
"scholarshipReviewId": "24764fcb-9792-4b5d-88ca-c74d194a416c"
}

    
### :page_with_curl: Resultados
1. Com base na data de divulgação dos resultados obtidos no parâmetro **resultRelease** do endpoint **process-periods** exibir o botão **Resultados**
2. Para obter a lista de alunos usa-se o endpoint abaixo passando o scholarshipId como parâmetro do tipo **path** 
    - > [Get]=[/api/v2/scholarships/{scholarshipId}/students]

3. As labels com o resultado e seus respectivos textos são:

    - <span style="background-color:green; color: white; padding-left: 10px; padding-right: 10px; border-radius: 25px">**Deferido 100%**</span>
        - Informamos que com base na análise do perfil socioeconômico e demais critérios estabelecidos pela entidade, a solicitação de Bolsa de Estudo para o ano letivo de {**ano_do_processo**} foi deferida com percentual de 100%.  
          
          Em consonância com o Edital, para receber o benefício supra, o responsável legal, deverá comparecer a secretaria escolar, munido de todos os documentos necessários para efetivar a matrícula do bolsista, consonante aos prazos previstos no cronograma descrito no Edital. **A não efetivação da matrícula do estudante, pelo responsável legal, cancela o processo de recebimento do benefício** da bolsa de estudo. 
          
          Em caso de dúvida, entre em contato com a unidade escolar.


   - <span style="background-color:green; color: white; padding-left: 10px; padding-right: 10px; border-radius: 25px">**Deferido 50%**</span>
        - Informamos que com base na análise do perfil socioeconômico e demais critérios estabelecidos pela entidade, a solicitação de Bolsa de Estudo para o ano letivo de {ano_do_processo} foi deferida com percentual de 50%.  
          
          Em consonância com o Edital, para receber o benefício supra, o responsável legal, deverá comparecer a secretaria escolar, munido de todos os documentos necessários para efetivar a matrícula do bolsista, consonante aos prazos previstos no cronograma descrito no Edital. **A não efetivação da matrícula do estudante, pelo responsável legal, cancela o processo de recebimento do benefício** da bolsa de estudo.  
            
          Em caso de dúvida, entre em contato com a unidade escolar.  
    
   - <span style="background-color:red; color: white; padding-left: 10px; padding-right: 10px; border-radius: 25px">**Indeferido**</span>
        - Informamos que com base na análise do perfil socioeconômico e demais critérios estabelecidos pela entidade, a solicitação de Bolsa de Estudo para o ano letivo de {**ano_do_processo**} foi indeferida [motivo_do_indeferimento]. Em caso de dúvida, entre em contato com a unidade escolar.
            
          Em caso de dúvida, entre em contato com a unidade escolar.