> ## Documentation Index
> Fetch the complete documentation index at: https://malga-develop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Revisão cadastral de recebedores

> Como responder às revisões cadastrais que o provedor abre para os seus recebedores, dentro do prazo e com dados coletados de forma ativa.

Periodicamente, e sempre que encontra uma inconsistência, o provedor exige que os dados cadastrais de um recebedor sejam confirmados. Quando isso acontece, a Malga abre um **processo de revisão cadastral** com prazo e com a lista dos campos a coletar, e avisa você por webhook.

Responder ao processo é responsabilidade sua: cabe a você coletar os dados **diretamente com o recebedor** e enviá-los pela API antes do prazo. Um processo que vence sem envio leva o provedor a bloquear o recebedor — e com ele o repasse do Split.

<Info>
  A revisão cadastral está disponível hoje para recebedores vinculados ao provedor **Zoop**.
</Info>

## Os dois tipos de revisão

| Tipo | Sigla | Quando acontece |
| - | - | - |
| Periódica | `acp` | Em intervalos definidos pelo provedor, independentemente de qualquer suspeita |
| Por inconsistência | `aci` | Quando o provedor encontra divergência nos dados do recebedor |

A diferença prática está no ritmo. A revisão periódica nasce em `pending`, com uma fase inicial em que o recebedor responde no seu próprio tempo, e passa a `overdue` — cobrança ativa — antes do vencimento. A revisão por inconsistência **já nasce em cobrança**, sem fase inicial, porque o provedor já identificou um problema.

Você não precisa acompanhar essa virada: ela se reflete no `status` do processo, e o que delimita a sua janela de resposta é o `deadlineAt`. Ambos vêm na consulta.

## A regra de coleta ativa

Esta é a regra que mais costuma ser violada na integração, e a que mais custa caro.

<Warning>
  O provedor **proíbe** preencher uma revisão cadastral com dado que você já tinha. Não vale usar bureau de crédito, a sua própria base, o que foi informado no onboarding nem o que foi enviado em uma revisão anterior. A coleta precisa ser **ativa**: feita com o recebedor, agora, por causa deste processo.
</Warning>

A Malga não tem como provar que a coleta foi ativa, mas se recusa a transportar um envio que nem sequer afirme isso. Por essa razão, todo envio carrega um bloco `collection` que descreve como você obteve os dados:

| Campo | Obrigatório | Descrição |
| - | - | - |
| `channel` | Sim | Canal pelo qual você falou com o recebedor (`in_app`, `email`, `phone`, o que se aplicar) |
| `collectedAt` | Sim | Quando a coleta aconteceu. Precisa ser **posterior à abertura do processo** |
| `journeyId` | Sim | Identificador da jornada de coleta do seu lado, para você reencontrar o registro depois |
| `sourceIp` | Não | Endereço de onde o recebedor enviou os dados |
| `userAgent` | Não | Agente do cliente usado na coleta |

A data de coleta é validada contra o momento em que o processo abriu: dado coletado antes de o provedor pedir é, por definição, dado que já estava guardado. Um envio nessas condições é recusado com `400`.

A Malga guarda o que foi declarado. É esse registro que você apresenta caso o provedor audite a origem dos dados.

## O fluxo de ponta a ponta

<Steps>
  <Step title="Você é avisado">
    O provedor abre o processo e a Malga publica `seller.registration_review.required` no seu webhook. Enquanto o processo continuar aberto, você recebe lembretes periódicos.
  </Step>

  <Step title="Você descobre o que coletar">
    Consulte o processo e leia `requestedFields.fields`. Cada item traz o caminho do campo no vocabulário da Malga, o rótulo para exibir no formulário e, quando existe, o formato esperado.
  </Step>

  <Step title="Você coleta com o recebedor">
    Monte o formulário a partir dessa lista e apresente ao recebedor. Registre o momento e a jornada da coleta.
  </Step>

  <Step title="Você envia">
    Faça o `POST` de envio com os dados coletados e a evidência da coleta. A resposta é `202`: a Malga aceitou a coleta e vai encaminhá-la ao provedor.
  </Step>

  <Step title="Você acompanha o desfecho">
    O resultado chega por webhook: `seller.registration_review.finished` quando o provedor confirma, ou `seller.registration_review.failed` quando recusa. Enquanto houver prazo, um envio recusado pode ser corrigido e reenviado.
  </Step>
