Revisão cadastral de recebedores

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.

A revisão cadastral está disponível hoje para recebedores vinculados ao provedor Zoop.

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.

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.

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

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.

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.

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.

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.

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.

Consultar os processos abertos

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.

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:

{
    "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.

Gerenciar recebedores

Criação, edição e status dos recebedores usados no Split.

Webhooks

Payload, eventos e configuração das notificações.

Comece na Malga

Conexões

Guias

Serviços adicionais

Revisão cadastral de recebedores

Os dois tipos de revisão

A regra de coleta ativa

O fluxo de ponta a ponta

Consultar os processos abertos

A lista de campos

Enviar os dados coletados

Erros de envio

Situações do processo

Prazos e lembretes

Eventos de webhook

Gerenciar recebedores

Webhooks

​Os dois tipos de revisão

​A regra de coleta ativa

​O fluxo de ponta a ponta

​Consultar os processos abertos

​A lista de campos

​Enviar os dados coletados

​Erros de envio

​Situações do processo

​Prazos e lembretes

​Eventos de webhook

Gerenciar recebedores

Webhooks

Os dois tipos de revisão

A regra de coleta ativa

O fluxo de ponta a ponta

Consultar os processos abertos

A lista de campos

Enviar os dados coletados

Erros de envio

Situações do processo

Prazos e lembretes

Eventos de webhook