bfocus 0.2.0__tar.gz → 0.2.2__tar.gz

{bfocus-0.2.0 → bfocus-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bfocus
-Version: 0.2.0
+Version: 0.2.2
 Summary: SDK oficial em Python da API pública do bFocus: clientes, produtos, release notes, base de conhecimento e agentes de IA.
 Project-URL: Homepage, https://bfocus.com.br
 Project-URL: Repository, https://github.com/bernisoftware/bfocus-python
@@ -118,7 +118,7 @@ Construir o cliente não faz nenhuma chamada de rede.
 | `bf.customers.interactions` | `list`, `list_all`, `create` |
 | `bf.customers.identifiers` | `add`, `remove` |
 | `bf.people` | `upsert`, `list`, `delete`, `batch` |
-| `bf.people.identifiers` | `add`, `remove` |
+| `bf.people.identifiers` | `list`, `add`, `remove` |
 | `bf.products` | `list`, `get`, `upsert`, `archive` |
 | `bf.release_notes` | `list`, `list_all`, `get`, `upsert`, `publish` |
 | `bf.kb` | `search` |
@@ -196,11 +196,110 @@ bf.people.upsert("erp-1042", "app-77", access=True)   # devolve o acesso
 
 - **Nunca duplica**: se o e-mail (ou o telefone) já pertence a uma pessoa que chegou por e-mail
   ou por outro sistema, ela é **adotada** e ganha o seu `external_id`.
-- A mesma pessoa informada com **outro cliente** é transferida para ele.
+- A mesma pessoa informada com **outro cliente** NÃO é transferida: ela é **ligada** também a
+  esse cliente e a resposta volta com `linked=True`. O cadastro é único e a mesma pessoa circula
+  por vários clientes e vários produtos.
+- **O acesso é do vínculo.** `delete` (e `access=False`) tira o acesso dela NESTE cliente, não nos
+  outros: `unlinked=True` na resposta quer dizer que ela segue ativa em algum outro.
 - `delete` **retira o acesso** (devolve a pessoa com `access=False`); ela continua no histórico
   de chamados e conversas. Um `upsert` com `access=True` devolve o acesso.
 - Como nos outros upserts, só o que você passa muda; `name` é obrigatório ao criar.
 
+### Campos personalizados da pessoa
+
+`custom_fields` leva o que só existe no seu sistema (matrícula, centro de custo, filial). É a
+**exceção** ao "só o que vier muda": a lista enviada **substitui a lista inteira** — campo que
+ficar de fora é **removido**. Mande sempre a lista que o seu sistema tem hoje; omitir o argumento não mexe
+em nada, como em qualquer outro campo.
+
+A `visibility` é decidida no bFocus e **preservada entre sincronizações** — por isso ela não vai
+no envio, só volta na resposta: o seu ERP não rebaixa nem promove a exposição de um dado sem
+querer.
+
+Vale no upsert de pessoa, no lote de pessoas e na listagem de pessoas do cliente.
+
+```python
+p = bf.people.upsert(
+    "erp-1042",
+    "app-77",
+    custom_fields=[                      # a lista INTEIRA do seu sistema
+        {"key": "matricula", "label": "Matrícula", "value": "4471"},
+        {"key": "filial", "label": "Filial", "value": "Centro"},
+    ],
+)
+for campo in p["custom_fields"]:
+    print(campo["key"], campo["value"], campo["visibility"])   # visibility vem do bFocus
+```
+
+### Apagar o e-mail ou o telefone da pessoa
+
+Um contato gravado errado ficava preso para sempre: enquanto a ficha errada segurasse o
+telefone, nenhum reenvio o soltava. `clear` apaga.
+
+```python
+bf.people.upsert("erp-1042", "app-77", clear=["phone"])          # some o telefone
+bf.people.upsert("erp-1042", "app-77", clear=["email", "phone"]) # some os dois
+```
+
+Três regras que parecem contraintuitivas e são de propósito:
+
+- **Apagar é explícito.** `phone=None`, `clear=[]` e não passar o argumento continuam
+  significando **"não mexe"** — a SDK não traduz `None` em `clear`. Fazer o `None` apagar
+  teria apagado, em silêncio e na primeira carga seguinte, o dado de todo sistema que manda
+  `None` para "não tenho esse valor".
+- **Campo fora da lista é recusado, não ignorado**: hoje só `"email"` e `"phone"`; qualquer
+  outro devolve 422 `PERSON_CLEAR_FIELD_INVALID` (`ValidationError`).
+- **Só se limpa a própria ficha.** Se você alcançou a pessoa por um identificador **extra**, a
+  API recusa com 409 `PERSON_CLEAR_NOT_OWN_RECORD` (`ConflictError`): apagar o contato de uma
+  ficha alcançada por apelido seria apagar dado de outro sistema. Para saber se o id que você
+  tem em mãos é o principal ou um extra, use `bf.people.identifiers.list(...)`.
+
+Vale no `people.upsert` e no `people.batch` (`{"clear": ["phone"]}` no item).
+
+### Contato já usado: um 409 que você consegue resolver
+
+`PERSON_EMAIL_TAKEN` e `PERSON_PHONE_TAKEN` (409) não são "tente de novo": o e-mail (ou o
+telefone) já é de outra pessoa da conta. O erro diz **de quem**, em `err.data` (a API repete o mesmo
+detalhe em `err.validation`, por compatibilidade):
+
+| campo | o que é |
+| --- | --- |
+| `field` | `email` ou `phone` — qual contato está tomado |
+| `owner_external_id` | o identificador da pessoa que já usa esse contato |
+| `owner_name` | o nome dela |
+| `owner_customer_external_id` | o cliente a que ela pertence |
+
+**É o `owner_customer_external_id` que decide a ação**, e os dois casos pedem coisas opostas:
+
+- **mesmo cliente que você enviou** → é quase sempre a MESMA pessoa em dois sistemas. Uma pessoa
+  tem **N identificadores**: registre o seu como **extra** dela. A partir daí o seu id encontra
+  essa pessoa.
+- **outro cliente** → ninguém decide sozinho a quem a pessoa pertence. Não force: registre o caso
+  e leve para quem conhece o cadastro. Unificar dois clientes é decisão de gente, não de um
+  casamento por e-mail.
+
+```python
+from bfocus import ConflictError
+
+try:
+    bf.people.upsert("erp-1042", "app-77", name="Paula Reis", email="paula@padaria.example")
+except ConflictError as err:
+    if err.code not in ("PERSON_EMAIL_TAKEN", "PERSON_PHONE_TAKEN"):
+        raise
+    dono = err.data
+    if dono.get("owner_customer_external_id") == "erp-1042":
+        # A mesma pessoa, com dois ids: o seu vira mais um identificador dela.
+        bf.people.identifiers.add(dono["owner_external_id"], "app-77", label="ERP")
+    else:
+        # Dono em OUTRO cliente: não decida sozinho — registre e leve para o cadastro.
+        avisar_cadastro(err.code, dono)
+```
+
+`PERSON_CONTACT_OTHER_CUSTOMER` (409) é o mesmo assunto pelo outro lado, e é **recusa
+definitiva**: a API não move mais uma pessoa de um cliente para outro só porque o e-mail (ou o
+telefone) casou. Repetir a chamada não resolve — trate como caso para o cadastro, nunca como
+falha temporária.
+
 ## Lotes
 
 `customers.batch` e `people.batch` criam/atualizam **até 500 itens por chamada** (`bfocus.BATCH_MAX`).
@@ -264,6 +363,23 @@ bf.people.identifiers.remove("app-77", "crm-p5")
 
 Num lote, um item enviado com um id extra volta com o principal em `merged_into`.
 
+### Ler os identificadores da pessoa (para reconciliar)
+
+`bf.people.list(...)` mostra só o identificador **principal** de cada pessoa. Quando dois
+cadastros seus eram a mesma pessoa, um dos ids virou **extra** — e some da listagem sem ter
+sumido do cadastro. É isso que faz a sua conferência fechar "633 de 636" sem explicar os 3.
+
+`people.identifiers.list` é a fonte de verdade dessa conferência, e é **leitura**: antes dela
+era preciso ESCREVER (tentar um `add`) para descobrir o que tinha acontecido. Aceita no
+caminho o id principal **ou qualquer um dos extras**.
+
+```python
+ids = bf.people.identifiers.list("crm-p5")   # o id extra que "sumiu" da listagem
+print(ids["external_id"])                    # "app-77" — o principal do cadastro
+for i in ids["identifiers"]:
+    print(i["external_id"], i["label"], i["source"])
+```
+
 ## Sincronizar clientes e usuários do seu sistema
 
 **Ids com o prefixo do sistema, sem `:`** — a assinatura do widget recusa `:`. Use `-` como
@@ -476,6 +592,11 @@ Qualquer resposta fora de 2xx levanta `BfocusError` (ou uma subclasse):
 | `ServerError` | 5xx |
 | `NetworkError` | conexão/timeout — `status == 0`, `code == "NETWORK_ERROR"` |
 
+Além de `code`, `status`, `message`, `request_id`, `validation`, `retry_after` e
+`required_scope`, o erro tem **`data`**: o `data` do corpo, com o detalhe estruturado que alguns
+erros trazem (`{}` quando não há). É por ele que um 409 de contato tomado diz de **quem** é o
+contato — veja [Pessoas](#pessoas).
+
 **Decida pelo `code`** — ele é estável (`CUSTOMER_NOT_FOUND`, `INTEGRATION_SCOPE_MISSING`,
 `VALIDATION_ERROR`…). O `message` é texto para humanos e pode mudar. Ao falar com o suporte,
 informe o `request_id`: ele vem do corpo da resposta, senão do header `X-Request-Id`, senão é o id

{bfocus-0.2.0 → bfocus-0.2.2}/README.md

@@ -91,7 +91,7 @@ Construir o cliente não faz nenhuma chamada de rede.
 | `bf.customers.interactions` | `list`, `list_all`, `create` |
 | `bf.customers.identifiers` | `add`, `remove` |
 | `bf.people` | `upsert`, `list`, `delete`, `batch` |
-| `bf.people.identifiers` | `add`, `remove` |
+| `bf.people.identifiers` | `list`, `add`, `remove` |
 | `bf.products` | `list`, `get`, `upsert`, `archive` |
 | `bf.release_notes` | `list`, `list_all`, `get`, `upsert`, `publish` |
 | `bf.kb` | `search` |
@@ -169,11 +169,110 @@ bf.people.upsert("erp-1042", "app-77", access=True)   # devolve o acesso
 
 - **Nunca duplica**: se o e-mail (ou o telefone) já pertence a uma pessoa que chegou por e-mail
   ou por outro sistema, ela é **adotada** e ganha o seu `external_id`.
-- A mesma pessoa informada com **outro cliente** é transferida para ele.
+- A mesma pessoa informada com **outro cliente** NÃO é transferida: ela é **ligada** também a
+  esse cliente e a resposta volta com `linked=True`. O cadastro é único e a mesma pessoa circula
+  por vários clientes e vários produtos.
+- **O acesso é do vínculo.** `delete` (e `access=False`) tira o acesso dela NESTE cliente, não nos
+  outros: `unlinked=True` na resposta quer dizer que ela segue ativa em algum outro.
 - `delete` **retira o acesso** (devolve a pessoa com `access=False`); ela continua no histórico
   de chamados e conversas. Um `upsert` com `access=True` devolve o acesso.
 - Como nos outros upserts, só o que você passa muda; `name` é obrigatório ao criar.
 
+### Campos personalizados da pessoa
+
+`custom_fields` leva o que só existe no seu sistema (matrícula, centro de custo, filial). É a
+**exceção** ao "só o que vier muda": a lista enviada **substitui a lista inteira** — campo que
+ficar de fora é **removido**. Mande sempre a lista que o seu sistema tem hoje; omitir o argumento não mexe
+em nada, como em qualquer outro campo.
+
+A `visibility` é decidida no bFocus e **preservada entre sincronizações** — por isso ela não vai
+no envio, só volta na resposta: o seu ERP não rebaixa nem promove a exposição de um dado sem
+querer.
+
+Vale no upsert de pessoa, no lote de pessoas e na listagem de pessoas do cliente.
+
+```python
+p = bf.people.upsert(
+    "erp-1042",
+    "app-77",
+    custom_fields=[                      # a lista INTEIRA do seu sistema
+        {"key": "matricula", "label": "Matrícula", "value": "4471"},
+        {"key": "filial", "label": "Filial", "value": "Centro"},
+    ],
+)
+for campo in p["custom_fields"]:
+    print(campo["key"], campo["value"], campo["visibility"])   # visibility vem do bFocus
+```
+
+### Apagar o e-mail ou o telefone da pessoa
+
+Um contato gravado errado ficava preso para sempre: enquanto a ficha errada segurasse o
+telefone, nenhum reenvio o soltava. `clear` apaga.
+
+```python
+bf.people.upsert("erp-1042", "app-77", clear=["phone"])          # some o telefone
+bf.people.upsert("erp-1042", "app-77", clear=["email", "phone"]) # some os dois
+```
+
+Três regras que parecem contraintuitivas e são de propósito:
+
+- **Apagar é explícito.** `phone=None`, `clear=[]` e não passar o argumento continuam
+  significando **"não mexe"** — a SDK não traduz `None` em `clear`. Fazer o `None` apagar
+  teria apagado, em silêncio e na primeira carga seguinte, o dado de todo sistema que manda
+  `None` para "não tenho esse valor".
+- **Campo fora da lista é recusado, não ignorado**: hoje só `"email"` e `"phone"`; qualquer
+  outro devolve 422 `PERSON_CLEAR_FIELD_INVALID` (`ValidationError`).
+- **Só se limpa a própria ficha.** Se você alcançou a pessoa por um identificador **extra**, a
+  API recusa com 409 `PERSON_CLEAR_NOT_OWN_RECORD` (`ConflictError`): apagar o contato de uma
+  ficha alcançada por apelido seria apagar dado de outro sistema. Para saber se o id que você
+  tem em mãos é o principal ou um extra, use `bf.people.identifiers.list(...)`.
+
+Vale no `people.upsert` e no `people.batch` (`{"clear": ["phone"]}` no item).
+
+### Contato já usado: um 409 que você consegue resolver
+
+`PERSON_EMAIL_TAKEN` e `PERSON_PHONE_TAKEN` (409) não são "tente de novo": o e-mail (ou o
+telefone) já é de outra pessoa da conta. O erro diz **de quem**, em `err.data` (a API repete o mesmo
+detalhe em `err.validation`, por compatibilidade):
+
+| campo | o que é |
+| --- | --- |
+| `field` | `email` ou `phone` — qual contato está tomado |
+| `owner_external_id` | o identificador da pessoa que já usa esse contato |
+| `owner_name` | o nome dela |
+| `owner_customer_external_id` | o cliente a que ela pertence |
+
+**É o `owner_customer_external_id` que decide a ação**, e os dois casos pedem coisas opostas:
+
+- **mesmo cliente que você enviou** → é quase sempre a MESMA pessoa em dois sistemas. Uma pessoa
+  tem **N identificadores**: registre o seu como **extra** dela. A partir daí o seu id encontra
+  essa pessoa.
+- **outro cliente** → ninguém decide sozinho a quem a pessoa pertence. Não force: registre o caso
+  e leve para quem conhece o cadastro. Unificar dois clientes é decisão de gente, não de um
+  casamento por e-mail.
+
+```python
+from bfocus import ConflictError
+
+try:
+    bf.people.upsert("erp-1042", "app-77", name="Paula Reis", email="paula@padaria.example")
+except ConflictError as err:
+    if err.code not in ("PERSON_EMAIL_TAKEN", "PERSON_PHONE_TAKEN"):
+        raise
+    dono = err.data
+    if dono.get("owner_customer_external_id") == "erp-1042":
+        # A mesma pessoa, com dois ids: o seu vira mais um identificador dela.
+        bf.people.identifiers.add(dono["owner_external_id"], "app-77", label="ERP")
+    else:
+        # Dono em OUTRO cliente: não decida sozinho — registre e leve para o cadastro.
+        avisar_cadastro(err.code, dono)
+```
+
+`PERSON_CONTACT_OTHER_CUSTOMER` (409) é o mesmo assunto pelo outro lado, e é **recusa
+definitiva**: a API não move mais uma pessoa de um cliente para outro só porque o e-mail (ou o
+telefone) casou. Repetir a chamada não resolve — trate como caso para o cadastro, nunca como
+falha temporária.
+
 ## Lotes
 
 `customers.batch` e `people.batch` criam/atualizam **até 500 itens por chamada** (`bfocus.BATCH_MAX`).
@@ -237,6 +336,23 @@ bf.people.identifiers.remove("app-77", "crm-p5")
 
 Num lote, um item enviado com um id extra volta com o principal em `merged_into`.
 
+### Ler os identificadores da pessoa (para reconciliar)
+
+`bf.people.list(...)` mostra só o identificador **principal** de cada pessoa. Quando dois
+cadastros seus eram a mesma pessoa, um dos ids virou **extra** — e some da listagem sem ter
+sumido do cadastro. É isso que faz a sua conferência fechar "633 de 636" sem explicar os 3.
+
+`people.identifiers.list` é a fonte de verdade dessa conferência, e é **leitura**: antes dela
+era preciso ESCREVER (tentar um `add`) para descobrir o que tinha acontecido. Aceita no
+caminho o id principal **ou qualquer um dos extras**.
+
+```python
+ids = bf.people.identifiers.list("crm-p5")   # o id extra que "sumiu" da listagem
+print(ids["external_id"])                    # "app-77" — o principal do cadastro
+for i in ids["identifiers"]:
+    print(i["external_id"], i["label"], i["source"])
+```
+
 ## Sincronizar clientes e usuários do seu sistema
 
 **Ids com o prefixo do sistema, sem `:`** — a assinatura do widget recusa `:`. Use `-` como
@@ -449,6 +565,11 @@ Qualquer resposta fora de 2xx levanta `BfocusError` (ou uma subclasse):
 | `ServerError` | 5xx |
 | `NetworkError` | conexão/timeout — `status == 0`, `code == "NETWORK_ERROR"` |
 
+Além de `code`, `status`, `message`, `request_id`, `validation`, `retry_after` e
+`required_scope`, o erro tem **`data`**: o `data` do corpo, com o detalhe estruturado que alguns
+erros trazem (`{}` quando não há). É por ele que um 409 de contato tomado diz de **quem** é o
+contato — veja [Pessoas](#pessoas).
+
 **Decida pelo `code`** — ele é estável (`CUSTOMER_NOT_FOUND`, `INTEGRATION_SCOPE_MISSING`,
 `VALIDATION_ERROR`…). O `message` é texto para humanos e pode mudar. Ao falar com o suporte,
 informe o `request_id`: ele vem do corpo da resposta, senão do header `X-Request-Id`, senão é o id

{bfocus-0.2.0 → bfocus-0.2.2}/bfocus/_resources.py

@@ -52,6 +52,7 @@ from .types import (
     Person,
     PersonBatchItem,
     PersonIdentifiers,
+    PersonRevokeResult,
     PersonUpsertResult,
     Product,
     ProductRef,
@@ -150,12 +151,12 @@ def _identifier_label(label: Any) -> Optional[Dict[str, Any]]:
     return None if label is UNSET else {"label": label}
 
 
-def _strings(value: Any) -> Any:
+def _strings(value: Any, field: str = "extra_emails/extra_phones") -> Any:
     """Sequência de strings → lista (preserva UNSET/None). String solta é erro (viraria letras)."""
     if value is UNSET or value is None:
         return value
     if isinstance(value, (str, bytes)):
-        raise TypeError("extra_emails/extra_phones precisam ser uma lista de strings.")
+        raise TypeError(f"{field} precisa ser uma lista de strings.")
     return list(value)
 
 
@@ -554,6 +555,26 @@ class Customers(_Resource):
 class PeopleIdentifiers(_Resource):
     """Identificadores extras de uma pessoa — ``client.people.identifiers``."""
 
+    def list(
+        self, person_external_id: str, *, timeout: Optional[float] = None
+    ) -> PersonIdentifiers:
+        """Todos os identificadores da pessoa: o principal + os extras.
+
+        ``GET /people/{person_external_id}/identifiers``. Escopo ``customers:read``. Aceita
+        no caminho o identificador **principal ou qualquer um dos extras** — ``external_id``
+        no retorno é sempre o principal.
+
+        É a fonte de verdade para **reconciliar**: :meth:`People.list` mostra só o
+        identificador principal de cada pessoa, então um id que virou extra (porque dois
+        cadastros seus eram a mesma pessoa) some de lá sem ter sumido do cadastro. Sem esta
+        leitura era preciso ESCREVER (um ``add``) para descobrir o que tinha acontecido.
+
+        Pessoa inexistente: ``NotFoundError`` com ``code == "PERSON_NOT_FOUND"``.
+        """
+        pid = path_segment(person_external_id, "person_external_id")
+        data, _ = self._t.request("GET", f"/people/{pid}/identifiers", timeout=timeout)
+        return cast(PersonIdentifiers, data)
+
     def add(
         self,
         person_external_id: str,
@@ -624,6 +645,8 @@ class People(_Resource):
         is_primary: MaybeUnset[Optional[bool]] = UNSET,
         extra_emails: MaybeUnset[Optional[Sequence[str]]] = UNSET,
         extra_phones: MaybeUnset[Optional[Sequence[str]]] = UNSET,
+        custom_fields: MaybeUnset[Optional[Sequence[CustomFieldInput]]] = UNSET,
+        clear: MaybeUnset[Optional[Sequence[str]]] = UNSET,
         idempotency_key: Optional[str] = None,
         timeout: Optional[float] = None,
     ) -> PersonUpsertResult:
@@ -632,7 +655,8 @@ class People(_Resource):
         ``PUT /customers/{customer_external_id}/people/{person_external_id}``. O ``status``
         do retorno diz ``"created"``, ``"updated"`` ou ``"unchanged"``. Se o e-mail (ou o
         telefone) já pertence a uma pessoa que chegou por outro caminho, ela é **adotada**
-        (nunca duplicada); a mesma pessoa informada com outro cliente é transferida.
+        (nunca duplicada); a mesma pessoa informada com outro cliente é LIGADA a ele também
+        (cadastro único em N clientes) e ``linked`` volta ``True``.
 
         Args:
             name: Obrigatório ao criar.
@@ -640,6 +664,19 @@ class People(_Resource):
                 acesso retirado por :meth:`delete`.
             extra_emails: E-mails adicionais (somam aos que já existem).
             extra_phones: Telefones adicionais (somam aos que já existem).
+            custom_fields: Campos personalizados da pessoa, ``{"key", "label", "value"}``.
+                Ao contrário de ``extra_emails``/``extra_phones``, a lista **substitui** a
+                lista inteira: mande o que o seu sistema tem HOJE, porque campo que ficou de
+                fora é REMOVIDO. Omitir o argumento não mexe em nada. A ``visibility`` é
+                decidida no bFocus e preservada entre sincronizações.
+            clear: Campos a **apagar** nesta pessoa — hoje ``["email"]``, ``["phone"]`` ou os
+                dois. Apagar é EXPLÍCITO: ``email=None`` (e a lista vazia, e omitir o
+                argumento) continua significando "não mexe", nunca "apague". Campo fora da
+                lista aceita é RECUSADO pela API (422 ``PERSON_CLEAR_FIELD_INVALID``), não
+                ignorado. E só se limpa a PRÓPRIA ficha: se você alcançou a pessoa por um
+                identificador EXTRA, a API recusa (409 ``PERSON_CLEAR_NOT_OWN_RECORD``) —
+                apagar contato de ficha alcançada por apelido seria apagar dado de outro
+                sistema.
         """
         cext = path_segment(customer_external_id, "customer_external_id")
         pid = path_segment(person_external_id, "person_external_id")
@@ -653,6 +690,8 @@ class People(_Resource):
                 "is_primary": is_primary,
                 "extra_emails": _strings(extra_emails),
                 "extra_phones": _strings(extra_phones),
+                "custom_fields": _dicts(custom_fields),
+                "clear": _strings(clear, "clear"),
             }
         )
         data, _ = self._t.request(
@@ -674,12 +713,13 @@ class People(_Resource):
         *,
         idempotency_key: Optional[str] = None,
         timeout: Optional[float] = None,
-    ) -> Person:
-        """Retira o acesso da pessoa (devolve a pessoa com ``access=False``).
+    ) -> PersonRevokeResult:
+        """Retira o acesso da pessoa NESTE cliente (devolve a pessoa com ``access=False``).
 
         ``DELETE /customers/{customer_external_id}/people/{person_external_id}``. A pessoa
         continua no histórico (chamados, conversas); :meth:`upsert` com ``access=True``
-        devolve o acesso.
+        devolve o acesso. O acesso é DO VÍNCULO: se ela também é de outros clientes, continua
+        ativa neles e a resposta volta com ``unlinked=True``.
         """
         cext = path_segment(customer_external_id, "customer_external_id")
         pid = path_segment(person_external_id, "person_external_id")
@@ -687,7 +727,7 @@ class People(_Resource):
             "DELETE", f"/customers/{cext}/people/{pid}",
             idempotency_key=idempotency_key, timeout=timeout,
         )
-        return cast(Person, data)
+        return cast(PersonRevokeResult, data)
 
     def batch(
         self,
@@ -712,9 +752,11 @@ class People(_Resource):
             customer = _required_id(op, index, item, "customer_external_id")
             _required_id(op, index, item, "external_id")
             person = compact({k: v for k, v in item.items() if k != "customer_external_id"})
-            for field in ("extra_emails", "extra_phones"):
+            for field in ("extra_emails", "extra_phones", "clear"):
                 if field in person:
-                    person[field] = _strings(person[field])
+                    person[field] = _strings(person[field], field)
+            if "custom_fields" in person:
+                person["custom_fields"] = _dicts(person["custom_fields"])
             body_items.append({"customer_external_id": customer, "person": person})
         if not body_items:
             return _empty_batch()

{bfocus-0.2.0 → bfocus-0.2.2}/bfocus/_transport.py

@@ -142,6 +142,7 @@ def build_error(
     code: Optional[str] = None
     human: Optional[str] = None
     validation: Dict[str, Any] = {}
+    data: Dict[str, Any] = {}
     request_id: Optional[str] = None
 
     if isinstance(payload, dict):
@@ -154,6 +155,11 @@ def build_error(
             human = msg
         if isinstance(payload.get("validation"), dict):
             validation = payload["validation"]
+        # `data` é o detalhe estruturado do erro (de quem é o contato já usado, o dono de um
+        # identificador…). A API também o repete em `validation`, mas quem lê o erro precisa
+        # alcançá-lo sem depender dessa duplicação.
+        if isinstance(payload.get("data"), dict):
+            data = payload["data"]
         rid = payload.get("request_id")
         if isinstance(rid, str) and rid:
             request_id = rid
@@ -184,6 +190,7 @@ def build_error(
         status,
         request_id=request_id,
         validation=validation,
+        data=data,
         retry_after=retry_after,
         required_scope=required_scope,
         body=payload if payload is not None else (text or None),

{bfocus-0.2.0 → bfocus-0.2.2}/bfocus/_version.py

@@ -1,3 +1,3 @@
 """Versão da SDK. O ``scripts/release-sdks.sh`` bumpa esta linha e o ``pyproject.toml``."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{bfocus-0.2.0 → bfocus-0.2.2}/bfocus/errors.py

@@ -38,6 +38,13 @@ class BfocusError(Exception):
             ``X-Request-Id`` que a SDK enviou (a API ecoa o do cliente) — sempre preenchido;
             informe-o ao suporte.
         validation: Mapa campo → motivo (erros de validação); ``{}`` quando não há.
+        data: O ``data`` do corpo do erro — o detalhe estruturado que alguns erros trazem;
+            ``{}`` quando não há. É onde vem, por exemplo, de quem é o contato já usado num
+            409 ``PERSON_EMAIL_TAKEN``/``PERSON_PHONE_TAKEN`` (``field``,
+            ``owner_external_id``, ``owner_name``, ``owner_customer_external_id``) e o
+            ``owner`` de um ``IDENTIFIER_IN_USE``. A API repete esse detalhe em
+            :attr:`validation`, por compatibilidade com as SDKs que ainda não expunham
+            ``data``.
         retry_after: Segundos sugeridos pelo header ``Retry-After`` (só em 429).
         required_scope: Escopo que faltou na chave (header ``X-Required-Scope``, só em 403).
         body: Corpo da resposta já decodificado (dict), ou o texto cru quando não é JSON.
@@ -54,6 +61,7 @@ class BfocusError(Exception):
         retry_after: Optional[float] = None,
         required_scope: Optional[str] = None,
         body: Any = None,
+        data: Optional[Dict[str, Any]] = None,
     ) -> None:
         super().__init__(message)
         self.code = code
@@ -61,6 +69,7 @@ class BfocusError(Exception):
         self.status = status
         self.request_id = request_id
         self.validation: Dict[str, Any] = dict(validation or {})
+        self.data: Dict[str, Any] = dict(data or {})
         self.retry_after = retry_after
         self.required_scope = required_scope
         self.body = body

{bfocus-0.2.0 → bfocus-0.2.2}/bfocus/types.py

@@ -36,6 +36,7 @@ __all__ = [
     "AgentPreview",
     "Deleted",
     "Person",
+    "PersonRevokeResult",
     "PersonUpsertResult",
     "Identifier",
     "CustomerWithIdentifiers",
@@ -124,7 +125,12 @@ class _CustomFieldInputRequired(TypedDict):
 
 
 class CustomFieldInput(_CustomFieldInputRequired, total=False):
-    """Campo personalizado de cliente. Enviar a lista SUBSTITUI a lista inteira."""
+    """Campo personalizado de cliente **ou de pessoa**. Enviar a lista SUBSTITUI a lista inteira.
+
+    Em pessoa, ``visibility`` **não** é aceito aqui: quem vê o campo é decisão do bFocus e é
+    preservada entre sincronizações (o seu sistema não rebaixa nem promove a exposição de um
+    dado sem querer).
+    """
 
     label: str
     type: Literal[
@@ -188,6 +194,10 @@ class PersonBatchItem(_PersonBatchItemRequired, total=False):
     is_primary: Optional[bool]
     extra_emails: Optional[List[str]]
     extra_phones: Optional[List[str]]
+    custom_fields: Optional[List[CustomFieldInput]]
+    #: Campos a APAGAR nesta pessoa (hoje ``"email"`` e/ou ``"phone"``). Apagar é explícito:
+    #: ``None``, lista vazia ou chave ausente continuam significando "não mexe".
+    clear: Optional[List[str]]
 
 
 class AgentTurn(TypedDict):
@@ -219,6 +229,12 @@ class Customer(TypedDict):
     notes: Optional[str]
     custom_fields: List[CustomField]
     is_active: bool
+    #: Logotipo do cliente, como a equipe subiu no bFocus (``None`` = sem logotipo).
+    logo_url: Optional[str]
+    #: E-mails adicionais do cliente (o principal é ``email``).
+    extra_emails: List[str]
+    #: Telefones adicionais do cliente (o principal é ``phone``).
+    extra_phones: List[str]
     created_at: Optional[str]
     updated_at: Optional[str]
 
@@ -375,12 +391,31 @@ class Person(TypedDict):
     access: bool
     is_primary: bool
     customer_external_id: str
+    custom_fields: List[CustomField]
+    #: Identificadores EXTRAS desta pessoa: os outros ids pelos quais ela também é encontrada.
+    #: É por aqui que você descobre que o id do SEU sistema virou apelido de outra ficha.
+    identifiers: List["Identifier"]
 
 
 class PersonUpsertResult(Person):
-    """Retorno de ``people.upsert``: a pessoa + ``status``."""
+    """Retorno de ``people.upsert``: a pessoa + ``status`` + ``linked``."""
 
     status: Literal["created", "updated", "unchanged"]
+    #: ``True`` = a pessoa JÁ EXISTIA em outro cliente e este envio a ligou também a este.
+    #: O cadastro é único e ela circula pelos dois; nada foi transferido nem duplicado.
+    linked: bool
+    #: Preenchido quando o id que você enviou é um APELIDO: este é o principal do cadastro.
+    merged_into: Optional[str]
+
+
+class PersonRevokeResult(Person):
+    """Retorno de ``people.delete``: a pessoa + se ela apenas SAIU deste cliente.
+
+    ``unlinked=True`` = ela continua com acesso, porque também é de outros clientes; o acesso é
+    do vínculo. ``False`` = era só deste cliente e foi desligada, como sempre.
+    """
+
+    unlinked: bool
 
 
 class Identifier(TypedDict):
@@ -414,6 +449,8 @@ class BatchItemResult(TypedDict):
     status: Literal["created", "updated", "unchanged", "error"]
     external_id: Optional[str]
     merged_into: Optional[str]
+    #: A pessoa já existia em outro cliente e este item a ligou também a este (cadastro único).
+    linked: bool
     error: Optional[str]
     code: Optional[int]
 

{bfocus-0.2.0 → bfocus-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bfocus"
-version = "0.2.0"
+version = "0.2.2"
 description = "SDK oficial em Python da API pública do bFocus: clientes, produtos, release notes, base de conhecimento e agentes de IA."
 readme = "README.md"
 requires-python = ">=3.9"

{bfocus-0.2.0 → bfocus-0.2.2}/tests/fixtures/cases.json

@@ -69,6 +69,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -97,6 +100,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -144,6 +150,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -172,6 +181,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -216,6 +228,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -244,6 +259,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }
@@ -327,6 +345,9 @@
                   "notes": null,
                   "custom_fields": [],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -356,6 +377,9 @@
               "notes": null,
               "custom_fields": [],
               "is_active": true,
+              "logo_url": null,
+              "extra_emails": [],
+              "extra_phones": [],
               "created_at": "2026-09-13T12:00:00+00:00",
               "updated_at": "2026-09-13T12:00:00+00:00"
             }
@@ -410,6 +434,9 @@
                     }
                   ],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -452,6 +479,9 @@
                   "notes": null,
                   "custom_fields": [],
                   "is_active": true,
+                  "logo_url": null,
+                  "extra_emails": [],
+                  "extra_phones": [],
                   "created_at": "2026-09-13T12:00:00+00:00",
                   "updated_at": "2026-09-13T12:00:00+00:00"
                 }
@@ -488,6 +518,9 @@
               }
             ],
             "is_active": true,
+            "logo_url": null,
+            "extra_emails": [],
+            "extra_phones": [],
             "created_at": "2026-09-13T12:00:00+00:00",
             "updated_at": "2026-09-13T12:00:00+00:00"
           },
@@ -502,6 +535,9 @@
             "notes": null,
             "custom_fields": [],
             "is_active": true,
+            "logo_url": null,
+            "extra_emails": [],
+            "extra_phones": [],
             "created_at": "2026-09-13T12:00:00+00:00",
             "updated_at": "2026-09-13T12:00:00+00:00"
           }
@@ -1021,6 +1057,17 @@
                 "access": true,
                 "is_primary": true,
                 "customer_external_id": "ERP 1042",
+                "custom_fields": [
+                  {
+                    "key": "matricula",
+                    "label": "Matrícula",
+                    "value": "4471",
+                    "visibility": "interno"
+                  }
+                ],
+                "identifiers": [],
+                "linked": false,
+                "merged_into": null,
                 "status": "created"
               },
               "message": "Executado com sucesso"
@@ -1038,6 +1085,17 @@
           "access": true,
           "is_primary": true,
           "customer_external_id": "ERP 1042",
+          "custom_fields": [
+            {
+              "key": "matricula",
+              "label": "Matrícula",
+              "value": "4471",
+              "visibility": "interno"
+            }
+          ],
+          "identifiers": [],
+          "linked": false,
+          "merged_into": null,
           "status": "created"
         }
       }
@@ -1085,6 +1143,17 @@
                 "access": false,
                 "is_primary": true,
                 "customer_external_id": "ERP 1042",
+                "custom_fields": [
+                  {
+                    "key": "matricula",
+                    "label": "Matrícula",
+                    "value": "4471",
+                    "visibility": "interno"
+                  }
+                ],
+                "identifiers": [],
+                "linked": false,
+                "merged_into": null,
                 "status": "updated"
               },
               "message": "Executado com sucesso"
@@ -1102,6 +1171,17 @@
           "access": false,
           "is_primary": true,
           "customer_external_id": "ERP 1042",
+          "custom_fields": [
+            {
+              "key": "matricula",
+              "label": "Matrícula",
+              "value": "4471",
+              "visibility": "interno"
+            }
+          ],
+          "identifiers": [],
+          "linked": false,
+          "merged_into": null,
           "status": "updated"
         }
       }
@@ -1181,7 +1261,16 @@
                   "role": "Financeiro",
                   "access": true,
                   "is_primary": true,
-                  "customer_external_id": "ERP 1042"
+                  "customer_external_id": "ERP 1042",
+                  "custom_fields": [
+                    {
+                      "key": "matricula",
+                      "label": "Matrícula",
+                      "value": "4471",
+                      "visibility": "interno"
+                    }
+                  ],
+                  "identifiers": []
                 },
                 {
                   "external_id": null,
@@ -1191,7 +1280,9 @@
                   "role": "Compras",
                   "access": false,
                   "is_primary": false,
-                  "customer_external_id": "ERP 1042"
+                  "customer_external_id": "ERP 1042",
+                  "custom_fields": [],
+                  "identifiers": []
                 }
               ],
               "message": "Executado com sucesso"
@@ -1209,7 +1300,16 @@
             "role": "Financeiro",
             "access": true,
             "is_primary": true,
-            "customer_external_id": "ERP 1042"
+            "customer_external_id": "ERP 1042",
+            "custom_fields": [
+              {
+                "key": "matricula",
+                "label": "Matrícula",
+                "value": "4471",
+                "visibility": "interno"
+              }
+            ],
+            "identifiers": []
           },
           {
             "external_id": null,
@@ -1219,7 +1319,9 @@
             "role": "Compras",
             "access": false,
             "is_primary": false,
-            "customer_external_id": "ERP 1042"
+            "customer_external_id": "ERP 1042",
+            "custom_fields": [],
+            "identifiers": []
           }
         ]
       }
@@ -1253,7 +1355,17 @@
                 "role": "Financeiro",
                 "access": false,
                 "is_primary": true,
-                "customer_external_id": "ERP 1042"
+                "customer_external_id": "ERP 1042",
+                "custom_fields": [
+                  {
+                    "key": "matricula",
+                    "label": "Matrícula",
+                    "value": "4471",
+                    "visibility": "interno"
+                  }
+                ],
+                "identifiers": [],
+                "unlinked": false
               },
               "message": "Acesso retirado"
             }
@@ -1269,7 +1381,17 @@
           "role": "Financeiro",
           "access": false,
           "is_primary": true,
-          "customer_external_id": "ERP 1042"
+          "customer_external_id": "ERP 1042",
+          "custom_fields": [
+            {
+              "key": "matricula",
+              "label": "Matrícula",
+              "value": "4471",
+              "visibility": "interno"
+            }
+          ],
+          "identifiers": [],
+          "unlinked": false
         }
       }
     },
@@ -1361,6 +1483,7 @@
                     "status": "updated",
                     "external_id": "ERP 1042",
                     "merged_into": null,
+                    "linked": false,
                     "error": null,
                     "code": null
                   },
@@ -1369,6 +1492,7 @@
                     "status": "error",
                     "external_id": "ERP 1044",
                     "merged_into": null,
+                    "linked": false,
                     "error": "NAME_REQUIRED",
                     "code": 422
                   }
@@ -1393,6 +1517,7 @@
               "status": "updated",
               "external_id": "ERP 1042",
               "merged_into": null,
+              "linked": false,
               "error": null,
               "code": null
             },
@@ -1401,6 +1526,7 @@
               "status": "error",
               "external_id": "ERP 1044",
               "merged_into": null,
+              "linked": false,
               "error": "NAME_REQUIRED",
               "code": 422
             }
@@ -1492,6 +1618,7 @@
                     "status": "created",
                     "external_id": "app-77",
                     "merged_into": null,
+                    "linked": false,
                     "error": null,
                     "code": null
                   },
@@ -1500,6 +1627,7 @@
                     "status": "error",
                     "external_id": "app-78",
                     "merged_into": null,
+                    "linked": false,
                     "error": "CUSTOMER_NOT_FOUND",
                     "code": 404
                   }
@@ -1524,6 +1652,7 @@
               "status": "created",
               "external_id": "app-77",
               "merged_into": null,
+              "linked": false,
               "error": null,
               "code": null
             },
@@ -1532,6 +1661,7 @@
               "status": "error",
               "external_id": "app-78",
               "merged_into": null,
+              "linked": false,
               "error": "CUSTOMER_NOT_FOUND",
               "code": 404
             }
@@ -1607,6 +1737,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00",
                 "identifiers": [
@@ -1642,6 +1775,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00",
           "identifiers": [
@@ -1740,6 +1876,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00",
                 "identifiers": []
@@ -1769,6 +1908,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00",
           "identifiers": []
@@ -1824,6 +1966,54 @@
         }
       }
     },
+    {
+      "id": "people.identifiers.list/by_extra",
+      "op": "people.identifiers.list",
+      "args": {
+        "person_external_id": "crm-p5"
+      },
+      "exchanges": [
+        {
+          "retry": false,
+          "request": {
+            "method": "GET",
+            "path": "/api/v1/integration/people/crm-p5/identifiers",
+            "query": {},
+            "body": null
+          },
+          "response": {
+            "status": 200,
+            "headers": {},
+            "body": {
+              "code": 200,
+              "data": {
+                "external_id": "app-77",
+                "identifiers": [
+                  {
+                    "external_id": "crm-p5",
+                    "label": null,
+                    "source": "api"
+                  }
+                ]
+              },
+              "message": "Executado com sucesso"
+            }
+          }
+        }
+      ],
+      "expect": {
+        "result": {
+          "external_id": "app-77",
+          "identifiers": [
+            {
+              "external_id": "crm-p5",
+              "label": null,
+              "source": "api"
+            }
+          ]
+        }
+      }
+    },
     {
       "id": "people.identifiers.remove/not_found",
       "op": "people.identifiers.remove",
@@ -3482,6 +3672,9 @@
                   }
                 ],
                 "is_active": true,
+                "logo_url": null,
+                "extra_emails": [],
+                "extra_phones": [],
                 "created_at": "2026-09-13T12:00:00+00:00",
                 "updated_at": "2026-09-13T12:00:00+00:00"
               },
@@ -3510,6 +3703,9 @@
             }
           ],
           "is_active": true,
+          "logo_url": null,
+          "extra_emails": [],
+          "extra_phones": [],
           "created_at": "2026-09-13T12:00:00+00:00",
           "updated_at": "2026-09-13T12:00:00+00:00"
         }

{bfocus-0.2.0 → bfocus-0.2.2}/tests/test_conformance.py

@@ -62,6 +62,7 @@ OPS: Dict[str, Callable[[Bfocus], Callable[..., Any]]] = {
     "people.list": lambda bf: bf.people.list,
     "people.delete": lambda bf: bf.people.delete,
     "people.batch": lambda bf: bf.people.batch,
+    "people.identifiers.list": lambda bf: bf.people.identifiers.list,
     "people.identifiers.add": lambda bf: bf.people.identifiers.add,
     "people.identifiers.remove": lambda bf: bf.people.identifiers.remove,
     "products.list": lambda bf: bf.products.list,

{bfocus-0.2.0 → bfocus-0.2.2}/tests/test_unit.py

@@ -15,7 +15,9 @@ from bfocus import (
     UNSET,
     Bfocus,
     BfocusError,
+    ConflictError,
     NetworkError,
+    NotFoundError,
     Page,
     RateLimitError,
     ServerError,
@@ -436,6 +438,30 @@ class ErrorShapeTest(_ServerCase):
         self.assertIn("req-9", str(err))
         self.assertIsNone(err.retry_after)
 
+    def test_data_traz_o_dono_do_contato_tomado(self) -> None:
+        """409 acionável: `data` diz de QUEM é o e-mail, e a API repete em `validation`."""
+        dono = {"field": "email", "owner_external_id": "app-12", "owner_name": "Paula Reis",
+                "owner_customer_external_id": "erp-1042"}
+        bf = self.client([{
+            "status": 409, "headers": {},
+            "body": {"code": 409, "data": dono, "message": "PERSON_EMAIL_TAKEN",
+                     "error": "PERSON_EMAIL_TAKEN", "validation": dono, "request_id": "req-9"},
+        }])
+        with self.assertRaises(ConflictError) as ctx:
+            bf.people.upsert("erp-1042", "app-77", email="paula@padaria.example")
+        err = ctx.exception
+        self.assertEqual(err.code, "PERSON_EMAIL_TAKEN")
+        self.assertEqual(err.data, dono)
+        self.assertEqual(err.data["owner_customer_external_id"], "erp-1042")
+        self.assertEqual(err.validation, dono)
+
+    def test_data_vazio_quando_o_erro_nao_traz_detalhe(self) -> None:
+        bf = self.client([{"status": 404, "headers": {},
+                           "body": {"code": 404, "data": None, "error": "CUSTOMER_NOT_FOUND"}}])
+        with self.assertRaises(NotFoundError) as ctx:
+            bf.customers.get("erp-1042")
+        self.assertEqual(ctx.exception.data, {})
+
     def test_2xx_sem_envelope_e_invalid_response(self) -> None:
         bodies = [
             {"status": 200, "headers": {}, "body": "<html>proxy</html>"},