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

# Update an Organization

> Atualiza uma organização.

Atualiza campos públicos da organização. A operação tem semântica de merge: apenas os campos enviados são modificados.

`bank_account`, `platform`, `activation_status`, `activation_status_updated_at`, `created_at` e `updated_at` são somente leitura neste endpoint.

`document` e `document_type` podem ser alterados apenas enquanto a organização ainda não tem identidade financeira viva: a ativação precisa estar em `activation_pending` ou `disabled` e a organização não pode ter nenhuma atividade de pagamento. Depois da primeira ativação ou movimentação, o documento identifica o histórico financeiro e se torna permanente. Veja o modelo completo em [Reenviar KYC de uma organização](/guides/platform-organization-rekyc).

## Autenticação

| Credencial                                  | Acesso                                                                                        |
| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| JWT de usuário                              | Requer acesso à organização.                                                                  |
| API key da organização (`write` ou `admin`) | Apenas a própria organização da key.                                                          |
| API key da plataforma (`platform_admin`)    | Organizações conectadas ativas da plataforma. Também permite atualizar `metadata` da relação. |

## Parâmetros de caminho

<ParamField path="id" type="string" required>
  ID da organização.
</ParamField>

## Attributes

<ParamField body="avatar_url" type="string">
  URL de file da Chargefy (`https://storage.chargefy.io/file_...`) com purpose
  `organization_avatar`, criada via [`POST /v1/files`](/api-reference/files/create)
  e pertencente à própria organização. URLs externas são rejeitadas com `400`.
  Use `null` para limpar.
</ParamField>

<ParamField body="billing_additional_info" type="string">
  Informação adicional de cobrança. Use `null` para limpar.
</ParamField>

<ParamField body="billing_address" type="object">
  Endereço de cobrança. Use `null` para limpar.
</ParamField>

<ParamField body="billing_name" type="string">
  Nome usado em cobranças. Use `null` para limpar.
</ParamField>

<ParamField body="branding_settings" type="object">
  Identidade visual aplicada ao checkout hospedado da organização. Merge por campo: cada campo enviado é atualizado, os demais permanecem. Use `null` em um campo para limpá-lo (volta ao padrão do sistema).

  <Expandable title="Campos de branding_settings">
    <ParamField body="accent_color" type="string">Cor de destaque (botão/foco), hex `#RGB` ou `#RRGGBB`.</ParamField>
    <ParamField body="border_style" type="string">`pill`, `rounded` ou `sharp`.</ParamField>
    <ParamField body="brand_color" type="string">Cor de marca (painel/cabeçalho), hex `#RGB` ou `#RRGGBB`.</ParamField>
    <ParamField body="font_family" type="string">`system`, `inter`, `geist` ou `bitter`.</ParamField>
    <ParamField body="theme" type="string">`light` ou `dark`.</ParamField>
  </Expandable>

  Estes defaults valem para todas as checkout sessions da organização; cada sessão pode sobrescrever campos pontualmente. A cópia do botão (`submit_type`) **não** mora aqui — é definida por sessão.
</ParamField>

<ParamField body="document" type="string">
  Novo CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. O documento é a identidade fiscal **declarada** da organização: ele define qual perfil financeiro a próxima onboarding session vai criar (pessoa física para CPF, pessoa jurídica para CNPJ).

  Só pode ser alterado enquanto `activation_status` é `activation_pending` ou `disabled` e a organização não tem atividade de pagamento. A troca desativa o perfil financeiro reprovado anterior (se houver) e reinicia qualquer onboarding session aberta — chame [`POST /v1/onboarding-sessions`](/api-reference/onboarding-sessions/create) novamente após a troca.
</ParamField>

<ParamField body="document_type" type="string">
  `cpf` ou `cnpj`. Opcional: quando omitido, é derivado do `document`. Quando enviado, precisa ser coerente com o número informado. Não pode ser enviado sem `document`.
</ParamField>

<ParamField body="email" type="string">
  E-mail principal. Use `null` para limpar.
</ParamField>

<ParamField body="metadata" type="object">
  Substitui a metadata da relação plataforma↔organização conectada. Disponível apenas com API key de plataforma.
</ParamField>

<ParamField body="name" type="string">
  Nome público da organização. Não aceita string vazia.
</ParamField>

<ParamField body="socials" type="array">
  Substitui a lista inteira de redes sociais. Use `[]` para limpar.
</ParamField>

<ParamField body="website" type="string">
  Site público. Use `null` para limpar.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/organizations/org_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "branding_settings": {
        "accent_color": "#FF6B00",
        "border_style": "rounded",
        "brand_color": "#1B1B1B",
        "theme": "light"
      },
      "email": "financeiro@meusite.com",
      "metadata": {
        "external_account_id": "acct_987"
      },
      "name": "Acme Brasil Ltda"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `organization` completo e já atualizado. A resposta direta não inclui diff.

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "org_123",
    "object": "organization",
    "activation_status": "activation_pending",
    "activation_status_updated_at": null,
    "avatar_url": null,
    "bank_account": null,
    "billing_additional_info": null,
    "billing_address": null,
    "billing_name": null,
    "branding_settings": {
      "accent_color": "#FF6B00",
      "border_style": "rounded",
      "brand_color": "#1B1B1B",
      "font_family": null,
      "theme": "light"
    },
    "created_at": "2026-05-16T14:09:27Z",
    "document": "12345678000190",
    "document_type": "cnpj",
    "email": "financeiro@meusite.com",
    "livemode": true,
    "metadata": {
      "external_account_id": "acct_987"
    },
    "name": "Acme Brasil Ltda",
    "platform": "plat_456",
    "socials": [],
    "updated_at": "2026-05-16T14:35:00Z",
    "website": "https://meusite.com"
  }
  ```
</ResponseExample>

## Erros de troca de documento

| HTTP  | `code`                              | Situação                                                                                                             |
| ----- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request`                   | `document` inválido, ou `document_type` incoerente com o número enviado.                                             |
| `409` | `organization_already_active`       | A organização já está ativa. O documento identifica o histórico financeiro e não pode mais ser trocado.              |
| `409` | `organization_activation_pending`   | Existe uma análise de ativação em andamento. Aguarde o resultado (`organization.updated`) antes de trocar.           |
| `409` | `organization_has_payment_activity` | A organização já tem atividade de pagamento; o documento é permanente.                                               |
| `409` | `document_already_in_use`           | Outra organização conectada da mesma plataforma já usa esse documento. Use a organização existente em vez de trocar. |

## Webhook

Quando a chamada altera campos visíveis para uma plataforma conectada, a Chargefy emite `organization.updated` para os endpoints da organização da plataforma.

`data.object` contém o snapshot completo atualizado. `data.previous_attributes` contém apenas os campos alterados e seus valores anteriores. Em uma troca de documento:

```json theme={}
{
  "data": {
    "object": {
      "id": "org_123",
      "object": "organization",
      "activation_status": "disabled",
      "document": "12345678901",
      "document_type": "cpf"
    },
    "previous_attributes": {
      "document": "12345678000190",
      "document_type": "cnpj"
    }
  },
  "type": "organization.updated"
}
```