# Cadastros, campos e arquivos pela API

## Cadastros

| Recurso               | Coleção                 | Operações individuais                      |
| --------------------- | ----------------------- | ------------------------------------------ |
| Contatos              | `/api/v1/contacts`      | Consultar, editar e excluir por ID.        |
| Empresas              | `/api/v1/companies`     | Consultar, editar e excluir por sequência. |
| Tags                  | `/api/v1/tags`          | Consultar, editar e excluir por ID.        |
| Campos personalizados | `/api/v1/custom-fields` | Consultar, editar e excluir por ID.        |
| Membros               | `/api/v1/users`         | Catálogo de membros; não cria contas.      |

Cada recurso tem permissões e limites próprios. Consulte método, corpo e retorno na [referência](/api/). Excluir um contato não é uma operação reversível; revise os vínculos antes de executar.

## Nome do contato

Envie `firstName` e `lastName` separadamente. Nas operações de criação de negócio, as chaves equivalentes são `contactFirstName` e `contactLastName`. Use os nomes retornados pelo servidor ao sincronizar cadastros.

## Definição e valor do campo

A definição estabelece tipo, opções, grupo, placeholder e regra de visibilidade. Seu `id` identifica o campo; o `slug` identifica o valor dentro de `customFields` e `properties` do negócio.

Em seleções, envie o **valor** da opção, não seu rótulo. Um campo com `apiOnly: true` permite atualizar seus valores pela API pública e os mantém somente para leitura no aplicativo.

Uma `visibilityRule` usa `parentFieldId` e `values`. Para removê-la no PATCH, envie `clearVisibilityRule: true`. Não combine com `visibilityRule` na mesma requisição: o servidor responde `422`.

## Arquivos

O upload de um campo de arquivo usa `multipart/form-data`, com o campo `file`. Não envie um caminho local como texto em JSON. Consulte as operações de arquivos em [Campos personalizados](/api/#resource-custom-fields).

Para obter o arquivo vinculado ao negócio, use `GET /api/v1/deals/{seq}/properties/{slug}/file`. A URL assinada dessa rota vale por 24 horas. Para resolver uma chave de armazenamento separadamente, use `GET /api/v1/custom-fields/file?key=…`; a URL dessa operação vale por uma hora. Guarde a referência do arquivo e solicite uma URL nova quando a anterior vencer.