Contas e parceiros

Em logística, seguros, saúde e B2B em geral, o cliente muitas vezes é uma empresa, e quem fala é uma pessoa que age em nome dela: o motorista da transportadora, o comprador da rede, o corretor. Há ainda organizações que participam do atendimento sem ser clientes: a transportadora que entrega, a clínica que atende, a assistência que conserta. A Niadra guarda memória para todos. O sujeito da memória é uma pessoa, uma conta ou um parceiro.

Três tipos de sujeito

Tipo	O que é	Exemplo
`person`	Uma pessoa, reconhecida por telefone, e-mail, id do WhatsApp, id do app ou id de sistema	Marina Souza
`account`	Uma organização que é sua cliente	A rede varejista da conta `ACC-2201` no CRM
`partner`	Uma organização que participa do atendimento sem ser cliente	A transportadora, a clínica, a corretora

O tipo vem dos handles, nunca de um parâmetro à parte. Todo handle tem subject_kind, que por padrão é person, exceto nos tipos de handle que só existem para organização.

Handles de organização

Tipo de handle	Força	Observação
`org_registry_hmac`	Forte	O registro da empresa no país dela, enviado como HMAC com o seu segredo, igual ao documento de uma pessoa
`system_id` com `subject_kind: account` ou `partner`	Forte dentro do namespace	A conta no seu CRM, o código do cliente no ERP, o id da transportadora no TMS
`email_domain`	Pista fraca	Nunca une nada sozinho; domínios de webmail ficam bloqueados
Telefone da empresa	Ambíguo por padrão	Um PABX liga muita gente ao mesmo número

Organizações nunca se unem automaticamente e nunca são deduplicadas por semelhança de nome. Só id liga organizações. Existe um nível de hierarquia: subsidiárias viram contas irmãs sob o mesmo parent_org.

Pessoa e organização se ligam, nunca se unem

Uma asserção entre handle de pessoa e handle de organização é recusada. O que liga as duas é um vínculo, com papel (buyer, technical_contact, driver, broker), validade, origem e confiança. Uma pessoa pode ter vários vínculos ao mesmo tempo: o motorista que roda para três transportadoras tem três vínculos. Vínculos nascem de quatro métodos: system_import (o registro de contato do CRM), co_occurrence (um evento que traz os dois ids), declared (“ligo em nome da transportadora X”, fraco até ser confirmado) e login (portal B2B). Um evento com subjects[] que cita uma pessoa e uma organização gera vínculo, nunca união de identidade.

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/identity/links" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {"type": "phone_e164", "value": "+14155550123"},
    "organization": {"type": "system_id", "value": "ACC-2201", "scope": "crm", "subject_kind": "account"},
    "role": "buyer",
    "can_see_contacts": true,
    "method": "system_import"
  }'

import os
import uuid
import httpx

response = httpx.post(
    "https://acme-prod.us-east-1.api.niadra.com/v1/identity/links",
    headers={"Authorization": f"Bearer {os.environ['NIADRA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person": {"type": "phone_e164", "value": "+14155550123"},
        "organization": {"type": "system_id", "value": "ACC-2201", "scope": "crm", "subject_kind": "account"},
        "role": "buyer",
        "can_see_contacts": True,
        "method": "system_import",
    },
)
response.raise_for_status()

const response = await fetch("https://acme-prod.us-east-1.api.niadra.com/v1/identity/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NIADRA_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    person: { type: "phone_e164", value: "+14155550123" },
    organization: { type: "system_id", value: "ACC-2201", scope: "crm", subject_kind: "account" },
    role: "buyer",
    can_see_contacts: true,
    method: "system_import",
  }),
});

As rotas de vínculo são rotas de governança: uma pessoa do Console com o papel security ou integration, ou uma chave de escopo admin, e o cabeçalho Idempotency-Key. Um vínculo recebe role, os opcionais valid_from e valid_to, e can_see_contacts, que decide se essa pessoa pode ler o que outros contatos da organização disseram. Quando o contato sai da empresa, encerre o vínculo, se quiser com a data em valid_to. As conversas passadas continuam com o about que tinham; leituras novas com about para aquele par respondem 422 about_without_link.

A memória fica presa à origem

Uma conversa da Marina com o seu agente sobre a rede varejista vira um episódio com sujeito Marina e about igual à conta. Objetos de negócio pertencem ao handle dono deles: o pedido feito pela rede fica na conta, e a Marina se liga a ele pelo vínculo. Como cada item aponta para a própria origem, uma separação de perfis ou um apagamento cai no sujeito certo sem reescrever nada.

