feat(payment-account): update doc and organize README.md (#388)

* feat(payment-account): update doc and organize README.md * chore(review): apply suggestions * chore(Readme): reorder content * chore(apply): review suggestions * fix(readme): change sections order * chore(review): apply changes
stone-co · Mar 8, 2023 · 1d23a87 · 1d23a87
1 parent 6fa891b
commit 1d23a87
Show file tree

Hide file tree

Showing 2 changed files with 158 additions and 60 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-# Documentação da API de OpenBank da Conta Stone
+
+# Documentação da API de OpenBank da Conta Stone | Stone Co.
+---
 
 O [site](https://stone-co.github.io/) com a documentação da nossa API de OpenBank usa
 [Hugo](https://gohugo.io/), um framework _open-source_ escrito em [Golang](https://go.dev/) para construção de sites
@@ -8,7 +10,18 @@ O seu funcionamento é simples: a usuária escolhe um [tema](https://themes.gohu
 formato **markdown**, edita um arquivo de configuração `.toml` para promover customizações e voilà - 🐭🪄 a mágica
 gopher acontece!
 
-## Visão geral do projeto
+Tabela de Conteúdo
+=================
+
+- [Visão Geral](#visão-geral)
+- [Contribua](#contribua)
+- [Guia GIT](#guia-git)
+- [Deploy](#deploy)
+- [Uso](#uso)
+- [Instalação](#instalação)
+- [Visão do Repositório](#visão-do-repositório)
+
+## Visão Geral
 
 ### Repositórios relacionados
 
@@ -28,7 +41,7 @@ três repositórios relacionados ao projeto:
 3. _Site Produção_: o código-fonte do site, que é gerado pelo código deste repositório + hugo a cada nova tag de
    release, pode ser encontrado [aqui](https://github.com/stone-co/stone-co.github.io).
 
-### Contribuindo
+## Contribua
 
 #### Nomeando arquivos e diretórios
 
@@ -70,7 +83,7 @@ Se nenhuma providência for tomada, as seções e posts vão se organizar em ord
 intencional, é necessário preencher o campo `weight` do cabeçalho. O primeiro conteúdo que deve aparecer deve
 ter `weight` igual a 1, o segundo igual a 2, e assim por diante.
 
-#### Fluxo de Git
+## Guia GIT
 
 Mensagens de commit, nomes de branches e títulos de Pull Requests devem seguir os padrões informados no
 [Guia de Estilo Git da Stone](https://github.com/stone-payments/stoneco-best-practices/blob/master/gitStyleGuide/README_pt.md#commits).
@@ -79,7 +92,7 @@ Para facilitar a colaboração, o fluxo de Git abaixo deve ser seguido:
 
 ![Flow](docs/images/diagrama_git_flow.png)
 
-### Deploy
+## Deploy
 
 A documentação é disponibilizada em dois ambientes: **Sandbox** e **Produção**. A atualização
 desses ambientes ocorre por meio de duas GitHub Actions, uma para cada ambiente. Essas ações rodam o
@@ -97,10 +110,44 @@ a flag `-D` para forçar os artigos que têm `draft: true` no cabeçalho a serem
 Temos a [Action](https://github.com/stone-co/stone-api-docs/blob/master/.github/workflows/release.yml)
 que desencadeia uma nova construção do site sempre que geramos uma tag de release neste repositório.
 
-## Usando Hugo
+## Uso
+
+Como o projeto necessita de git submodules para o seu funcionamento, você deve os iniciar da seguinte forma:
+
+- Caso ainda não tenha clonado o projeto:
+
+  ```shell
+  $ git clone --recurse-submodules https://github.com/stone-co/stone-api-docs.git
+  ```
+
+- Caso já tenha clonado:
+  ```shell
+  $ git submodule update --init --recursive
+  ```
+
+⚠️ É importante rodar localmente antes de submeter as suas contribuições para o repositório remoto para poder visualizar o
+site e verificar se não há erros na sua construção.
+
+- Digitar no terminal o seguinte comando:
+
+  ```shell
+  $ hugo server
+  ```
+
+  🔍 Obs: se você quiser forçar os _drafts_ a serem publicados, utilize a _flag_ `-D`
 
-### Instalando
+- No seu navegador, visitar o endereço **localhost:1313** (ou o endereço que for informado no próprio terminal após
+  rodar o comando acima)
+
+- Para parar, apertar `Ctrl + C` no terminal
 
+---
+
+Para mais informações sobre Hugo: [getting started do Hugo](https://gohugo.io/getting-started/quick-start/) e
+[oficina de sites estáticos com hugo](https://github.com/womenwhogocwb/oficina-hugo).
+
+
+## Instalação
 #### Windows
 
 Baixe o executável do
@@ -133,7 +180,7 @@ Comando para instalar com Homebrew: `$ brew install hugo`
 Use o _package manager_ da sua distro/de sua preferência, instruções adicionais
 [aqui](https://gohugo.io/getting-started/installing/#linux)
 
-### Adicionando conteúdo com Hugo instalado
+## Visão do Repositório
 
 - Para criar um novo conteúdo (na prática, vai ser criado um arquivo **markdown** que vai ser usado para gerar uma nova
   página **html**), deve-se digitar o seguinte comando:
@@ -156,38 +203,4 @@ Use o _package manager_ da sua distro/de sua preferência, instruções adiciona
   deve ser publicado no ambiente de Produção.
   🚨 Mesmo que o campo `draft` tenha o valor `true`, **o artigo será publicado no ambiente de Sandbox!**
 
-### Rodando localmente
-
-Como o projeto necessita de git submodules para o seu funcionamento, você deve os iniciar da seguinte forma:
-
-- Caso ainda não tenha clonado o projeto:
-
-  ```shell
-  $ git clone --recurse-submodules https://github.com/stone-co/stone-api-docs.git
-  ```
-
-- Caso já tenha clonado:
-  ```shell
-  $ git submodule update --init --recursive
-  ```
-
-⚠️ É importante rodar localmente antes de submeter as suas contribuições para o repositório remoto para poder visualizar o
-site e verificar se não há erros na sua construção.
 
-- Digitar no terminal o seguinte comando:
-
-  ```shell
-  $ hugo server
-  ```
-
-  🔍 Obs: se você quiser forçar os _drafts_ a serem publicados, utilize a _flag_ `-D`
-
-- No seu navegador, visitar o endereço **localhost:1313** (ou o endereço que for informado no próprio terminal após
-  rodar o comando acima)
-
-- Para parar, apertar `Ctrl + C` no terminal
-
----
-
-Para mais informações sobre Hugo: [getting started do Hugo](https://gohugo.io/getting-started/quick-start/) e
-[oficina de sites estáticos com hugo](https://github.com/womenwhogocwb/oficina-hugo).
diff --git a/...da-api/dados-da-conta/consultar-dados-do-pedido-da-conta-de-pagamento/_index.md b/...da-api/dados-da-conta/consultar-dados-do-pedido-da-conta-de-pagamento/_index.md
@@ -16,9 +16,9 @@ Provê um conjunto de informações para acompanhar o pedido de cadastro da cont
 
 ---
 
-```
-GET https://sandbox-api.openbank.stone.com.br/api/v1/applications/:client_id/signups/:sign_up_request_id
-```
+
+> GET https://sandbox-api.openbank.stone.com.br/api/v1/applications/:client_id/signups/:sign_up_request_id
+
 
 <br>
 
@@ -46,6 +46,11 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 
 ##### **PATH PARAMETER**
 ---
+ID do cliente é o id da sua aplicação para mais informações veja a documentação de [token de acesso](https://docs.openbank.stone.com.br/docs/guias/token-de-acesso/).
+
+
+O sign up request é o id gerado apartir de um pedido feito via `/singups` para mais informações veja [singup](http://localhost:1313/docs/referencia-da-api/dados-da-conta/criar-nova-conta-de-pagamento/).
+
 
 
 **client_id*** `string`
@@ -61,6 +66,15 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 
 <br>
 
+
+## Glossário 
+
+- Verificações Automáticas (automatic_checks_assessment): Fazemos verificações automáticas do cadastro de usuário como exemplos, verificar situação cadastral, idade legal, sociedade entre outros.
+
+- KYC Know Your Costumer (user_input_assessment): Validadmos a identidade do usuário após envio de informações como selfie, foto do documato entre outras.
+
+- CHECKS:  Cada informação que pedimos dentro do KYC.
+
 ##### **Responses**
 ---
 
@@ -71,22 +85,51 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 {{% pageinfo %}}
 **A resposta contém os seguintes dados:**
 
- - id: identificador do pedido de sign up
- - owner_id: identificador do usuário ou organização dona da conta de pagamento
- - owner_type: tipo do dono da conta de pagamento (user ou organization)
- - user_id: id do usuário atrelado a conta de pagamento
+ - id: identificador do pedido de sign up.
+ - account_status: status da conta de pagamento.
+    + **created**: conta foi criada.
+    + **closed**: conta foi encerrada.
+    + **pending_analysis**: pendente de aprovação de KYC.
+    + **empty**: Status legado de quando a conta não foi aberta automaticamente.
+ - owner_id: identificador do usuário ou organização dona da conta de pagamento.
+ - owner_type: tipo do dono da conta de pagamento (user ou organization).
+ - user_id: id do usuário atrelado a conta de pagamento.
  - organization_id: id da organização atrelada a conta de pagamento (pode ser nulo caso seja uma conta apenas de PF).
  - user_email_verified: indica se o usuário está com o e-mail verificado.
- - user_assessment_request_status: status do assessment request para criação do usuário.
- - organization_assessment_request_status: status do assessment request para criação da organização (pode ser nulo caso seja uma conta apenas de PF).
+ - user_assessment_request_status: status resultante da combinação entre os status dos assessments gerados para o usuário nesse pedido.
+ - user_input_assessment_status: 
+    + **answered**: quando o cliente respondeu KYC e está pendente de análise.
+    + **approved**: KYC aprovado.
+    + **canceled**: quando o KYC foi cancelado pela operação.
+    + **partially_rejected**: Quando pelo menos um dos checks foi aprovado e pelo menos um foi rejeitado.
+    + **rejected**:  quando o cadastro for rejeitado por completo.
+    + **requested**: quando o KYC ainda não foi respondido. 
+    + **undone**: quando a análise do KYC foi desfeita.
+ - user_automatic_checks_status: status agrupado das validações automáticas.
+    + **approved**: aprovado em todas as validações automáticas.
+    + **rejected**: rejeitado o pedido de abertura de conta.
+    + **partially_rejected**: Quando foi rejeitado em uma ou mais validações automáticas.
+    + **rerunned**: quando reprocessamos as validações.
+    + **answered**: status intermediário enquanto as avaliações não foram finalizadas.
+    + **canceled**: quando foi cancelado pela operação de analise de KYC.
+    + **requested**: quando as validações não foram finalizadas ainda.
+ - organization_assessment_request_status: status resultante da combinação entre os status dos assessments gerados para a organização nesse pedido (pode ser nulo caso seja uma conta apenas de PF).
  - subject_id: id da aplicação que criou esse pedido de sign up.
- - status: em qual status está o pedido de sign up created, kyc_analysis(em análise de kyc), finished, failed
+ - status: em qual status está o pedido de sign up: 
+     + **created** - pedido criado.
+     + **kyc_analysis** - pedido em análise de kyc.
+     + **finished** - todas as etapas do pedido finalizadas.
+     + **failed** -  pedido falhou no momento da criação.
  - error: apenas presente caso o status seja failed, contém informações do motivo de falha ao fazer o sign up.
  - metadata: metadados customizados passados ao realizar o cadastro.
  - request_metadata: metadados da requisição de cadastro. Ex: user-agent, ip.
  - resource_details: detalhes envolvendos esse cadastro. Ex: usuário verificou o e-mail, horário que o usuário verificou e-mail, assessment de usuário aprovado, conta de pagamento aberta/fechada/inexistente.
- - resource_type: tipo de recurso principal criado (usuário, organização, conta de pagamento).
- - user: alguns campos do usuário, atualmente só carregamos o id e o approval_status (limited|approved|partially_rejected|pending_analysis).
+ - resource_type: tipo de recurso principal criado.
+    + **usuário**: criou uma entidade de usuário (srn:resource:user).
+    + **organização**: criou uma entidade de Organização (srn:resource:organization).
+    + **conta de pagamento PF**: cria uma entidade usuário com um pedido de conta de pagamento (srn:resource:paymentaccount).
+    + **conta de pagamento PJ**: cria uma entidade usuário e organização com pedido de conta de pagamento (srn:resource:paymentaccount).
+ - user: alguns campos do usuário, atualmente só carregamos o id e o approval_status (limitedapprovedpartially_rejectedpending_analysis).
  - organization: alguns campos da organização, atualmente só carregamos o id e o approval_status.
  - inserted_at: timestamp da criação do pedido de conta de pagamento.
  - updated_at: timestamp da última atualização do pedido de conta de pagamento.
@@ -108,12 +151,24 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 
  - **owner_type** `string`
 
+ - **owner_document** `string`
+
  - **user_id** `string` 
 
+ - **user_assessment_request_id** `string`
+
  - **organization_id** `string`
 
+ - **organization_assessment_request_id** `string`
+
+ - **request_id** `string`
+
  - **subject_id** `string`
 
+ - **detailed_status** `string`
+
+ - **detailed_status_description** `string`
+
  - **status** `string`
 
  - **error** `string` 
@@ -126,7 +181,7 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 
  - **update_at** `string` 
 
-**resource_details** `object`
+ - **resource_details** `object`
 
  - **account_status** `boolean` or `string`
 
@@ -160,6 +215,7 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 
 **resource_type** `string`
 
+
 <br>
 
 ##### Example
@@ -178,6 +234,7 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
     "utm_term": null
   },
   "metadata": {},
+  "owner_document": null,
   "organization_id": "3bf2ac6f-2219-4027-8516-d9457f7e6a96",
   "owner_id": "organization:3bf2ac6f-2219-4027-8516-d9457f7e6a96",
   "owner_type": "organization",
@@ -207,9 +264,12 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
   },
   "resource_type": "srn:resource:paymentaccount",
   "status": "kyc_analysis",
+  "detailed_status": "status_111",
+  "detailed_status_description": "Conta ainda não foi aberta pois falta o cliente responder informações de cadastro no app",
   "subject_id": "user:790081f7-92ce-428f-8334-6443ecc3cbb2",
   "updated_at": "2020-08-11T12:39:56.568580",
   "user_id": "1f4b4f98-f2a2-4ae6-9d4d-2a8dbe5473e1",
+  "user_assessment_request_id": "daa74a8b-701d-405e-b8c4-9976286eeda9"
   "user": {
     "approval_status": "approved",
     "id": "2d2e6aba-ce11-49be-88c0-0641843cabdc"
@@ -218,8 +278,33 @@ A autenticação pública deve passar pelo nosso IAM Keycloak através do protoc
 ```
 
 
-
-
-
-
-
+#### Possiveis detailed status description
+
+1. Conta não foi aberta para livre movimentação pois o cadastro do cliente foi rejeitado
+2. Conta ainda não foi aberta pois está em análise pelo time da conta
+3. Estado inconsistente
+4. Conta ainda não foi liberada para livre movimentação pois falta o cliente responder informações de cadastro no app e confirmar e-mail
+5. Conta não foi aberta pois o cadastro do cliente foi rejeitado
+6. Conta ainda não foi liberada para livre movimentação pois falta o cliente verificar o e-mail
+7. Conta ainda não foi liberada pois está em análise pelo time da conta
+8. Conta encerrada pois o cadastro do cliente foi rejeitado.
+9. Conta ainda não foi liberada para livre movimentação pois está pendente análise do time da Conta
+10. Conta ainda não foi aberta pois falta o cliente verificar o e-mail
+11. Conta não foi liberada para livre movimentação, entrar em contato com o time da Conta
+12. Conta não foi liberada para livre movimentação pois o cadastro do cliente foi rejeitado
+13. Conta ainda não foi liberada para livre movimentação pois falta o cliente responder informações adicionais de cadastro no app
+14. Estado inconsistente
+15. Conta ainda não foi liberada para livre movimentação pois falta o cliente responder informações adicionais de cadastro no app e confirmar e-mail
+16. Conta aprovada para livre movimentação
+17. Conta ainda não foi liberada para livre movimentação pois falta o cliente confirmar e-mail
+18. Conta ainda não foi liberada para livre movimentação pois falta o cliente responder novamente informações no app
+19. Conta encerrada pois o cadastro do cliente foi rejeitado
+20. Conta ainda não foi aberta pois falta o cliente responder informações de cadastro no app e confirmar e-mail
+21. Conta ainda não foi liberada para livre movimentação pois falta o cliente responder informações de cadastro no app
+22. Conta ainda não foi aberta para livre movimentação pois falta o cliente verificar o e-mail
+23. Conta pendente análise pois falta cliente confirmar e-mail
+24. Conta ainda não foi aberta pois falta o cliente responder informações de cadastro no app
+25. Conta em análise pelo time da conta
+
+> detailed_status é formado por status_número
+> ex: `status_1`, `status_111` ...  `status_7559`