> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/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>


## Related topics

- [Set 09, 2026 - Revisão cadastral de recebedores](/release-notes/2026-09-09-Release-Notes.md)
- [Mais releases](/release-notes/releases.md)
- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)
- [Listar processos de revisão cadastral](/api-reference/sellers/listar-processos-de-revisao-cadastral.md)