> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar campo personalizado ## OpenAPI ````yaml /api-reference/openapi.yaml post /custom-fields openapi: 3.0.3 info: title: Connecta DESK API pública version: 1.0.0 description: > API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com um token gerado no módulo de tokens. Cada token tem permissões por **módulo × método**, e toda leitura de lista é paginada. ## Autenticação ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` O token pertence a uma **empresa**, e não a um usuário. A empresa usada é sempre a do token, então enviar `companyId` no corpo não tem efeito. Token ausente, inválido, revogado ou expirado recebe a mesma resposta `401`. ## Ordem de verificação 1. **token** → `401` 2. **empresa ativa** → `403` 3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a on-premise) 4. **rate limit da empresa** → `429` 5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE` ## Ids de usuário Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que `GET /users` devolve. Vale para o que a API responde (`user.id`, `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`, `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário). A mesma pessoa pode trabalhar em várias empresas, com nome e perfil diferentes em cada uma, e tem um id diferente em cada empresa. Um id que não pertence a esta empresa responde `404`, com a mesma mensagem de um id inexistente. ## Paginação Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e `hasMore`, sem o total de registros. Para percorrer tudo, avance `page` enquanto `hasMore` for `true`. ## Idempotência Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a resposta é `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Produção security: - apiToken: [] tags: - name: contacts description: Cadastro de contatos, campos extras e origem de marketing. - name: tickets x-displayName: Conversas description: Abertura, transferência, encerramento e qualificação de conversas. - name: messages description: Envio assíncrono e leitura de mensagens. - name: tags description: Tags e vínculo com atendimentos. - name: queues description: Filas de atendimento e seus atendentes. - name: wrapups description: Tipos de qualificação. - name: users description: Atendentes e administradores. - name: schedules description: Mensagens programadas. - name: quick-messages description: Respostas rápidas. - name: campaigns description: Disparos em massa. - name: crm description: Painéis, etapas, cards e indicadores. - name: channels description: Canais (somente leitura). - name: reports description: Relatórios e dashboards. - name: products description: Catálogo de produtos, categorias e desempenho nas vendas. - name: custom-fields description: >- Campos personalizados de contato e de card, e variáveis globais da empresa. - name: profiles description: Perfis de permissões da empresa (somente leitura). - name: webchat description: >- Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e ler mensagens. O token precisa do escopo `webchat` (GET e POST). paths: /custom-fields: post: tags: - custom-fields summary: Criar campo personalizado parameters: - $ref: '#/components/parameters/idempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomFieldInput' responses: '201': description: Criado content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CustomField' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: idempotencyKey: name: Idempotency-Key in: header description: >- Chave única da operação. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada. schema: type: string maxLength: 200 example: pedido-88213-confirmacao schemas: CustomFieldInput: type: object required: - name - application - type properties: name: type: string maxLength: 60 description: Nome exibido. example: Plano key: type: string maxLength: 40 description: >- Se você não informar, a chave é gerada a partir do nome, em `minusculas_com_underline`. example: plano description: type: string nullable: true maxLength: 120 description: Descrição do campo personalizado. application: type: string enum: - contact - card description: >- Onde o campo se aplica: `contact` em contatos, `card` em cards do CRM. type: type: string enum: - text - number - currency - date - select - boolean - email - phone - link - textarea description: | Tipo de valor aceito. Ele define a validação feita a cada gravação: | valor | aceita | | --- | --- | | `text` | Texto curto, de uma linha. | | `number` | Número. | | `currency` | Valor monetário. | | `date` | Data. | | `select` | Uma das opções cadastradas no próprio campo. | | `boolean` | Sim ou não. | | `email` | E-mail, com o formato validado. | | `phone` | Telefone. | | `link` | URL. | | `textarea` | Texto longo, de várias linhas. | groupName: type: string nullable: true description: Grupo do campo no formulário. Campos do mesmo grupo aparecem juntos. example: Comercial isPublic: type: boolean default: true description: >- Deixa o campo visível para todos os atendentes. Quando falso, só quem tem permissão vê o campo. alwaysVisible: type: boolean default: false description: Mostra o campo na ficha mesmo sem valor preenchido. options: type: array description: Lista de opções. Obrigatória quando `type` é `select`. items: type: object required: - name properties: name: type: string maxLength: 40 description: Nome exibido. example: Plano color: type: string nullable: true description: Cor em hexadecimal, com `#`. example: '#6941C6' CustomField: type: object properties: id: type: integer key: type: string description: >- Identificador usado nos fluxos e mensagens, como em `{{tipo_de_cliente}}`. example: tipo_de_cliente name: type: string description: Nome exibido. example: Plano description: type: string nullable: true description: Descrição do campo personalizado. application: type: string enum: - contact - card description: >- Onde o campo se aplica: `contact` em contatos, `card` em cards do CRM. type: type: string enum: - text - number - currency - date - select - boolean - email - phone - link - textarea description: | Tipo de valor aceito. Ele define a validação feita a cada gravação: | valor | aceita | | --- | --- | | `text` | Texto curto, de uma linha. | | `number` | Número. | | `currency` | Valor monetário. | | `date` | Data. | | `select` | Uma das opções cadastradas no próprio campo. | | `boolean` | Sim ou não. | | `email` | E-mail, com o formato validado. | | `phone` | Telefone. | | `link` | URL. | | `textarea` | Texto longo, de várias linhas. | groupName: type: string nullable: true description: Grupo do campo no formulário. Campos do mesmo grupo aparecem juntos. example: Comercial isPublic: type: boolean description: Quando falso, o campo fica visível só para quem tem permissão. alwaysVisible: type: boolean description: Mostra o campo na ficha mesmo quando ele não tem valor. isSystem: type: boolean description: >- Campo do sistema. A chave, a aplicação e o tipo não podem ser alterados, e o campo não pode ser excluído. order: type: integer example: desc options: type: array description: Lista de opções. Presente quando `type` é `select`. items: $ref: '#/components/schemas/CustomFieldOption' createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 44 key: tipo_de_cliente name: Tipo de cliente description: Classificação comercial usada na régua de atendimento. application: contact type: select groupName: Comercial isPublic: true alwaysVisible: true isSystem: false order: 2 options: - id: 91 name: Varejo color: '#0E7490' order: 0 - id: 92 name: Atacado color: '#6941C6' order: 1 createdAt: '2026-06-09T09:30:00.000Z' updatedAt: '2026-08-14T16:05:00.000Z' CustomFieldOption: type: object properties: id: type: integer name: type: string description: Nome exibido. color: type: string nullable: true description: Cor em hexadecimal, com `#`. example: '#6941C6' order: type: integer example: desc Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Código fixo do erro, para você tratar cada caso no seu sistema. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} responses: BadRequest: description: Corpo da requisição inválido. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: O campo `number` é obrigatório. Unauthorized: description: Token ausente, inválido, revogado ou expirado. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_UNAUTHORIZED message: Token de API ausente ou inválido. Forbidden: description: Empresa inativa, API não habilitada no plano ou permissão insuficiente. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_FORBIDDEN_SCOPE message: >- O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois. Conflict: description: Conflito de `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_IDEMPOTENCY_KEY_REUSED message: Idempotency-Key já usada com um corpo diferente. UnprocessableEntity: description: >- O corpo está bem formado, mas falta um campo obrigatório ou algum valor não é aceito. Por exemplo, `application` diferente de `contact`/`card`, `orderedIds` vazio ou `name` em branco. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: >- O parâmetro `application` é obrigatório e aceita "contact" ou "card". securitySchemes: apiToken: type: http scheme: bearer description: Token da API no formato `sk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.