> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plataformas: guia completo de ativação por API

> Colete o cadastro dentro do seu produto e ative a organização por API: preencher, subir documentos, enviar para análise e tratar o resultado.

Este guia mostra como ativar financeiramente uma organização conectada **sem redirecionar o vendedor**: você coleta o cadastro nas suas próprias telas, grava tudo na organização pela API e envia para análise com uma chamada.

Ele foi escrito para o time de **produto e engenharia de uma plataforma** que já tem (ou quer ter) o formulário de cadastro dentro do próprio produto.

<Info>
  Já integra este fluxo? Revise o checklist de [mudanças na integração de
  ativação](/platforms/activation-integration-changes).
</Info>

<Warning>
  Este guia só se aplica a contas com o produto **Chargefy for Platforms**
  habilitado. Nesse produto, uma plataforma opera pagamentos para suas
  **organizações filhas**.
</Warning>

## Os dois caminhos

Ativar uma organização sempre significa a mesma coisa: entregar dados cadastrais, documento de identidade, selfie e conta para saques para análise. O que muda é **quem constrói o formulário**.

|                           | Hospedado                                       | Por API                                                     |
| ------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| Quem coleta               | A Chargefy, em uma página hospedada.            | O seu produto, nas suas telas.                              |
| O que você constrói       | Um botão e um redirect.                         | Formulário, upload, validações e estados.                   |
| Sai do seu produto?       | Sim, o vendedor é redirecionado.                | Não.                                                        |
| Quem guarda os documentos | A Chargefy.                                     | A Chargefy — os arquivos sobem direto pela API de arquivos. |
| Como fica pronto          | O vendedor conclui e envia na página hospedada. | Você chama `POST /v1/organizations/{id}/submit`.            |

**Use o hospedado** quando quiser o menor esforço possível: ele continua existindo, é mantido pela Chargefy e acompanha mudanças regulatórias sozinho. O passo a passo está em [Ativação hospedada](/platforms/activate-with-hosted-session).

**Use este caminho** quando você já tem cadastro próprio (marketplace com conta de vendedor, ERP, app com fluxo de identidade) e não quer mandar o usuário para fora, ou quando precisa controlar a ordem das telas, a cópia e o momento do envio.

Os dois caminhos escrevem no **mesmo cadastro** da mesma organização, e o resultado chega pelo mesmo evento (`organization.updated`). Enquanto o cadastro não foi enviado, dá para coletar parte por API e terminar no hospedado: o fluxo hospedado reabre com o que você já gravou.

## Pré-requisitos

1. Plataforma ativa e com o setup concluído.
2. Uma **API key de plataforma** com escopo `platform_admin` (`Authorization: Bearer {{PLATFORM_API_KEY}}`). O recurso `organizations` não aceita API keys de organizações padrão.
3. Um endpoint de webhook registrado — o resultado da análise chega por [`organization.updated`](/api-reference/webhooks/organization.updated), não por polling.
4. Um lugar no seu produto para capturar o **aceite dos termos** (data, hora e IP de quem aceitou).

<Note>
  Nos endpoints `/v1/organizations`, a coleção ou o ID da URL define qual
  organização será usada. Não envie o header `Organization` nessas chamadas. Use
  esse header apenas em recursos da conta conectada, como o upload de arquivos.
</Note>

## O modelo, em uma frase

A **organização é a ficha do cadastro**: você escreve os blocos com `POST /v1/organizations/{id}`, `requirements.missing` diz exatamente o que ainda falta, e quando `missing` fica vazio você chama `POST /v1/organizations/{id}/submit`.

Três consequências práticas:

* Você nunca precisa adivinhar o que falta: a lista vem pronta, em caminhos pontuados (`representative.birthdate`, `payout_account`, `terms_acceptance.ip`).
* A escrita é merge parcial: mande tudo de uma vez ou campo a campo, na ordem que a sua tela quiser.
* Salvar não envia. O envio é explícito — o que permite autossalvar cada campo sem consumir uma tentativa de análise.

<Warning>
  `activation_status` não é o status da conexão com a plataforma.
  `not_submitted`, `in_review` e `disabled` continuam pertencendo à mesma
  organização conectada. Corrija e reenvie o mesmo `org_*`; não crie uma conta
  duplicada.
</Warning>

## Passo a passo (organização CNPJ)

### 1. Crie a organização conectada

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme"
  }'