Contexto por sujeito

Duas chamadas cobrem as duas situações:

context(subject=<handle da conta>) para o agente que atende a própria empresa, com a view account.
context(subject=<handle da pessoa>, about=<handle da conta>) para o agente que atende o contato. O contexto ganha um bloco da conta com o que ela tem de relevante para a tarefa.

from niadra import Niadra, phone, system_id

niadra = Niadra()

ctx = niadra.context(
    subject=phone("+14155550123"),
    about=system_id("crm", "ACC-2201", kind="account"),
    view="chat",
    verification="V1",
    conversation_id="wa-8812",
)

import { Niadra, handles } from "@niadra/sdk";

const niadra = new Niadra();

const ctx = await niadra.context({
  subject: handles.phone("+14155550123"),
  about: handles.systemId("ACC-2201", "crm", { subjectKind: "account" }),
  view: "chat",
  verification: "V1",
  conversation_id: "wa-8812",
});

O about exige vínculo ativo entre os dois sujeitos. Sem ele, a resposta é 422 about_without_link, e ela nunca revela se a organização existe. A view account reúne os fatos da conta (contrato, SLA, condições), pendências e promessas no nível da conta, objetos abertos, episódios recentes com qualquer contato (com nome e papel de quem falou), padrões da conta e as ações que agentes internos fizeram sobre ela. Até 20 contatos aparecem em detalhe, e os demais entram como contagem. A view partner funciona igual para parceiros.

Um contato não lê o que outro disse

Dado pessoal de contato continua sendo dado pessoal em B2B, e a LGPD e o GDPR não abrem exceção para ele. Para vínculos sem can_see_contacts (o motorista, o contato técnico), o que outros contatos disseram aparece só como contagem e tema. Nome e conteúdo chegam só aos vínculos que têm essa permissão, como o comprador ou o gestor da conta. O papel do vínculo também é um atributo de contexto da política.

Padrões no nível da conta

Um padrão de conta como recurring_complaint pode somar reclamações de vários contatos. Ele só conta evidência que a audiência da view account pode ler, herda a categoria mais restritiva entre as evidências e exige pelo menos dois contatos diferentes.

Política por sujeito

As classes de audiência incluem o tipo de sujeito. Um agente que liga para transportadoras enxerga contexto de partner, não de account. As finalidades partnership e logistics fazem parte do catálogo, e, por padrão, um fornecedor nunca vê o contexto de um parceiro que concorre com ele.

Apagamento

Esquecer uma pessoa não apaga a conta. Sai a memória pessoal dela, inclusive o que ela disse sobre a conta, e os vínculos dela terminam. O que a conta sabe por evento de sistema ou por outros contatos fica. Esquecer uma conta apaga os fatos, objetos e padrões da conta e encerra os vínculos, sem tocar na memória pessoal de cada contato, que só sai a pedido do titular. Os dois caminhos emitem comprovante. Veja Privacidade, apagamento e exportação.

Próximos passos

Identidade e verificação

handles, asserções e os níveis V0 a V4.

O contexto e as views

as views de canal, de tarefa e de sujeito.

Criar vínculo

a requisição e a resposta em detalhe.

Padrões

os sinais que se repetem, com evidência.

A base da memória

O que o agente recebe

Governança

Contas e parceiros

Três tipos de sujeito

Handles de organização

Pessoa e organização se ligam, nunca se unem

A memória fica presa à origem

Contexto por sujeito

Um contato não lê o que outro disse

Padrões no nível da conta

Política por sujeito

Apagamento

Próximos passos

Identidade e verificação

O contexto e as views

Criar vínculo

Padrões

​Três tipos de sujeito

​Handles de organização

​Pessoa e organização se ligam, nunca se unem

​A memória fica presa à origem

​Contexto por sujeito

​Um contato não lê o que outro disse

​Padrões no nível da conta

​Política por sujeito

​Apagamento

​Próximos passos

Identidade e verificação

O contexto e as views

Criar vínculo

Padrões

Três tipos de sujeito

Handles de organização

Pessoa e organização se ligam, nunca se unem

A memória fica presa à origem

Contexto por sujeito

Um contato não lê o que outro disse

Padrões no nível da conta

Política por sujeito

Apagamento

Próximos passos