> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Retorno ao seu app (`callbackUri`)

Nas jornadas de abertura de conta e de portabilidade, o titular sai do seu app, faz a captura facial (ou a autorização) numa página nossa e, no fim, ficava numa tela de conclusão da CorpX. O campo opcional `callbackUri` fecha esse ciclo: ao terminar a etapa, o titular é levado de volta para o seu app ou site, e o desfecho vai na própria URI.

Vale para os dois fluxos, porque os dois entram pelo mesmo endpoint:

* abertura de conta PF (`POST /v1/accreditations/pf`) e PJ (`POST /v1/accreditations/pj`);
* portabilidade automática, que usa o mesmo `POST /v1/accreditations/pf`.

## Pré-requisito: cadastrar a URI

A URI precisa estar **registrada previamente** para o seu tenant. Fale com o suporte da CorpX informando exatamente a URI (ou as URIs) que você vai usar — quem cadastra é o nosso time. Se a verificação de identidade estiver habilitada, o gestor do tenant também cadastra a mesma lista em **Verificações de identidade** no painel.

A comparação é **exata**. Se você registrar `https://app.suaempresa.com/onboarding/done`, é essa string que você deve enviar; nós apenas acrescentamos os parâmetros de desfecho no fim. Não há wildcard nem casamento por prefixo: `https://app.suaempresa.com/onboarding/done/extra` é outra URI e precisa de outro cadastro.

Enviar uma URI que não está cadastrada **recusa a criação** com `400 invalid_callback_uri` — você descobre na hora, e não depois de o titular ter gasto a jornada inteira.

### O que é aceito

|                                      |                                              |
| ------------------------------------ | -------------------------------------------- |
| `https://`                           | `https://app.suaempresa.com/onboarding/done` |
| Esquema do seu aplicativo (deeplink) | `suaempresa://onboarding/done`               |

### O que é recusado

* `http://` sem TLS, e qualquer esquema que o navegador execute ou leia do disco (`javascript:`, `data:`, `file:`, `blob:`);
* credenciais embutidas (`https://usuario:senha@...`);
* `localhost`, endereços de rede interna (`10.x`, `192.168.x`, `172.16–31.x`, `169.254.x`, `::1`, `fd00::/8`) e sufixos locais (`.local`, `.internal`);
* endereço IP literal em `https` — use nome de domínio;
* fragmento (`#`), porque ele encerraria a URI antes dos parâmetros;
* host sem domínio (`https://intranet/`).

## Como enviar

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pf" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{
    "person": { "...": "..." },
    "address": { "...": "..." },
    "callbackUri": "https://app.suaempresa.com/onboarding/done"
  }'
```

O campo é opcional. Sem ele, nada muda: o titular termina na página de conclusão da CorpX, como antes.

A URI aceita também é devolvida em `callbackUri` na resposta do `POST` e no `GET /v1/accreditations/{id}`.

## Parâmetros que chegam na volta

| Parâmetro         | Quando                                    | Descrição                                                                                                                                                                                                 |
| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accreditationId` | Sempre                                    | O mesmo `accreditationId` que você recebeu na criação.                                                                                                                                                    |
| `outcome`         | Sempre                                    | Desfecho daquela etapa (tabela abaixo).                                                                                                                                                                   |
| `personId`        | Etapas de uma pessoa (biometria e aceite) | Identificador da pessoa dentro do credenciamento, devolvido em `persons[].personId` desde a criação. **Nunca enviamos CPF na URI**: ela fica em histórico de navegador, log de proxy e telemetria de app. |
| `remainingPeople` | Credenciamento com mais de uma pessoa     | Quantas pessoas ainda faltam concluir a etapa. `0` significa que aquela foi a última.                                                                                                                     |

Exemplo de retorno de um sócio de PJ que concluiu a facial e ainda tem um sócio pendente:

```
https://app.suaempresa.com/onboarding/done?accreditationId=acr_9f8e7d6c5b4a&outcome=biometry_approved&personId=prs_3b1c9a7f2e4d&remainingPeople=1
```

## Vocabulário de `outcome`

