> ## 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.

# Mudanças na integração de ativação

> Checklist das mudanças públicas do fluxo de ativação hospedado e por API para revisar uma integração existente.

Esta página reúne o contrato público atual da ativação de organizações. Use-a
para revisar uma integração existente, tanto no fluxo hospedado quanto no fluxo
por API. As mudanças abaixo valem desde **11 de agosto de 2026**.

<Info>
  O identificador da organização não muda durante uma correção. Preserve o mesmo
  `org_*`, corrija somente os requisitos indicados e inicie uma nova tentativa
  pelo canal escolhido.
</Info>

## O que mudou

| Área                               | Contrato atual                                                                                                                             | Ajuste esperado do parceiro                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Resultado de uma tentativa por API | Uma falha terminal antes da análise devolve a organização a `not_submitted` e preenche `requirements.errors` e `requirements.missing`.     | Trate `not_submitted` também como resultado de uma tentativa anterior, não apenas como cadastro nunca enviado. |
| Webhook                            | A transição terminal por API gera `organization.updated`, com os valores anteriores em `data.previous_attributes`.                         | Consuma a mudança `in_review` → `not_submitted` e apresente os requisitos que precisam ser corrigidos.         |
| Nova tentativa                     | No hospedado, crie uma nova `activation_session`. Por API, atualize os requisitos indicados e chame `/submit` novamente.                   | Não obrigue o usuário a abrir o fluxo hospedado quando a integração usa a API.                                 |
| Documento de identidade            | São aceitos CNH, RG, CREF, CIN e passaporte, nas variantes físicas ou digitais descritas na matriz.                                        | Envie exatamente a quantidade e o lado de arquivo exigidos para a variante escolhida.                          |
| Upload e exclusão                  | Imagens podem ter até **20 MB** e são normalizadas; PDFs podem ter até **5 MB**. Excluir um arquivo vinculado responde `409 file_in_use`.  | Valide o limite pelo tipo; para excluir, substitua primeiro a referência no cadastro.                          |
| Motivo de bloqueio                 | O campo público é `requirements.disabled_reason`.                                                                                          | Remova qualquer leitura do nome anterior e use somente `disabled_reason`.                                      |
| Erro sem nova tentativa hospedada  | Criar uma `activation_session` quando não há caminho de autoatendimento responde `409 activation_not_retryable`.                           | Não repita automaticamente; releia a organização e encaminhe o caso ao suporte.                                |
| MCP                                | O catálogo possui 61 operações. Ele orienta o fluxo e lê organizações filhas (`organizations.list` e `organizations.get`), sem alterá-las. | Para criar, atualizar e ativar organizações filhas, continue usando a API pública e `organization.updated`.    |

## Falha terminal antes da análise

No fluxo por API, o envio começa em `in_review`. Se a Chargefy não conseguir
concluir o envio para análise e a tentativa não puder mais ser retomada, a
organização volta para `not_submitted`. O evento informa tanto o estado atual
quanto o anterior. O recorte abaixo destaca somente os campos relevantes da
organização:

```json theme={"theme":"css-variables"}
{
  "id": "evt_Tm6DzHLoHTme9y47",
  "object": "event",
  "created_at": "2026-08-11T15:04:05Z",
  "data": {
    "object": {
      "id": "org_Tm6DzHLoHTme9y47",
      "object": "organization",
      "...": "demais campos da organization",
      "activation_status": "not_submitted",
      "requirements": {
        "disabled_reason": null,
        "errors": [
          {
            "code": "identity_document_verification_failed",
            "message": "The identity document could not be verified.",
            "requirement": "representative.verification.document",
            "resolution": "Ask the account holder to replace the indicated document with a clear, valid and unexpired identity document — a well-lit photo showing the whole document, with readable text — then start a new activation attempt."
          }
        ],
        "missing": [
          "representative.verification.document"
        ],
        "pending_verification": []
      }
    },
    "previous_attributes": {
      "activation_status": "in_review",
      "requirements": {
        "disabled_reason": null,
        "errors": [],
        "missing": [],
        "pending_verification": [
          "representative.verification.document"
        ]
      }
    }
  },
  "livemode": true,
  "organization": "org_Tm6DzHLoHTme9y47",
  "request": {
    "id": null
  },
  "type": "organization.updated"
}
```

<Warning>
  A entrega de webhooks é *at least once*. Deduplique por `event.id`, aceite
  repetições e use o objeto atual como fonte da verdade.
</Warning>

## Como corrigir e tentar novamente

<Tabs>
  <Tab title="Fluxo hospedado">
    Releia `requirements`, explique ao vendedor o que precisa ser substituído e
    crie uma nova
    [`activation_session`](/api-reference/activation-sessions/create). A sessão
    anterior não é reaberta.
  </Tab>

  <Tab title="Fluxo por API">
    Releia `requirements.missing`, atualize somente os campos e arquivos
    indicados com `POST /v1/organizations/{id}` e, quando `missing` estiver
    vazio, chame `POST /v1/organizations/{id}/submit` novamente.
  </Tab>
</Tabs>

Se a criação da sessão hospedada responder `409 activation_not_retryable`, não
crie outra organização e não faça retry automático. Releia a organização e
encaminhe o caso ao suporte: o estado atual não permite autoatendimento.

## Arquivos de identidade

Consulte a [matriz de documentos de verificação](/help/identity-verification-documents)
antes de montar o upload. Ela especifica, por documento, quando o parceiro deve
enviar um único arquivo completo, frente e verso separados ou o arquivo digital
oficial. A [ativação por API](/platforms/activate-by-api) traz exemplos completos
para todas as variantes aceitas.

Cada arquivo:

* pode ser uma imagem de até **20 MB** (normalizada automaticamente) ou um PDF de até **5 MB**;
* precisa ser enviado para a organização correta;
* não pode ser excluído enquanto estiver vinculado ao documento ou à selfie;
* deve ter sua referência substituída antes da exclusão quando a API responder
  `409 file_in_use`.

## Checklist de validação

* O webhook trata `active`, `disabled`, `in_review` e `not_submitted`.
* Uma transição `in_review` → `not_submitted` abre a correção, sem criar outro `org_*`.
* O retry respeita o canal: nova sessão no hospedado; update + submit na API.
* O formulário oferece CNH, RG, CREF, CIN e passaporte conforme a matriz.
* O frontend aceita imagens até 20 MB e mantém PDFs limitados a 5 MB.
* A integração lê `requirements.disabled_reason`.
* `activation_not_retryable` e `file_in_use` não entram em retry automático.
* O evento é deduplicado por `event.id`.

Para o estado completo e os payloads de cada fase, leia
[Entender requisitos e corrigir a ativação](/platforms/resolve-activation-rejections) e
[`organization.updated`](/api-reference/webhooks/organization.updated).