```

Guarde o `id` (`org_*`) — ele é o identificador estável do vendedor no seu sistema. Repetir a chamada com o mesmo documento devolve a mesma organização.

A resposta já traz a lista de tarefas:

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "activation_status": "not_submitted",
  "activation_status_updated_at": null,
  "activation_submitted_at": null,
  "avatar_url": null,
  "billing_additional_info": null,
  "billing_address": null,
  "billing_name": null,
  "branding_settings": {
    "accent_color": null,
    "border_style": null,
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "business_profile": null,
  "company": null,
  "created_at": "2026-07-23T14:00:00Z",
  "dashboard_settings": {
    "timezone": "America/Sao_Paulo"
  },
  "document": "12345678000190",
  "document_type": "cnpj",
  "email": null,
  "individual": null,
  "livemode": true,
  "metadata": {},
  "name": "Acme",
  "payout_account": null,
  "platform": "plat_n5aNBQBXiqvYWPt4",
  "representative": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "company.address",
      "company.email",
      "company.name",
      "company.opening_date",
      "company.phone",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "statement_descriptor",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  },
  "socials": [],
  "statement_descriptor": null,
  "terms_acceptance": null,
  "updated_at": "2026-07-23T14:00:00Z",
  "website": null
}
```

<Info>
  A organização pode nascer `active` com `requirements.missing` vazio: o
  CPF/CNPJ dela já tinha um cadastro aprovado e o status é do documento. Nesse
  caso não há nada a coletar nem a enviar — pule direto para operar a
  organização.
</Info>

### 2. Releia `requirements.missing` antes de montar a tela

Em organizações CNPJ, a Chargefy completa os dados públicos da empresa (razão social, nome fantasia, endereço, data de abertura e, quando existem no registro, e-mail e telefone) logo após a criação, a partir do registro público do CNPJ. Isso acontece em segundo plano: a resposta do create ainda mostra `company: null`, mas uma leitura seguinte costuma vir com o bloco preenchido e com menos itens em `missing`.

```bash theme={"theme":"css-variables"}
curl -X GET "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
```

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "company": {
    "address": {
      "city": "São Paulo",
      "line1": "Avenida Paulista",
      "line2": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "number": "1000",
      "postal_code": "01310100",
      "state": "SP"
    },
    "email": "financeiro@meusite.com",
    "name": "ACME COMERCIO LTDA",
    "opening_date": "2019-03-14",
    "phone": "11999999999",
    "trade_name": "Acme"
  },
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "business_profile.annual_revenue",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "statement_descriptor",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}
```

Use `missing` como fonte da sua tela: peça só o que está na lista. Você pode sobrescrever qualquer campo preenchido automaticamente — o que você grava sempre vence.

<Tip>
  Se essa consulta responder `404`, confirme o `org_*`, o ambiente da API key e
  se a conexão com a plataforma continua ativa. Adicionar o header
  `Organization` não corrige esse erro, porque o alvo já está na URL.
</Tip>

### 3. Complete os dados da empresa

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile": {
      "annual_revenue": {
        "amount": 120000000,
        "currency": "brl"
      },
      "url": "https://meusite.com"
    },
    "company": {
      "address": {
        "city": "São Paulo",
        "line1": "Avenida Paulista",
        "line2": "Conjunto 101",
        "neighborhood": "Bela Vista",
        "number": "1000",
        "postal_code": "01310100",
        "state": "SP"
      },
      "email": "financeiro@meusite.com",
      "name": "ACME COMERCIO LTDA",
      "opening_date": "2019-03-14",
      "phone": "+5511999999999",
      "trade_name": "Acme"
    },
    "statement_descriptor": "ACME"
  }'
```

O que vale saber:

* `business_profile.annual_revenue.amount` é **em centavos** e `currency` é sempre `"brl"`. `business_profile.mcc` é somente leitura: a categoria do negócio é resolvida pela Chargefy a partir do registro público do CNPJ.
* `statement_descriptor` é o nome que aparece na fatura do comprador. Ele é normalizado (maiúsculas, letras, números e espaços) e precisa ficar entre 5 e 22 caracteres depois da normalização. É uma propriedade do documento fiscal: ao alterar, o novo valor passa a valer para todas as cobranças daquele CPF/CNPJ.
* Endereço é atômico: quando enviado, é validado inteiro e substitui o anterior. `line1`, `number`, `neighborhood`, `city`, `state` (2 letras) e `postal_code` (8 dígitos) são obrigatórios; `line2` é opcional.
* Telefone aceita formatação livre e é guardado normalizado (DDD + número).

