feat(splits): unify splits docs and create new docs

Open-Pix · Jan 17, 2024 · f28d603 · f28d603
1 parent 19528a0
commit f28d603
Show file tree

Hide file tree

Showing 19 changed files with 257 additions and 90 deletions.
diff --git a/docs/charge/how-to-create-charge-with-split-using-api.mdx b/docs/charge/how-to-create-charge-with-split-using-api.mdx
@@ -10,9 +10,11 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 :::info
-Para a ultilização dessa funcionalidade é necessário possuir a funcionalidade Split
+Para a utilização dessa funcionalidade é necessário possuir a funcionalidade Split
 :::
 
+## Criar Split via API
+
 Para criar uma cobrança Pix com split, você utiliza o _endpoint_ `/api/v1/charge` da API.
 
 Você pode acessar [aqui](https://developers.openpix.com.br/api#tag/charge/paths/~1api~1v1~1charge/post)
@@ -24,7 +26,7 @@ Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes
 - **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
 - **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento
 
-## Exemplo
+### Exemplo
 
 O body da sua requisição será semelhante a este exemplo:
 

diff --git a/docs/charge/how-to-create-charge-woovi-parcelado.mdx b/docs/charge/how-to-create-charge-woovi-parcelado.mdx
@@ -10,7 +10,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 :::info
-Para a ultilização dessa funcionalidade é necessário possuir a funcionalidade OpenPix Parcelado. Solicite o acesso via chat pela plataforma pelo <a href="https://app.woovi.com/home/charges/pix-credit-card" target="_blank">link</a>
+Para a utilização dessa funcionalidade é necessário possuir a funcionalidade OpenPix Parcelado. Solicite o acesso via chat pela plataforma pelo <a href="https://app.woovi.com/home/charges/pix-credit-card" target="_blank">link</a>
 :::
 
 Para criar uma cobrança Pix com OpenPix Parcelado, você utiliza o _endpoint_ `/api/v1/charge` da API.

diff --git a/docs/concepts/charge.md b/docs/concepts/charge.md
@@ -20,4 +20,6 @@ Uma Cobrança aceita somente 1 pagamento.
 
 Uma Cobrança possui um prazo de vencimento.
 
+Cada cobrança paga gera uma nova transação.
+
 Casos de uso: criar uma cobrança para um pedido, criar uma cobrança para um serviço, criar uma cobrança para um produto.
diff --git a/docs/splits/__assets__/split-fee-partner.png b/docs/splits/__assets__/split-fee-partner.png
diff --git a/docs/splits/__assets__/split-intro.png b/docs/splits/__assets__/split-intro.png
diff --git a/docs/splits/__assets__/split-subaccount.png b/docs/splits/__assets__/split-subaccount.png
diff --git a/docs/splits/_category_.json b/docs/splits/_category_.json
@@ -0,0 +1,13 @@
+{
+  "label": "Split de cobranças",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "title": "Splits visão geral"
+  },
+  "customProps": {
+    "description": "Splits documentação"
+  }
+}
diff --git a/docs/splits/split-introduction.md b/docs/splits/split-introduction.md
@@ -0,0 +1,70 @@
+---
+id: split-introduction
+title: Introdução
+tags:
+  - split
+---
+
+:::info
+Para a utilização dessa funcionalidade é necessário possuir uma conta na OpenPix e a funcionalidade Split, entre em contato com nosso time de suporte para habilitar essa funcionalidade.
+:::
+
+## Definição de split
+
+O split é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre diversas contas.
+
+![Introdução ao Split](__assets__/split-intro.png)
+
+## Como funciona?
+
+A OpenPix possui diversas funcionalidades de split que permite que o recebimento de uma cobrança seja dividido entre algumas chaves pix via `API`, via plataforma e via `plugin.js`
+
+## Tipos de split
+
+Temos 2 tipos de split, e esses dois tipos de split tem casos de uso diferentes, por isso é necessário antes de utilizar o split entender qual tipo de split utilizar.
+
+### Split de parceiro e afiliado (SPLIT_PARTNER)
+
+O split de parceiro e afiliado é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre a conta do parceiro e a conta do afiliado.
+
+Ou seja, parte do valor da cobrança vai para a conta do parceiro e parte do valor da cobrança vai para a conta do afiliado, sendo possível configurar uma porcentagem ou valor fixo do parceiro diretamente pela plataforma para todas as cobranças.
+
+#### Quando utilizar (SPLIT_PARTNER)
+
+O sistema de parceiros permite a empresas registrar outras empresas como afiliados e gerenciar alguns aspectos do seu funcionamento através das API's e plataforma OpenPix.
+
+Cada afiliado passa pelo processo de abertura de contas na plataforma.
+
+Cada afiliado possui conta virtual na plataforma registrada no CNPJ de sua empresa independente do parceiro.
+
+Cada afiliado recebe valores de cobranças diretamente via pix em sua conta virtual registrada na plataforma.
+
+O parceiro não recebe diretamente valores em sua conta, somente taxa do parceiro perante o uso da feature de `SPLIT_PARTNER`.
+
+Esta feature é indicada para quem quer ter uma relação mais definida entre parceiro e afiliados e pretende envolver parceiros no cadastro completo de uma conta virtual
+
+requisitando assim dados de registro de empresa e sócios como qualquer outra abertura de contas, não recebendo diretamente em suas contas valores relativos a pagamento feitos por afiliados, somente valores relativos a taxa de parceiros.
+
+![Taxa de Parceiro](__assets__/split-fee-partner.png)
+
+### Split de sub-contas (SPLIT_SUB_ACCOUNT)
+
+Sub contas são contas virtuais representadas por uma chave pix que podem transacionar virtualmente valores através do sistema de split de pagamentos. Esses valores podem ser convertidos em transações reais através do saque para a chave pix registrada para a subconta.
+
+Ou seja, parte do valor da cobrança vai para uma chave pix e parte do valor da cobrança vai para outra chave pix, sendo possível definir na hora da criação da cobrança o valor que vai para cada chave pix.
+
+![Split SubAccount](__assets__/split-subaccount.png)
+
+#### Quando utilizar (SPLIT_SUB_ACCOUNT)
+
+O sistema de subcontas permite registrar transações de split em uma subconta a partir de cobranças feitas para uma conta principal.
+
+Subcontas não são contas bancárias reais e somente transacionam valores virtuais permitindo assim a eliminação de etapas burocráticas na abertura da mesma.
+
+Cada subconta só precisa de uma chave pix única para ser aberta, de qualquer tipo, CPF, CNPJ, email, telefone, etc.
+
+Uma empresa pode ter qualquer número de subcontas.
+
+Uma empresa pode a qualquer momento realizar um saque para a chave pix registrada na subconta, tanto via integração de API ou diretamente pela plataforma.
+
+O uso da subconta permite a criação de fluxos menos burocráticos e mais livres dentro da plataforma, os valores sacados só serão debitados da conta principal no momento do saque garantindo total controle ao administrador da empresa dona destas subcontas.
diff --git a/docs/subaccount/_category_.json → docs/splits/subaccount/_category_.json b/docs/subaccount/_category_.json → docs/splits/subaccount/_category_.json
diff --git a/...e-with-splits-to-subaccount-using-api.mdx → ...e-with-splits-to-subaccount-using-api.mdx b/...e-with-splits-to-subaccount-using-api.mdx → ...e-with-splits-to-subaccount-using-api.mdx
diff --git a/docs/splits/subaccount/how-to-create-charge-with-splits-with-plugin.mdx b/docs/splits/subaccount/how-to-create-charge-with-splits-with-plugin.mdx
@@ -0,0 +1,104 @@
+---
+id: how-to-create-charge-with-splits-with-plugin
+title: Como usar o Plugin JS para criar uma cobrança com split para Subconta?
+tags:
+  - concept
+  - api
+  - subaccount
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::info
+Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
+:::
+
+Para criar uma cobrança Pix com split para sub conta, você precisa informar no plugin.js o array de splits a serem realizados na cobrança.
+
+Os campos obrigatórios para criar uma cobrança Pix com Split são os seguintes:
+
+- **`value`**: O valor em `centavos` da cobrança Pix a ser criado.
+- **`correlationID`**: Um identificador único para a cobrança Pix. [CorrelationID](../concepts/correlation-id)
+- **`splits`**: Um array contendo as configurações de split realizado na hora do recebimento.
+
+## Exemplo
+
+O body da sua requisição será semelhante a este exemplo:
+
+```javascript
+function displayOpenPixModal() {
+  window.$openpix = window.$openpix || [];
+
+  window.$openpix.push([
+    'config',
+    {
+      appID: 'yourOpenPixAppId',
+    },
+  ]);
+
+  window.$openpix.push([
+    'pix',
+    {
+      value: 100, // R$ 1,00
+      correlationID: 'c782e0ac-833d-4a89-9e73-9b60b2b41d3a',
+      splits: [
+        {
+          pixKey: '[email protected]', // chave pix da subconta
+          value: 15, // valor a ser splitado em centavos (R$ 0,15)
+          splitType: 'SPLIT_SUB_ACCOUNT', // tipo de split (não alterar)
+        },
+      ],
+    },
+  ]);
+}
+```
+
+O valor do campo `value` dentro do objeto no array de `splits`, é o valor desejado para a realização do split em **centavos**. O valor do split não será debitado da conta de origem pois transações de split para sub contas são transações virtuais, somente será debitado da conta de origem o valor integral do saldo da sub conta no momento do saque da mesma.
+
+Após efetuar a requisição, se tudo ocorreu bem, o plugin exibirá normalmente o qrcode. Caso haja algum erro sintático(formato) no array de splits irá exibir um erro no modal do plugin.
+
+### Exemplos em código
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Open Pix</title>
+  </head>
+  <body>
+    <button id="btn">Pagar com pix</button>
+    <script
+      src="https://plugin.openpix.com.br/v1/openpix.js"
+      allow="clipboard-read; clipboard-write"
+    ></script>
+    <script>
+      const appID = 'seuAppId';
+
+      window.$openpix = window.$openpix ?? [];
+      window.$openpix.push(['config', { appID }]);
+
+      const correlationID = Math.floor(Math.random() * 1000000000);
+
+      document.getElementById('btn').addEventListener('click', () => {
+        window.$openpix.push([
+          'pix',
+          {
+            value: 10000, // R$ 100,00
+            correlationID: correlationID, // no seu sistema, use um identificador único
+            description: 'OpenPix Demo',
+            splits: [
+              {
+                value: 5000, // R$ 50,00
+                pixKey: '[email protected]', // chave pix que receberá R$ 50,00
+                splitType: 'SPLIT_SUB_ACCOUNT', // tipo do split, não mexer
+              },
+            ],
+          },
+        ]);
+      });
+    </script>
+  </body>
+</html>
+```
diff --git a/...ce-and-detais-of-subaccount-using-api.mdx → ...ce-and-detais-of-subaccount-using-api.mdx b/...ce-and-detais-of-subaccount-using-api.mdx → ...ce-and-detais-of-subaccount-using-api.mdx
@@ -1,6 +1,6 @@
 ---
 id: how-to-get-balance-and-details-of-subaccount-using-api
-title: Como  acessar saldo e detalhes de uma Subconta via API?
+title: Como acessar saldo e detalhes de uma Subconta via API?
 tags:
   - api
   - subaccount
@@ -16,15 +16,13 @@ Para a utilização desta funcionalidade é necessário possuir a funcionalidade
 
 Para acessar o saldo e detalhes de uma subconta, você utiliza o _endpoint_ `/api/v1/subaccount/{ID}` da API.
 
-
-Você pode acessar [aqui](https://developers.openpix.com.br/api#tag/sub-account-(request-access)/paths/~1api~1v1~1subaccount~1%7Bid%7D/get)
+Você pode acessar [aqui](<https://developers.openpix.com.br/api#tag/sub-account-(request-access)/paths/~1api~1v1~1subaccount~1%7Bid%7D/get>)
 a documentação referente a esse _endpoint_.
 
 A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.
 
 Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, uma objeto contendo os campos de balance, name, pixKey da subconta requisitada.
 
-
 ### Exemplos em código
 
 ```mdx-code-block
