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

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.

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.

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:

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

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

Como corrigir e tentar novamente

Fluxo hospedado
Fluxo por API

Releia requirements, explique ao vendedor o que precisa ser substituído e crie uma nova activation_session. A sessão anterior não é reaberta.

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.

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 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 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 e organization.updated.

Visão geral

Ativação de organizações

Modelo de negócio

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

O que mudou

Falha terminal antes da análise

Como corrigir e tentar novamente

Arquivos de identidade

Checklist de validação

​O que mudou

​Falha terminal antes da análise

​Como corrigir e tentar novamente

​Arquivos de identidade

​Checklist de validação

O que mudou

Falha terminal antes da análise

Como corrigir e tentar novamente

Arquivos de identidade

Checklist de validação