A resposta vem com `missing` menor:

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "representative.address",
      "representative.birthdate",
      "representative.document",
      "representative.email",
      "representative.first_name",
      "representative.last_name",
      "representative.phone",
      "representative.verification.document",
      "representative.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}
```

### 4. Complete os dados do responsável

O responsável é a pessoa física que responde legalmente pela empresa.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "document": "12345678901",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888"
    }
  }'
```

`first_name` e `last_name` precisam ser o nome civil da pessoa: nomes com números ou com termos de razão social (`Ltda`, `EIRELI`, `Sociedade`) são recusados com `400`. `document` é o CPF do responsável, com ou sem pontuação.

Sobram os arquivos, a conta e o aceite:

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "representative.verification.document",
      "representative.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}
```

### 5. Suba os arquivos de verificação

Antes de implementar a tela de anexos, defina quem será verificado:

| Organização filha | Pessoa verificada                                 | De quem devem ser a selfie e o documento |
| ----------------- | ------------------------------------------------- | ---------------------------------------- |
| **CPF**           | O próprio titular                                 | Do titular                               |
| **CNPJ**          | O responsável legal informado em `representative` | Do responsável legal                     |

Peça sempre uma **selfie separada** e apenas **uma** das opções de documento:

| Opção                   | Arquivos do documento                                     | Como anexar na API                             | Total com a selfie |
| ----------------------- | --------------------------------------------------------- | ---------------------------------------------- | ------------------ |
| **CNH digital**         | 1 PDF oficial exportado do app CNH Digital                | `type: "cnh"`, use `front` e omita `back`      | 2                  |
| **CNH frente e verso**  | 1 arquivo da frente + 1 arquivo do verso da CNH física    | `type: "cnh"`, use `front` e `back`            | 3                  |
| **RG frente e verso**   | 1 arquivo da frente + 1 arquivo do verso                  | `type: "rg"`, use `front` e `back`             | 3                  |
| **CREF completo**       | 1 arquivo da carteira aberta, com frente e verso visíveis | `type: "cref"`, use `front` e omita `back`     | 2                  |
| **CREF frente e verso** | 1 arquivo da frente + 1 arquivo do verso                  | `type: "cref"`, use `front` e `back`           | 3                  |
| **CIN digital**         | 1 PDF oficial exportado do app gov.br                     | `type: "cin"`, use `front` e omita `back`      | 2                  |
| **CIN frente e verso**  | 1 arquivo da frente + 1 arquivo do verso                  | `type: "cin"`, use `front` e `back`            | 3                  |
| **Passaporte**          | 1 arquivo da página de identificação                      | `type: "passport"`, use `front` e omita `back` | 2                  |

As combinações inválidas falham na declaração, com `400` e `param` no campo exato: `rg` exige `back`; `passport` não aceita `back`; `cnh` ou `cin` com `front` único representam o documento digital e exigem o PDF oficial do app do governo — para fotos do documento físico, envie `front` e `back`.

<Info>
  A ativação atual não solicita upload de comprovante de endereço, contrato
  social, Requerimento de Empresário, comprovante de renda, documentos dos
  demais sócios ou comprovante bancário. Endereços e dados da conta para saques
  são preenchidos nos campos da organização.
</Info>

Documento de identidade e selfie sobem por [`POST /v1/files`](/api-reference/files/create) com `purpose=kyc_document`. Com API key de plataforma, aponte a organização dona do arquivo no header `Organization`.

<Warning>
  Nunca exponha a API key da plataforma no navegador. Envie o arquivo da sua
  interface para o backend da plataforma e faça o upload para a Chargefy a
  partir dele. Depois de receber o `file_*`, descarte a cópia temporária.
</Warning>

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_Tm6DzHLoHTme9y47" \
  -F "purpose=kyc_document" \
  -F "file=@/caminho/local/documento-frente.jpg"
```

```json theme={"theme":"css-variables"}
{
  "id": "file_B3cAGJDsoPoGF32Z",
  "object": "file",
  "created_at": "2026-07-23T14:01:00Z",
  "filename": "documento-frente.jpg",
  "mime_type": "image/jpeg",
  "purpose": "kyc_document",
  "size": 184320,
  "...": "demais campos do objeto file"
}
```

Guarde o `id` (`file_*`) — é ele que você anexa ao cadastro no passo seguinte.