</Steps>

## Consultar os processos abertos

```bash theme={null}
curl --location --request GET 'https://api.malga.io/v1/sellers/registration-reviews?status=pending,overdue' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY'

< HTTP/2 200
{
    "items": [
        {
            "processId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "sellerId": "ea115e44-7048-11ed-a1eb-0242ac120002",
            "provider": "ZOOP",
            "providerId": "8f14e45f-ceea-467a-9e6f-6c1a5b3a1f2d",
            "reviewType": "acp",
            "status": "pending",
            "deadlineAt": "2026-09-15T23:59:59.000Z",
            "daysRemaining": 18,
            "requestedFields": {
                "raw": ["revenue", "owner.address.postal_code"],
                "fields": [
                    {
                        "path": "revenue",
                        "type": "enum",
                        "required": true,
                        "providerField": "revenue",
                        "label": { "pt-br": "Faixa de faturamento", "en": "Revenue range" },
                        "allowedValues": ["10000_to_50000", "50000_to_100000", "100000_to_500000"]
                    },
                    {
                        "path": "owner.address.zipCode",
                        "type": "string",
                        "required": true,
                        "providerField": "owner.address.postal_code",
                        "label": { "pt-br": "CEP", "en": "Postal code" },
                        "format": { "pt-br": "8 dígitos, sem pontuação", "en": "8 digits, no punctuation" },
                        "pattern": "^[0-9]{8}$"
                    }
                ]
            },
            "requestedFieldsPending": false,
            "createdAt": "2026-08-28T13:04:11.320Z"
        }
    ],
    "meta": {
        "totalItems": 1,
        "itemCount": 1,
        "itemsPerPage": 100,
        "totalPages": 1,
        "currentPage": 1
    }
}
```

Para restringir a um recebedor, use `GET /v1/sellers/{sellerId}/registration-reviews`. Um recebedor com mais de um vínculo ao provedor recebe um item por vínculo, distinguidos pelo campo `providerId`.

### A lista de campos

O bloco `requestedFields` traduz para o vocabulário da Malga o que o provedor pediu no vocabulário dele. Você lê `fields` e ignora `raw`, que existe apenas para rastrear a origem de cada item.

Vale conhecer três detalhes da lista:

* **Um item de `raw` pode virar dois em `fields`.** O endereço é o caso típico: onde o provedor pede um campo só, a Malga separa logradouro e número. Os dois aparecem em `fields` e você coleta os dois; a junção acontece na borda.
* **`pattern` é a mesma expressão que valida o envio.** Se o seu formulário validar por ela, o envio não é recusado por formato.
* **`allowedValues` é informativo.** Um valor fora da lista não é recusado pela Malga, porque o provedor pode aceitar opções que ainda não publicou.

Enquanto o provedor não informa o que pedir, `requestedFields` vem ausente e `requestedFieldsPending` vem `true` — com o prazo já correndo. Nessa situação não há o que coletar ainda, e um envio é recusado com `409`.

## Enviar os dados coletados

O bloco `data` deve conter **exatamente** os campos listados em `requestedFields.fields`: nem um a menos, nem um que não tenha sido pedido. Os caminhos seguem o formato de `path`, aninhados.

