**Para gerenciar atributos personalizados dos contatos de forma programática, utilize a API REST da [Papo](https://papo.global/). Com autenticação por chave secreta, você pode listar definições de atributos, criar novos campos customizados e definir ou mesclar valores nos contatos — ideal para sincronizar dados de CRMs externos, enriquecer perfis e refinar a segmentação de campanhas e automações sem intervenção manual.**

A API da Papo expõe recursos específicos para atributos customizados, permitindo que sua operação mantenha uma base de contatos sempre atualizada com informações relevantes do negócio. Seja para importar dados de um ERP, migrar listas de um CRM legado ou automatizar a classificação de leads, esses endpoints funcionam com a mesma autenticação simples dos demais recursos da plataforma.

## Resumo do processo de integração

| Etapa | Ação | Detalhe importante |
| :--- | :--- | :--- |
| 1. Obter as chaves | Gerar a chave secreta (sk_live_…) e copiar a chave pública (pk_live_…) no painel da Papo. | A chave secreta aparece uma única vez; guarde‑a em local seguro. |
| 2. Autenticar as chamadas | Incluir o header `Authorization: Bearer sk_live_…` em todas as requisições de escrita. | A chave pública pode ser enviada no header `X-Papo-Public-Key` (opcional). |
| 3. Gerenciar definições | Listar os atributos existentes ou criar um novo (com chave, nome de exibição e modelo). | Consulte a documentação oficial para os paths e payloads exatos. |
| 4. Atualizar contatos | Enviar requisição para mesclar os `custom_attributes` no contato desejado. | Pode-se atualizar um ou vários atributos de uma vez, em lote via scripts. |
| 5. Verificar as respostas | A API retorna `success: true` e os dados atualizados. | Em caso de erro, o corpo traz o código e a mensagem para correção. |

## Como funciona: passo a passo

### 1. Autenticação e chaves
Toda chamada que modifica dados exige a **chave secreta** da conta, enviada como token Bearer no header `Authorization`. A **chave pública** (fixa por conta) pode acompanhar a requisição no header `X-Papo-Public-Key` — seu uso é opcional, mas se enviada precisa corresponder à mesma conta da chave secreta. A URL base da API é `https://app.papo.global/api/v1`. As chaves são geradas na área de desenvolvedor do painel da Papo.

### 2. Gerenciar as definições de atributos
Antes de popular valores, é necessário que a definição do atributo exista na conta. A API permite:
- **Listar** todos os atributos personalizados já cadastrados, para auditar a padronização ou mapear campos antes de uma integração.
- **Criar** uma nova definição, informando:
  - `attribute_key` — identificador único (ex.: `plano`, `cidade`).
  - `attribute_display_name` — nome legível que aparece no CRM (ex.: “Plano Contratado”).
  - `attribute_model` — tipo do campo: texto, número, data ou lista (com opções pré-definidas).

Essas operações são essenciais para preparar a estrutura que receberá os dados vindos de sistemas externos.

### 3. Definir e atualizar valores nos contatos
Com as definições prontas, você pode enviar requisições para **mesclar os `custom_attributes`** em um contato específico. O payload inclui um objeto chave-valor com os atributos que deseja atualizar. Por exemplo, para definir o plano “Pro” e a cidade “São Paulo” em um contato, o JSON conteria algo como `{"plano": "Pro", "cidade": "São Paulo"}`. A API processa um contato por requisição, mas a operação em massa é alcançada executando múltiplas chamadas em sequência — com scripts em Python, Node.js ou automações no n8n.

### 4. Sincronização com CRM externo (caso de uso típico)
Um script pode:
1. Ler registros de um CRM externo, ERP ou banco de dados.
2. Para cada registro, mapear os campos de interesse para as `attribute_key` correspondentes na Papo.
3. Se necessário, criar a definição do atributo (caso ainda não exista).
4. Enviar a requisição de atualização do contato (identificado por ID, e-mail ou telefone) com os `custom_attributes`.
5. Coletar as respostas e tratar eventuais erros (campo inválido, chave inexistente etc.).

Assim, a base da Papo permanece espelho fiel dos dados do seu ecossistema, pronta para segmentações e automações.

### 5. Impacto nas automações e campanhas
Depois que os atributos estão populados, eles ficam disponíveis imediatamente para:
- **Flows** com condição baseada em atributo do contato (ex.: enviar uma mensagem específica para quem tem `plano` igual a “Enterprise”).
- **Segmentos** dinâmicos para campanhas de WhatsApp ou e-mail marketing.
- **Relatórios** e filtros no CRM, permitindo que os times visualizem e priorizem contatos com base em qualquer campo customizado.

## Para quem essa integração é indicada

- **Empresas que usam múltiplos sistemas** (CRM, ERP, e-commerce) e precisam centralizar informações de clientes na Papo sem digitação manual.
- **Operações que migram de outra plataforma** e desejam importar não só os contatos, mas também campos customizados como “fonte da lead”, “score” ou “última compra”.
- **Times de marketing e vendas** que segmentam campanhas com base em dados estruturados (plano, região, interesse) e precisam que esses dados estejam sempre atualizados.
- **Revendas white label** que personalizam atributos para cada cliente final e querem automatizar a sincronização a partir dos sistemas dos próprios clientes.

## Perguntas frequentes

### Preciso criar o atributo antes de definir o valor no contato?
Sim. A definição do atributo (com `attribute_key`, nome e modelo) precisa existir na conta. Você pode criá-la via API ou pelo painel em **Configurações → Atributos Personalizados**.

### Quais tipos de atributos posso criar via API?
A API suporta os mesmos tipos disponíveis no painel: texto, número, data e lista (com opções pré-definidas). O modelo é informado no campo `attribute_model` ao criar a definição.

### Como atualizar vários contatos de uma vez?
A API processa um contato por requisição. Para operações em massa, automatize o envio em lote com scripts (Python, Node.js) ou ferramentas como n8n, iterando sobre uma lista de contatos e enviando as requisições sequencialmente.

### Onde encontro os endpoints exatos e o formato do payload?
Na documentação oficial da API, disponível em `https://papo.global/pt/docs`. Lá estão detalhados os endpoints de atributos customizados, autenticação e exemplos de código.

### Posso usar a API para limpar ou remover um atributo de um contato?
A documentação da API descreve as operações disponíveis. Para casos de remoção ou limpeza, consulte a referência oficial para verificar se há endpoints específicos ou se é necessário redefinir o valor.

### Os atributos atualizados via API disparam automações?
Sim. A atualização de um contato via API pode disparar eventos internos, como a execução de Flows configurados com gatilhos relacionados a alterações no contato, desde que as condições sejam atendidas.

## Leia também

- [Como usar a API da Papo para criar e atualizar contatos em massa](/hc/papo/articles/usar-api-papo-criar-atualizar-contatos-massa)
- [Como usar a API da Papo para criar e gerenciar etiquetas (tags)](/hc/papo/articles/como-usar-api-papo-criar-gerenciar-etiquetas-tags)

---

**[Comece grátis e integre seus dados →](https://papo.global/?utm_source=helpcenter&utm_medium=article&utm_campaign=como-usar-api-papo-gerenciar-atributos-personalizados-contatos&utm_content=pt_BR)**

Com a API da Papo, você sincroniza atributos personalizados em massa e refina a segmentação de campanhas sem sair do seu fluxo de trabalho.