Faça um upload separado para cada posição indicada na tabela. A selfie aceita JPG, JPEG, PNG, WebP, BMP, HEIC e HEIF — nunca PDF. Os arquivos de documento aceitam os mesmos formatos e também PDF, com duas exceções: a CNH digital e a CIN digital aceitam somente o PDF oficial do app do governo (CNH Digital e gov.br, com QR code). Imagens podem ter até 20 MB e são normalizadas automaticamente para menos de 4,5 MB; PDFs podem ter até 5 MB e são armazenados sem recompressão. Arquivos de verificação são privados: a `url` do arquivo é assinada e expira em 1 hora — o cadastro não precisa dela.

<Info>
  Para o documento, use uma imagem do original válido e colorido, com todas as
  bordas e dados legíveis, sem cortes, reflexos, sombras, inclinação, dedos ou
  objetos cobrindo informações. Para a selfie, use boa iluminação, fundo neutro,
  rosto centralizado e sem filtros. A pessoa não deve segurar o documento na
  selfie.
</Info>

Veja também a página que você pode compartilhar com o vendedor: [Documentos de verificação aceitos](/help/identity-verification-documents).

### 6. Anexe os arquivos ao cadastro

O bloco depende da opção escolhida. Nos exemplos de CNPJ abaixo, ele fica em `representative.verification`. Para uma organização CPF, use o mesmo conteúdo em `individual.verification`.

#### CNH digital

Use `front` para o PDF oficial exportado do app CNH Digital e omita `back`.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cnh"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'
```

#### CNH frente e verso

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cnh"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'
```

#### RG frente e verso

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "rg"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'
```

#### CREF completo

Use `front` para o arquivo único da carteira aberta, em imagem ou PDF, e omita `back`.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cref"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'
```

#### CREF frente e verso

Use dois arquivos separados quando a carteira não estiver aberta em um único arquivo.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cref"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'
```

#### CIN digital

Use `front` para o PDF oficial exportado do app gov.br e omita `back`.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cin"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'
```

#### CIN frente e verso

Use dois arquivos separados para a CIN física.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "back": "file_vcqeVUqwgGApyUC9",
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "cin"
        },
        "selfie": "file_bLGr3spyEqPe1WKr"
      }
    }
  }'
```

#### Passaporte

Use `front` para a imagem da página de identificação. `back` não é aceito para passaporte.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": {
      "verification": {
        "document": {
          "front": "file_B3cAGJDsoPoGF32Z",
          "type": "passport"
        },
        "selfie": "file_vcqeVUqwgGApyUC9"
      }
    }
  }'
```

* `type` aceita `cnh`, `rg`, `cref`, `cin` e `passport`. CNH e CIN aceitam o PDF oficial do documento digital em `front` ou as duas fotos do documento físico em `front` e `back`. O RG exige os dois lados. O CREF aceita a carteira aberta em `front` ou os dois lados em `front` e `back`. O passaporte usa somente `front`.
* O bloco `document` é atômico: reenviá-lo substitui frente, verso e tipo de uma vez.
* Cada arquivo só pode ocupar um espaço: usar o mesmo arquivo (ou o mesmo conteúdo) como documento e selfie retorna `400`.
* As fotos nunca voltam no objeto `organization`. O progresso aparece em `requirements`.

### 7. Conta para saques e aceite dos termos

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_account": {
      "account_number": "1234567",
      "bank_code": "341",
      "routing_number": "0001",
      "type": "checking"
    },
    "terms_acceptance": {
      "accepted_at": "2026-07-23T13:58:12Z",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    }
  }'
```

A resposta devolve a organização com o bloco `payout_account` já resolvido — incluindo `bank_name`, derivado do `bank_code` (confira se o banco é o esperado antes de submeter):

```json theme={"theme":"css-variables"}
{
  "payout_account": {
    "id": "pa_8gqQH2RWZi27y1sZ",
    "object": "payout_account",
    "account_number_last4": "4567",
    "bank_code": "341",
    "bank_name": "Itaú Unibanco S.A.",
    "...": "demais campos do objeto payout_account"
  }
}
```

* A conta é atômica: os quatro campos vão juntos. O titular nunca é enviado — é sempre a identidade da organização.
* `terms_acceptance` é o registro de que o vendedor aceitou os termos de serviço da Chargefy no **seu** produto: quando (`accepted_at`, no passado) e de onde (`ip`). `user_agent` é opcional e recomendado.

Agora `missing` está vazio — o cadastro está pronto, esperando o envio:

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "not_submitted",
  "activation_submitted_at": null,
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [],
    "pending_verification": []
  }
}
```

