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

# Create an Organization

> Cria uma organização conectada.

Cria uma organização conectada para a sua plataforma e devolve o objeto
`organization` completo. O identificador retornado em `id` é o valor que você
usa depois no header `Organization` para criar produtos, preços, checkout
sessions, payment links, invoices e subscriptions em nome dessa organização.

Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma retornam a
organização já existente. O create não substitui campos de perfil de uma
organização existente; use [`POST /v1/organizations/{id}`](/api-reference/organizations/update)
para atualizar nome, email, branding ou metadata depois da criação.

## Autenticação

Requer API key de plataforma com escopo `platform_admin`.

O header `Organization` não é aceito neste endpoint, porque a organização ainda
está sendo criada.

## Attributes

<ParamField body="document" type="string" required>
  CPF ou CNPJ da organização conectada. Máscaras são aceitas e normalizadas para
  somente dígitos. Este campo é a chave de idempotência dentro da plataforma.
</ParamField>

<ParamField body="document_type" type="string">
  `cpf` ou `cnpj`. Quando omitido, inferimos pelo comprimento de `document`. Se
  enviado, deve bater com a quantidade de dígitos de `document`.
</ParamField>

<ParamField body="name" type="string" required>
  Nome público inicial da organização conectada.
</ParamField>

<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).
  URLs externas são rejeitadas com `400`. O file precisa pertencer à própria
  organização conectada, então o fluxo típico é criar a organização primeiro,
  subir o file com o header `Organization` e definir o avatar via
  [update](/api-reference/organizations/update). Use `null` ou omita para vazio.
</ParamField>

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

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

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

<ParamField body="branding_settings" type="object">
  Identidade visual inicial aplicada ao checkout hospedado da organização.

  <Expandable title="Campos de branding_settings">
    <ParamField body="accent_color" type="string">Cor de destaque, 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, 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>
</ParamField>

<ParamField body="email" type="string">
  E-mail principal da organização. Use `null` ou omita para vazio.
</ParamField>

<ParamField body="metadata" type="object">
  Mapa opcional `string → string` com até 50 chaves. A Chargefy só armazena e
  ecoa este objeto; use as chaves que fizerem sentido para o seu sistema.
  Chaves: `[a-zA-Z0-9_\-.]{1,40}`. Valores: até 500 caracteres.
</ParamField>

<ParamField body="socials" type="array">
  Lista de redes sociais no formato `{ platform, url }`. `platform`: `x`,
  `github`, `facebook`, `instagram`, `youtube`, `linkedin` ou `other`.
</ParamField>

<ParamField body="website" type="string">
  Site público da organização. Use `null` ou omita para vazio.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  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 Ltda"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `organization` completo. Campos declarados nunca são
omitidos; vazio vem como `null`, `{}` ou `[]`.

<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": null,
      "border_style": null,
      "brand_color": null,
      "font_family": null,
      "theme": null
    },
    "created_at": "2026-05-16T14:09:27Z",
    "document": "12345678000190",
    "document_type": "cnpj",
    "email": "contato@meusite.com",
    "livemode": true,
    "metadata": {},
    "name": "Acme Ltda",
    "platform": "plat_456",
    "socials": [],
    "updated_at": "2026-05-16T14:09:27Z",
    "website": "https://meusite.com"
  }
  ```
</ResponseExample>

## Erros

| Status | Quando                                                                                               |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | Payload inválido (`document`, `document_type`, `name`, `metadata`) ou header `Organization` enviado. |
| `401`  | API key ausente, inválida, revogada ou expirada.                                                     |
| `403`  | Credencial não é uma API key de plataforma.                                                          |
| `409`  | Plataforma inativa ou setup da plataforma incompleto.                                                |
| `503`  | Erro temporário resolvendo a organização. Faça retry.                                                |

## Próximos passos

Depois de criar a organização, use o `id` retornado como header
`Organization` nos endpoints que criam recursos em nome dela.

Se a organização precisar completar cadastro financeiro, crie uma
[`onboarding_session`](/api-reference/onboarding-sessions/create) usando o `id`
retornado. Ela devolve a URL hospedada para o vendedor concluir o fluxo.