```bash theme={null}
curl --location --request POST 'https://api.malga.io/v1/sellers/ea115e44-7048-11ed-a1eb-0242ac120002/registration-reviews/3fa85f64-5717-4562-b3fc-2c963f66afa6/submit' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "collection": {
        "channel": "in_app",
        "collectedAt": "2026-08-28T14:20:00.000Z",
        "journeyId": "jr_8f14e45fceea",
        "sourceIp": "200.150.10.22",
        "userAgent": "Mozilla/5.0"
    },
    "data": {
        "revenue": "10000_to_50000",
        "owner": {
            "address": {
                "zipCode": "01310200"
            }
        }
    }
}'

< HTTP/2 202
```

A resposta `202` significa que a Malga aceitou a coleta, e não que o provedor já a confirmou. O envio ao provedor acontece em segundo plano, justamente para que uma indisponibilidade do lado dele não vire um erro na sua chamada. Acompanhe o desfecho pelos webhooks ou pela listagem.

### Erros de envio

Todos os problemas encontrados vêm juntos em `error.details`, e não um por vez. Isso é deliberado: a coleta já foi feita com o recebedor, e descobrir um campo errado por tentativa significaria voltar até ele várias vezes, com o prazo cada vez menor.

| Código | `error.key` | Causa |
| - | - | - |
| `400` | `invalid_registration_review_payload` | O `data` não corresponde à lista de campos: falta um, sobra um que não foi pedido, ou o formato não bate |
| `400` | — | A evidência de coleta está incompleta, ou a data de coleta é anterior à abertura do processo |
| `404` | `registration_review_not_found` | O processo não existe para esse recebedor |
| `409` | `invalid_registration_review_transition` | O processo está em uma situação que não aceita envio, por exemplo já encerrado |
| `409` | `registration_review_fields_unavailable` | A lista de campos do processo ainda não está utilizável |

Exemplo de recusa por campos fora da lista:

```json theme={null}
{
    "error": {
        "type": "bad_request",
        "code": 400,
        "key": "invalid_registration_review_payload",
        "details": [
            "missing requested field: owner.address.zipCode",
            "field not requested by the provider: business.email"
        ]
    }
}
```

## Situações do processo

| Status | Descrição |
| - | - |
| **pending** | Dentro da fase inicial, apenas na revisão periódica |
| **overdue** | Em cobrança ativa — na periódica após a fase inicial, na inconsistência desde o início |
| **submitting** | Coleta recebida, envio ao provedor em curso |
| **submit\_failed** | Envio recusado ou falho, aguardando correção ou nova tentativa |
| **expired** | Prazo vencido. O envio continua sendo aceito, e continua sendo o melhor caminho |
| **finished** | O provedor confirmou o recebimento |
| **canceled** | Processo invalidado, por exemplo com a remoção do recebedor |
| **unmatched** | A Malga não conseguiu identificar a qual recebedor o processo se refere. É um incidente operacional, tratado pelo nosso time, com o prazo correndo |

Um processo `expired` não é um processo perdido. O envio continua sendo aceito, e segue sendo a única ação que reduz a exposição do recebedor ao bloqueio.

## Prazos e lembretes

O prazo é definido pelo provedor e chega no campo `deadlineAt`. O campo `daysRemaining` traz os dias inteiros que faltam, e fica negativo depois que o prazo passa.

Enquanto o processo continuar aberto, a Malga o lembra por webhook em uma cadência que aperta conforme o prazo se aproxima:

| Tempo até o prazo | Intervalo entre lembretes |
| - | - |
| Mais de 30 dias | A cada 7 dias |
| Entre 8 e 30 dias | A cada 3 dias |
| 7 dias ou menos | Diário |
| Prazo vencido | A cada 7 dias |

## Eventos de webhook

Os seis eventos do processo viajam pelo mesmo webhook em que você já recebe `seller.active` e `seller.inactive`. Veja o payload e a lista completa em [Webhooks](/documentations/webhooks/webhook1-1#seller).

<CardGroup cols={2}>
  <Card title="Gerenciar recebedores" href="/documentations/split/seller">
    Criação, edição e status dos recebedores usados no Split.
  </Card>

  <Card title="Webhooks" href="/documentations/webhooks/webhook1-1">
    Payload, eventos e configuração das notificações.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.