### 8. Envie para análise

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47/submit" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
```

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "in_review",
  "activation_submitted_at": "2026-07-23T14:02:00Z",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [],
    "pending_verification": []
  }
}
```

Comportamento do envio:

* **Faltou campo** → `400` com `code: "requirements_incomplete"`, `param` no primeiro caminho e a lista completa em `message`.
* **Já enviado** → `200` com o objeto atual. Organização `in_review` ou `active` não reenvia nada e não abre uma análise nova; repetir por timeout é seguro.
* **`in_review` significa "cadastro recebido"**, não "aprovado". Não libere recebimentos aqui.

Contrato completo: [Enviar o cadastro](/api-reference/organizations/submit).

### 9. Acompanhe o resultado por webhook

A análise é assíncrona (normalmente minutos). O veredito chega por [`organization.updated`](/api-reference/webhooks/organization.updated):

| `activation_status`                  | O que significa                          | O que fazer                                       |
| ------------------------------------ | ---------------------------------------- | ------------------------------------------------- |
| `in_review`                          | Cadastro recebido, análise em andamento. | Mostre "em análise".                              |
| `active`                             | Aprovado.                                | Libere recebimentos.                              |
| `disabled`                           | Reprovado.                               | Leia `requirements` e ofereça a correção.         |
| `not_submitted` (depois de um envio) | O envio falhou antes da análise.         | `requirements.errors` explica; corrija e reenvie. |

Aprovação:

```json theme={"theme":"css-variables"}
{
  "id": "evt_YGcrStJSosTpw1F8",
  "object": "event",
  "created_at": "2026-07-23T15:30:00Z",
  "data": {
    "object": {
      "id": "org_Tm6DzHLoHTme9y47",
      "object": "organization",
      "...": "demais campos do objeto organization",
      "activation_status": "active",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": []
      }
    },
    "previous_attributes": {
      "activation_status": "in_review"
    }
  },
  "livemode": true,
  "organization": "org_Tm6DzHLoHTme9y47",
  "request": {
    "id": "req_QLA3Wk2W4DieY219"
  },
  "type": "organization.updated"
}
```

Processe por `id` do evento (idempotência) e trate `code` desconhecido de forma genérica — o conjunto cresce.

## Variante pessoa física (CPF)

Idêntico, com duas diferenças:

1. Não existe bloco `company`: a pessoa física é o próprio vendedor e todos os dados dela vão em `individual`.
2. `individual.document` **não é aceito** — o documento da organização já é o CPF dela. Enviar esse campo retorna `400`.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/organizations/org_Tm6DzHLoHTme9y47" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "individual": {
      "address": {
        "city": "São Paulo",
        "line1": "Rua das Flores",
        "neighborhood": "Jardins",
        "number": "50",
        "postal_code": "01410000",
        "state": "SP"
      },
      "birthdate": "1985-06-02",
      "email": "nome@email.com",
      "first_name": "Maria",
      "last_name": "Souza",
      "phone": "+5511988888888"
    }
  }'
```

Os caminhos de `missing` acompanham: `individual.address`, `individual.verification.selfie`, e assim por diante. O resto do fluxo (arquivos, conta, aceite, envio) é igual.

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "document_type": "cpf",
  "requirements": {
    "disabled_reason": null,
    "errors": [],
    "missing": [
      "payout_account",
      "individual.verification.document",
      "individual.verification.selfie",
      "terms_acceptance.accepted_at",
      "terms_acceptance.ip"
    ],
    "pending_verification": []
  }
}
```

## O ciclo de correção

Reprovação não é fim de linha. Ela devolve os campos para `requirements.missing` e explica o motivo em `requirements.errors[]`, onde `requirement` aponta o caminho exato que falhou:

```json theme={"theme":"css-variables"}
{
  "id": "org_Tm6DzHLoHTme9y47",
  "object": "organization",
  "...": "demais campos do objeto organization",
  "activation_status": "disabled",
  "requirements": {
    "disabled_reason": null,
    "errors": [
      {
        "code": "identity_name_mismatch",
        "message": "The name provided does not match the name registered for the taxpayer id.",
        "requirement": "representative.verification.document",
        "resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
      }
    ],
    "missing": [
      "representative.first_name",
      "representative.last_name",
      "representative.verification.document"
    ],
    "pending_verification": []
  }
}
```

O ciclo é sempre o mesmo:

1. Mostre ao vendedor o que precisa mudar (use `resolution`, ou traduza a partir do `code`).
2. Regrave só os caminhos de `missing` com [`POST /v1/organizations/{id}`](/api-reference/organizations/update).
3. Chame `POST /v1/organizations/{id}/submit` de novo — mesma organização, mesmo `org_*`. Nada do que você construiu em cima dela se perde.

Campos de verificação que não aparecem em `missing` continuam válidos e não
precisam ser reenviados. Em `identity_document_mismatch`, por exemplo, faça o
upload de outro documento e envie um novo `verification.document`; omita
`verification.selfie` para manter a selfie atual. Se quiser substituí-la,
envie também um novo `file_*` em `verification.selfie`. O arquivo recusado não
é reaproveitado na nova análise.

**`disabled_reason` preenchido é terminal.** `"rejected.attempt_limit_reached"` significa limite de tentativas esgotado; `"rejected.other"` significa que não há caminho de autoatendimento. Nos dois casos, encaminhe ao suporte e não reenvie em loop.

Há também a **falha de envio**: quando o cadastro não chega a ser analisado (atividade econômica não suportada, arquivo apagado entre o envio e o processamento), a organização volta para `not_submitted`, `activation_submitted_at` volta para `null` e o motivo aparece em `requirements.errors`. Regravar qualquer bloco limpa esse erro.

A tabela de códigos, os caminhos apontados por cada um e todas as variações de payload estão em [Requisitos de ativação](/platforms/resolve-activation-rejections).

## Modo de teste

Com credencial de teste (`livemode: false`), o cadastro roda ponta a ponta sem tocar em nenhum documento real. O desfecho é **determinístico e escolhido pelo documento da organização** — o mesmo recurso dos cartões de teste:

| Documento da organização                       | Desfecho                      | O que você exercita                                          |
| ---------------------------------------------- | ----------------------------- | ------------------------------------------------------------ |
| `00000000000` (CPF) ou `00000000000000` (CNPJ) | Aprovado                      | `in_review` → `active`                                       |
| `11111111111` ou `11111111111111`              | Reprovado com correção        | `disabled` com `errors`, `missing` e `disabled_reason: null` |
| `22222222222` ou `22222222222222`              | Reprovado sem autoatendimento | `disabled` com `disabled_reason: "rejected.other"`           |
| Qualquer outro                                 | Fica em análise               | `in_review` indefinido                                       |

Os arquivos continuam sendo enviados de verdade por [`POST /v1/files`](/api-reference/files/create) (qualquer imagem válida serve) — o que muda é a análise, que responde pelo documento. Como os motivos de reprovação passam pelo mesmo tratamento da produção, você recebe os mesmos `code`, `message` e `resolution` que veria em uma conta real.

## O que não fazer

* **Não chame `/submit` a cada campo salvo.** Autossalve à vontade com `POST /v1/organizations/{id}`; envie uma vez, quando `missing` zerar. Depois de uma reprovação, cada reenvio consome uma das tentativas de reativação (atualmente 3).
* **Não crie outra organização porque o cadastro reprovou.** O reenvio é sempre no mesmo `org_*` — outra organização espalha o histórico do vendedor.
* **Não confie em `in_review` para liberar recebimentos.** Só `active` habilita a organização a receber.
* **Não monte a sua tela a partir de uma lista fixa de campos.** Use `requirements.missing`: ele é a fonte, e muda com o tipo de documento e com o que já foi preenchido.
* **Não guarde as fotos no seu servidor.** Suba direto por `POST /v1/files` e guarde apenas o `file_*`.
* **Não invente um quinto estado.** São quatro: `not_submitted`, `in_review`, `active`, `disabled`.

## Referências

* Contrato de escrita: [Atualizar organização](/api-reference/organizations/update) · [Enviar o cadastro](/api-reference/organizations/submit)
* Objeto e leitura: [`organization`](/api-reference/organizations/object) · [Consultar organização](/api-reference/organizations/get)
* Arquivos: [Criar arquivo](/api-reference/files/create)
* Arquivos aceitos: [Documentos de verificação aceitos](/help/identity-verification-documents)
* Resultado e pendências: [Requisitos de ativação](/platforms/resolve-activation-rejections) · [`organization.updated`](/api-reference/webhooks/organization.updated)
* Caminho hospedado: [Ativação hospedada](/platforms/activate-with-hosted-session)
* Contexto de plataforma: [Organizações conectadas](/platforms/connected-organizations) · [Reenviar KYC](/platforms/resubmit-organization-verification)