Este guia é para **plataformas** (sistemas de gestão, PDVs, cardápios digitais, ERPs, e-commerces) que querem oferecer pagamentos Pix da Woovi para os seus clientes dentro do próprio sistema.

No **modelo parceiro**, a sua plataforma é a empresa **parceira** e cada cliente seu vira uma empresa **afiliada**, com conta Woovi própria. A plataforma cuida do cadastro e da experiência do cliente. A Woovi fica por baixo, como infraestrutura de pagamento.

Ao final, sua plataforma vai conseguir:

1. Integrar com a Woovi
2. Ter o modelo parceiro habilitado
3. Cadastrar os seus clientes como afiliados
4. Ativar as contas das afiliadas
5. Permitir o saque das afiliadas
6. Operar cobranças, estornos e repasses no dia a dia

## Como o modelo funciona

* **Cada afiliada tem a própria conta Woovi**, no CNPJ dela. O dinheiro das vendas cai na conta da afiliada, não na conta da plataforma.
* **A plataforma ganha em cada transação:** você define uma taxa por afiliada, que é cobrada automaticamente em cada pagamento recebido e cai na sua conta de parceiro.
* **Tudo pode ser feito via API:** criar a afiliada, gerar as credenciais dela, criar cobranças e fazer os saques.

![Como funciona o modelo parceiro](https://chat.woovi.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBZzJ0IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--80fec349c273fa926ffd1a904fff2034c5b3ea7e/parceiro-modelo.png)

![Jornada de integração do parceiro](https://chat.woovi.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBZzZ0IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--76041947db678a98e6ff1fd054b4943e25d395bb/parceiro-jornada.png)

## 1. Integrar com a Woovi

1. Crie a conta da sua plataforma na Woovi. Essa será a sua **empresa parceira**.
2. Gere uma chave de API (AppID) com os escopos de parceiro: **PARTNER_COMPANY_POST**, **PARTNER_COMPANY_GET** e **PARTNER_APPLICATION_POST**.
   * [Como gerar o AppID](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1781546626-como-gerar-o-ap_id)
3. Faça os testes no ambiente de sandbox antes de ir para produção.
   * [Ambiente de testes](https://developers.woovi.com/docs/intro/test-environment)

**Dica:** o modelo parceiro também precisa ser habilitado na sua conta de sandbox. Peça ao nosso time junto com a habilitação de produção.

## 2. Habilitar o modelo parceiro

O modelo parceiro é liberado pelo time da Woovi após uma análise do perfil da sua plataforma. Fale com a gente para solicitar.

* [Como se tornar parceiro e ter afiliados?](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-se-tornar-parceiro-e-ter-afiliados)

Com o modelo liberado, aparece no painel o menu **Minhas empresas**, onde você acompanha todas as afiliadas.

**Defina a sua taxa.** Você pode configurar uma taxa por afiliada, somada à taxa da Woovi em cada transação. Esse valor é a receita da sua plataforma.

* [Customizando a taxa de seu afiliado](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/customizando-a-taxa-de-seu-afiliado)
* [Split Partner (documentação técnica)](https://developers.woovi.com/docs/split/split-partner)

## 3. Cadastrar as afiliadas

Com o AppID da sua empresa parceira, crie cada cliente como afiliada:

* **Via API:** **POST /api/v1/partner/company**, enviando os dados da empresa (nome, CNPJ, site) e do usuário responsável (nome, e-mail, telefone e CPF).
  * [Como criar uma empresa afiliada via API](https://developers.woovi.com/docs/partnerships/how-to-create-a-affiliate-company-via-api)
* **Em lote, pelo painel:** para cadastrar muitas empresas de uma vez.
  * [Como registrar diversas empresas afiliadas de uma vez](https://developers.woovi.com/docs/partnerships/how-register-lot-company)
* **Pelo link de afiliado:** o próprio cliente se cadastra por um link seu.
  * [Como integrar como parceiro da Woovi](https://developers.woovi.com/docs/partnerships/how-to-integrate-as-woovi-partner)

A resposta do **POST /api/v1/partner/company** traz o **linkOnboarding**: é o link em que o cliente completa o cadastro da conta (dados da empresa e dos sócios).

**O cliente já tem conta na Woovi?** Nesse caso, fale com o nosso time antes de cadastrar. Cadastrar pela API cria uma empresa nova, e o vínculo de uma conta que já existe com a sua plataforma é feito por nós.

## 4. Ativar as contas

1. **Leve o cliente ao **linkOnboarding**.** Você pode abrir o link em uma nova aba, redirecionar ou exibir dentro do seu sistema, inclusive sem a logo da Woovi.
   * [Como incorporar o link de onboarding no seu site](https://developers.woovi.com/docs/baas/kyc/kyc-api-onboarding-embed)
2. **Acompanhe o status** da afiliada com **GET /api/v1/partner/company/{taxID}** ou pelo menu **Minhas empresas**.
3. **Com a conta aprovada, gere as credenciais da afiliada** com **POST /api/v1/partner/application**. A resposta traz o **clientId** e o **clientSecret**, que formam o AppID da afiliada.
   * [Como acessar a API com uma empresa afiliada](https://developers.woovi.com/docs/partnerships/how-to-access-api-via-affiliated-company)
4. **Cadastre o webhook da afiliada** com o AppID dela, para receber os avisos de pagamento.
   * [Como criar um webhook para uma empresa afiliada](https://developers.woovi.com/docs/partnerships/how-to-create-a-webhook-to-affiliated-company)

**Importante:** gere o AppID da afiliada **depois** que a conta dela estiver aprovada. O AppID é vinculado à conta da afiliada no momento em que é criado. Se ele for gerado antes, algumas consultas (como o extrato) não vão encontrar a conta.

### Escopos do AppID da afiliada

No **POST /api/v1/partner/application**, informe em **scopes** só o que a sua plataforma vai usar. Os mais comuns:

| Para quê | Escopos |
|---|---|
| Cobranças | **CHARGE_POST**, **CHARGE_GET**, **CHARGE_DELETE** |
| Estornos | **CHARGE_REFUND_POST** |
| Webhooks | **WEBHOOK_POST** |
| Conta, extrato e transações | **ACCOUNT_GET**, **STATEMENT_GET**, **TRANSACTION_GET** |
| Saque | **ACCOUNT_WITHDRAW_POST** |

Escopos que movimentam dinheiro, como o de saque, exigem **IP permitido**. Cadastre o IP do seu servidor uma única vez na sua empresa parceira e ele passa a valer para todas as afiliadas.

* [IPs permitidos para Pix out via API (inclusive no modelo parceiro)](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1789147554-i_ps-permitidos-para-pix-out-via-api-como-configurar-inclusive-no-modelo-parceiro)

## 5. Permitir o saque

O saldo das vendas fica na conta da afiliada. Para levar esse dinheiro para a conta bancária do cliente:

* **Pela sua plataforma, via API:** consulte a conta com **GET /api/v1/account** e solicite o saque com **POST /api/v1/account/{accountId}/withdraw**, usando o AppID da afiliada.
* **Pelo painel Woovi:** o próprio cliente pode sacar, se tiver acesso.
  * [Como fazer um saque manual?](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-fazer-um-saque-manual)
  * [Saque automático](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/saque-automatico)

Pontos que valem para as regras do seu sistema:

* O saque vai para a **chave Pix de saque cadastrada na conta** da afiliada, normalmente o CNPJ dela.
* A **gratuidade do saque depende do valor e da titularidade**: saque para uma conta de mesma titularidade (o CNPJ da afiliada) segue a regra de isenção do plano, e saque para uma chave de outro titular (como o CPF de um sócio) é tarifado.
* Os saques têm **limites** por período, definidos conforme a análise da conta.
  * [Limites de saques](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/limites-de-saques)
* Você também pode cobrar uma taxa sua sobre o saque, como faz na venda.

## 6. Operar no dia a dia

### Cobrança no checkout

![Um pedido do começo ao fim](https://chat.woovi.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaEt0IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--a5552072d967d281bd7eb309083bd575bebc3df3/parceiro-pedido-v2.png)

1. O cliente final escolhe Pix no seu cardápio, loja ou PDV.
2. A plataforma cria a cobrança com **POST /api/v1/charge**, usando o AppID da afiliada e um **correlationID** com o número do pedido.
3. O QR Code é exibido para o cliente final.
4. Quando o pagamento é confirmado, o webhook **OPENPIX:CHARGE_COMPLETED** chega com o **correlationID**, e a plataforma libera o pedido.

* [Como criar uma cobrança via API](https://developers.woovi.com/docs/charge/how-to-create-charge-using-api)

### Estornos

Para devolver o valor de um pedido cancelado, use o estorno da cobrança, com o AppID da afiliada.

* [Como criar um reembolso de cobrança](https://developers.woovi.com/docs/refund/charge-refund-create-api)

Para acompanhar o resultado do estorno, assine os webhooks **PIX_TRANSACTION_REFUND_SENT_CONFIRMED** (estorno concluído) e **PIX_TRANSACTION_REFUND_SENT_REJECTED** (estorno não realizado).

### Eventos principais

| Evento | Quando acontece |
|---|---|
| **OPENPIX:CHARGE_COMPLETED** | Cobrança paga |
| **OPENPIX:CHARGE_EXPIRED** | Cobrança expirou sem pagamento |
| **PIX_TRANSACTION_REFUND_SENT_CONFIRMED** | Estorno concluído |
| **PIX_TRANSACTION_REFUND_SENT_REJECTED** | Estorno não realizado |
| **OPENPIX:MOVEMENT_CONFIRMED** | Saque concluído |
| **OPENPIX:MOVEMENT_FAILED** | Saque não realizado |

* [Eventos de webhook](https://developers.woovi.com/webhook-events)

### Acompanhando as afiliadas

No menu **Minhas empresas**, você vê as afiliadas, as cobranças, a conta, as integrações e os logs de webhook de cada uma.

* [O que o Parceiro Pode Ver e Editar na Conta do Afiliado?](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/o-que-o-parceiro-pode-ver-e-editar-na-conta-do-afiliado)

## Exemplo: plataforma de gestão para restaurantes

Um dos cenários mais comuns do modelo parceiro é o de sistemas de gestão para food service, com milhares de restaurantes na base. O fluxo costuma ser assim:

1. No sistema da plataforma, o restaurante clica em ativar pagamentos Pix e informa o CNPJ.
2. A plataforma cria a afiliada (**POST /api/v1/partner/company**) e abre o **linkOnboarding** para o restaurante completar o cadastro.
3. Com a conta aprovada, a plataforma gera o AppID do restaurante (**POST /api/v1/partner/application**) e cadastra o webhook dele.
4. A partir daí, cada pedido do cardápio digital ou do PDV vira uma cobrança Pix, e o pedido é liberado automaticamente quando o webhook de pagamento chega.
5. O restaurante saca o saldo pela própria plataforma, que chama o saque via API, ou pelo painel Woovi.
6. A plataforma recebe a taxa dela em cada transação, direto na conta de parceira.

## Dúvidas ou erros na integração

Veja o artigo [Erros comuns na integração de parceiros](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/1790350040-erros-comuns-na-integracao-de-parceiros) ou fale com o nosso time pelo chat.