Contatos (Gestão e Deduplicação)

A gestão de contatos centraliza os dados de pessoas e empresas parceiras. A API permite gerenciar esse cadastro garantindo a integridade dos dados através de uma inteligência ativa de não-duplicação.

---

Endpoints Principais

1. Criar Contato (com Deduplicação Ativa)

Cria um novo contato na organização. O Perpetuus aplica regras automáticas para evitar duplicados: se o e-mail ou telefone enviado já existir na organização, o sistema rejeitará ou fará o merge conforme a configuração.

• Método: POST
• Caminho: /contacts
• Payload de Exemplo:

  {
    "data": {
      "name": "Lailton Santos",
      "email": "lailton@empresa.com",
      "phone": "+5511988887777",
      "customFields": {
        "cargo": "Gerente de TI",
        "setor": "Tecnologia"
      }
    }
  }

---

2. Listar Contatos

Retorna a lista paginada de contatos. Suporta ordenação e filtragem avançada (ex: buscar contatos criados no último mês).

• Método: GET
• Caminho: /contacts
• Exemplo de busca por e-mail:

  curl -G "https://api.perpetuus.com.br/api/contacts" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -H "x-tenant-id: acme" \
    --data-urlencode "filters[email][$eq]=lailton@empresa.com"

---

3. Cards Vinculados ao Contato

Retorna todos os cards de qualquer quadro que estejam associados a este contato. Útil para renderizar o histórico comercial completo no painel do cliente.

• Método: GET
• Caminho: /contacts/{id}/linked-cards

---

Operações em Massa (Bulk)

Para importação de grandes bases ou integrações com sistemas legados, utilize os endpoints em massa. Eles processam requisições de forma otimizada para evitar limites de timeout.

1. Criação/Edição em Lote

• Método: POST
• Caminho: /contacts/bulk
• Payload:

  {
    "contacts": [
      {
        "name": "Maria Silva",
        "email": "maria@empresa.com",
        "phone": "+5511977776666"
      },
      {
        "name": "Carlos Souza",
        "email": "carlos@empresa.com"
      }
    ]
  }

2. Exclusão em Lote

• Método: POST
• Caminho: /contacts/bulk-delete
• Payload:

  {
    "documentIds": ["contact_doc_id_1", "contact_doc_id_2"]
  }