Os desfechos negativos reaproveitam as mesmas strings de `errorReason` que você já trata nos webhooks.

| `outcome`                 | Quando acontece                                                                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `biometry_approved`       | Biometria facial aprovada.                                                                                                                                            |
| `biometry_pending`        | A selfie foi enviada e o resultado ainda estava em análise no instante em que o titular voltou. **É o caso mais comum** — o resultado chega em seguida, pelo webhook. |
| `biometry_failed`         | Biometria facial reprovada. Cabe retry.                                                                                                                               |
| `biometry_expired`        | O link de biometria expirou. Cabe retry.                                                                                                                              |
| `acceptance_recorded`     | Termo de aceite registrado (fluxos habilitados sob demanda).                                                                                                          |
| `acceptance_expired`      | O link de aceite expirou.                                                                                                                                             |
| `acceptance_blocked`      | Aceite barrado na análise de dispositivo.                                                                                                                             |
| `consent_accepted`        | O titular autorizou a portabilidade.                                                                                                                                  |
| `consent_declined`        | O titular recusou.                                                                                                                                                    |
| `consent_expired`         | O link de autorização expirou.                                                                                                                                        |
| `consent_identity_failed` | A verificação de identidade do titular não foi aprovada.                                                                                                              |
| `consent_blocked`         | Autorização barrada na análise de dispositivo.                                                                                                                        |
| `error`                   | Falha inesperada do nosso lado. Não conclua nada sobre a jornada; consulte o credenciamento.                                                                          |

> **\`biometry_approved\` não é conta ativa**
>
> No onboarding, concluir a biometria **não** conclui o credenciamento: ainda vêm a revisão, a integração com o liquidante e a ativação. `biometry_approved` com `remainingPeople=0` quer dizer que a etapa de biometria terminou — nada além disso.
>
> A conta só está pronta para operar quando chega o webhook `accreditation.active` (ou o `GET /v1/accreditations/{id}` responde `ACTIVE`) com o `accountId`.

## Os parâmetros não são prova de nada

Eles viajam na barra de endereço e **o próprio titular pode editá-los**. Não há assinatura: são uma dica de interface, para o seu app escolher que tela mostrar quando o usuário voltar.

Qualquer decisão com efeito — liberar acesso, marcar o cadastro como concluído, habilitar uma operação — tem que se apoiar em:

* o webhook (`accreditation.updated`, `accreditation.active`, `accreditation.failed`), ou
* uma consulta a `GET /v1/accreditations/{accreditationId}`.

Trate a volta como "o usuário está de novo no meu app, provavelmente com este resultado" e confirme pelo canal servidor a servidor.

## PJ com vários sócios

Cada sócio tem link próprio, então cada um gera o seu próprio retorno, com o `personId` de quem concluiu. O `remainingPeople` diz se ainda falta alguém, e exatamente um dos retornos sai com `remainingPeople=0`.

Duas coisas que valem para o seu app:

* **`remainingPeople=0` significa que não há mais pendência**, não que todos foram aprovados. Um sócio reprovado pode repetir a biometria, e enquanto ele não repetir ele não conta como pendente. O status individual de cada pessoa vem em `persons[].biometryStatus` no `GET`.
* O desfecho individual (`outcome`) e o do conjunto (`remainingPeople`) são informações distintas e chegam juntas de propósito.

## Quando o redirect não acontece

O titular termina na nossa página de conclusão, sem erro, quando:

* a accreditation não tem `callbackUri`;
* a URI foi **removida da allowlist** no meio da jornada — a autorização é reconferida no momento do salto, e a remoção vale na hora;
* não foi possível montar a URI de retorno.

Nesses casos o credenciamento segue normalmente; só o salto de volta é que não acontece. Como o desfecho de verdade chega por webhook, nada é perdido.

## Deeplink e navegador

O salto é feito por uma página nossa, com um link visível, e não por redirect HTTP: esquema de aplicativo não atravessa redirect de forma confiável em todos os navegadores. Se o app não estiver instalado, o titular vê o link e a mensagem do desfecho em vez de uma tela de erro do navegador.