@@ -62,7 +60,6 @@ fetch('https://api.openpix.com.br/api/v1/subaccount/chave-pix-subconta', {
 
 ### Exemplos de resposta
 
-
 ```jsx
 {
   "SubAccount": {
@@ -72,5 +69,3 @@ fetch('https://api.openpix.com.br/api/v1/subaccount/chave-pix-subconta', {
   }
 }
 ```
-
-
diff --git a/...list-subaccounts-of-company-using-api.mdx → ...list-subaccounts-of-company-using-api.mdx b/...list-subaccounts-of-company-using-api.mdx → ...list-subaccounts-of-company-using-api.mdx
diff --git a/...-to-withdraw-fom-subaccount-using-api.mdx → ...-to-withdraw-fom-subaccount-using-api.mdx b/...-to-withdraw-fom-subaccount-using-api.mdx → ...-to-withdraw-fom-subaccount-using-api.mdx
@@ -16,14 +16,12 @@ Para a utilização desta funcionalidade é necessário possuir a funcionalidade
 
 Para realizar o saque integral de uma subconta, você utiliza o _endpoint_ `/api/v1/subaccount/{ID}/withdraw` da API.
 
-
-Você pode acessar [aqui](https://developers.openpix.com.br/api#tag/sub-account-(request-access)/paths/~1api~1v1~1subaccount~1%7Bid%7D/get)
+Você pode acessar [aqui](<https://developers.openpix.com.br/api#tag/sub-account-(request-access)/paths/~1api~1v1~1subaccount~1%7Bid%7D/get>)
 a documentação referente a esse _endpoint_.
 
 A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.
 
-Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, um objeto com os detalhes da transação efetuada para a chave pix registrada na subconta. 
-
+Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, um objeto com os detalhes da transação efetuada para a chave pix registrada na subconta.
 
 ### Exemplos em código
 
@@ -46,23 +44,24 @@ Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisiç
 ```
 
 ```js
-fetch('https://api.openpix.com.br/api/v1/subaccount/chave-pix-subconta/withdraw', {
-  method: 'POST',
-  headers: {
-    Authorization: 'AUTHORIZATION',
-    'Content-Type': 'application/json',
+fetch(
+  'https://api.openpix.com.br/api/v1/subaccount/chave-pix-subconta/withdraw',
+  {
+    method: 'POST',
+    headers: {
+      Authorization: 'AUTHORIZATION',
+      'Content-Type': 'application/json',
+    },
   },
-}).then((res) => res.json());
+).then((res) => res.json());
 ```
 
 ```mdx-code-block
   </TabItem>
 </Tabs>
 ```
 
-
-
-### Exemplos de resposta 
+### Exemplos de resposta
 
 ```jsx
 {

diff --git a/docs/splits/subaccount/split-sub-account-usecases.mdx b/docs/splits/subaccount/split-sub-account-usecases.mdx
@@ -0,0 +1,48 @@
+---
+id: split-sub-account-usecases
+title: Casos de uso de split de sub-contas
+tags:
+  - concept
+  - api
+---
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+:::info
+Para a utilização dessa funcionalidade é necessário possuir a funcionalidade Split
+:::
+
+## Casos de uso de split de sub-contas
+
+O split de sub-contas é uma funcionalidade que permite que o recebimento de uma cobrança seja dividido entre chaves pix. Entenda mais aqui: [O que é um split](../what-is-split#split-de-sub-contas-split_sub_account)
+
+:::info
+Entenda melhor sobre qual tipo de split utilizar [aqui](../when-to-use-split-sub-account-or-partner#Quando usar o sistema de subcontas)
+:::
+
+### Caso de uso 1 - Dividir o valor entre os sócios da empresa
+
+Imagine que você tem uma empresa com 3 sócios e deseja dividir o valor de uma cobrança entre eles. Para isso, você pode criar uma cobrança pix com split de sub-contas, onde o valor da cobrança será dividido entre as chaves pix dos sócios, isso facilita a divisão do valor entre os sócios, economizando tempo e evitando erros.
+
+#### Como dividir o valor entre os sócios da empresa via API
+
+Para dividir o valor entre os sócios da empresa via API, você deve utilizar o _endpoint_ `/api/v1/charge` da API.
+
+Para a API é necessário enviar o campo `splits` no body da requisição, que é um array contendo as configurações de split realizado na hora do recebimento com os valores fixos já definidos, ou seja, seu sistema deve definir o valor que vai para cada chave pix e informar na api da OpenPix.
+
+### Caso de uso 2 - Gorjeta
+
+Administradores de empresas do ramo de alimentação como restaurantes e bares podem cadastrar chave pix de garçons e atendentes como uma subconta e configurar valores
+por cobrança a serem registrados como crédito, podendo então ser sacado a qualquer momento por integração via API ou diretamente pela plataforma.
+
+### Caso de uso 3 - Comissão para vendedores
+
+Gestores de comércio podem cadastrar vendedores através da chave pix do vendendor como subconta e assim gerenciar cada cobrança, para creditar valroes de comissão automaticamente podendo fazer os saque a qualquer momento por integração via API ou diretamente pela plataforma.
+
+## MarketPlace
+
+Gestores de MarketPlace digitais podem criar cobranças com chave pix cadastrada como subconta, registrando assim em cada cobrança paga o valor da comissão por venda
+relacionada a vendas dentro de seu marketplace. Esta integração permite a gestores um gerenciamento de valores automático e facilidade na gestão e no pagamento de valores ao longo do tempo. O saque pode ser feito por integração via api ou diretamente pela plataforma.
diff --git a/docs/subaccount/sub-account-use-cases.md b/docs/subaccount/sub-account-use-cases.md