bfocus 0.2.4__tar.gz → 0.2.5__tar.gz

{bfocus-0.2.4 → bfocus-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bfocus
-Version: 0.2.4
+Version: 0.2.5
 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
@@ -256,6 +256,30 @@ Três regras que parecem contraintuitivas e são de propósito:
 
 Vale no `people.upsert` e no `people.batch` (`{"clear": ["phone"]}` no item).
 
+### CPF: a pessoa é única
+
+`document` é o CPF da pessoa. É por ele que dois sistemas que conhecem a mesma pessoa por ids
+diferentes chegam ao MESMO cadastro.
+
+```python
+p = bf.people.upsert("erp-1042", "app-91", name="Paula Reis", document="529.982.247-25")
+print(p["document"])      # "52998224725"
+print(p["merged_into"])   # "app-77" se o CPF já era de outra ficha; None se não
+```
+
+Regras (valem no upsert e no lote):
+
+- **A pessoa é única.** O mesmo CPF é sempre o mesmo cadastro, em qualquer produto e cliente. Mande
+  com ou sem máscara; a resposta traz só os 11 dígitos em `document`.
+- **Id desconhecido + CPF que já existe** → a API acha a ficha, o seu id vira identificador extra
+  dela e a resposta vem com `merged_into` = o id principal. Guarde esse id do seu lado.
+- **Id de uma ficha + CPF de OUTRA** → as duas são mescladas na hora; `merged_into` = a que tinha o CPF.
+- **`document=None` NÃO apaga** o CPF (e `document` não é campo do `clear`). Omitir é o mesmo que "não mexe".
+- Erros: 422 `PERSON_DOCUMENT_INVALID` (CPF inválido, `ValidationError`) e 409 `PERSON_DOCUMENT_CONFLICT` (a
+  ficha já tem OUTRO CPF — a API nunca troca sozinho; `ConflictError`).
+
+No lote: `{"document": "529.982.247-25"}` 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
@@ -295,10 +319,13 @@ except ConflictError as err:
         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.
+`PERSON_CONTACT_OTHER_CUSTOMER` (409) é o mesmo assunto pelo outro lado: o e-mail (ou o telefone) é
+de uma pessoa de **outro cliente**. A API **não liga duas fichas sozinha** só porque o contato casou
+— dois cadastros podem dividir um e-mail ou um telefone, e ligar por palpite já destruiu fichas.
+Repetir a chamada não resolve. Se for **mesmo a mesma pessoa** (confirme antes), o erro traz o dono
+nos dados, como os outros dois conflitos: registre o seu id como identificador extra da ficha dele
+(`owner_external_id`) e o próximo envio **liga** a pessoa ao seu cliente (`linked: true`), sem
+sobrescrever os dados da outra ficha.
 
 ## Lotes
 

{bfocus-0.2.4 → bfocus-0.2.5}/README.md

@@ -229,6 +229,30 @@ Três regras que parecem contraintuitivas e são de propósito:
 
 Vale no `people.upsert` e no `people.batch` (`{"clear": ["phone"]}` no item).
 
+### CPF: a pessoa é única
+
+`document` é o CPF da pessoa. É por ele que dois sistemas que conhecem a mesma pessoa por ids
+diferentes chegam ao MESMO cadastro.
+
+```python
+p = bf.people.upsert("erp-1042", "app-91", name="Paula Reis", document="529.982.247-25")
+print(p["document"])      # "52998224725"
+print(p["merged_into"])   # "app-77" se o CPF já era de outra ficha; None se não
+```
+
+Regras (valem no upsert e no lote):
+
+- **A pessoa é única.** O mesmo CPF é sempre o mesmo cadastro, em qualquer produto e cliente. Mande
+  com ou sem máscara; a resposta traz só os 11 dígitos em `document`.
+- **Id desconhecido + CPF que já existe** → a API acha a ficha, o seu id vira identificador extra
+  dela e a resposta vem com `merged_into` = o id principal. Guarde esse id do seu lado.
+- **Id de uma ficha + CPF de OUTRA** → as duas são mescladas na hora; `merged_into` = a que tinha o CPF.
+- **`document=None` NÃO apaga** o CPF (e `document` não é campo do `clear`). Omitir é o mesmo que "não mexe".
+- Erros: 422 `PERSON_DOCUMENT_INVALID` (CPF inválido, `ValidationError`) e 409 `PERSON_DOCUMENT_CONFLICT` (a
+  ficha já tem OUTRO CPF — a API nunca troca sozinho; `ConflictError`).
+
+No lote: `{"document": "529.982.247-25"}` 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
@@ -268,10 +292,13 @@ except ConflictError as err:
         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.
+`PERSON_CONTACT_OTHER_CUSTOMER` (409) é o mesmo assunto pelo outro lado: o e-mail (ou o telefone) é
+de uma pessoa de **outro cliente**. A API **não liga duas fichas sozinha** só porque o contato casou
+— dois cadastros podem dividir um e-mail ou um telefone, e ligar por palpite já destruiu fichas.
+Repetir a chamada não resolve. Se for **mesmo a mesma pessoa** (confirme antes), o erro traz o dono
+nos dados, como os outros dois conflitos: registre o seu id como identificador extra da ficha dele
+(`owner_external_id`) e o próximo envio **liga** a pessoa ao seu cliente (`linked: true`), sem
+sobrescrever os dados da outra ficha.
 
 ## Lotes
 

{bfocus-0.2.4 → bfocus-0.2.5}/bfocus/_resources.py

@@ -655,6 +655,7 @@ class People(_Resource):
         name: MaybeUnset[Optional[str]] = UNSET,
         email: MaybeUnset[Optional[str]] = UNSET,
         phone: MaybeUnset[Optional[str]] = UNSET,
+        document: MaybeUnset[Optional[str]] = UNSET,
         role: MaybeUnset[Optional[str]] = UNSET,
         access: MaybeUnset[Optional[bool]] = UNSET,
         is_primary: MaybeUnset[Optional[bool]] = UNSET,
@@ -675,6 +676,14 @@ class People(_Resource):
 
         Args:
             name: Obrigatório ao criar.
+            document: CPF da pessoa, com ou sem máscara (a resposta traz só os 11 dígitos).
+                A PESSOA É ÚNICA: o mesmo CPF é sempre o mesmo cadastro, em qualquer produto.
+                Id desconhecido + CPF de uma ficha existente → a resposta vem com
+                ``merged_into`` = id principal dela (o seu id vira identificador extra). Id de
+                uma ficha + CPF de OUTRA → as duas são mescladas na hora (``merged_into`` = a
+                que tinha o CPF). ``None``/vazio NÃO apaga (não é campo do ``clear``). Erros:
+                422 ``PERSON_DOCUMENT_INVALID`` (CPF inválido) e 409
+                ``PERSON_DOCUMENT_CONFLICT`` (a ficha já tem OUTRO CPF — nunca troca sozinho).
             access: Acesso ao widget/portal (padrão ao criar: ``True``). ``True`` devolve o
                 acesso retirado por :meth:`delete`.
             extra_emails: E-mails adicionais (somam aos que já existem).
@@ -700,6 +709,7 @@ class People(_Resource):
                 "name": name,
                 "email": email,
                 "phone": phone,
+                "document": document,
                 "role": role,
                 "access": access,
                 "is_primary": is_primary,

{bfocus-0.2.4 → bfocus-0.2.5}/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.4"
+__version__ = "0.2.5"

{bfocus-0.2.4 → bfocus-0.2.5}/bfocus/types.py

@@ -194,6 +194,9 @@ class PersonBatchItem(_PersonBatchItemRequired, total=False):
     name: Optional[str]
     email: Optional[str]
     phone: Optional[str]
+    #: CPF da pessoa (com ou sem máscara). A pessoa é ÚNICA: o mesmo CPF é sempre o mesmo
+    #: cadastro. ``None``/vazio não apaga. Ver ``people.upsert``.
+    document: Optional[str]
     role: Optional[str]
     access: Optional[bool]
     is_primary: Optional[bool]
@@ -402,6 +405,8 @@ class Person(TypedDict):
     name: str
     email: Optional[str]
     phone: Optional[str]
+    #: CPF da pessoa, só os 11 dígitos (``None`` = não informado).
+    document: Optional[str]
     role: Optional[str]
     access: bool
     is_primary: bool

{bfocus-0.2.4 → bfocus-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bfocus"
-version = "0.2.4"
+version = "0.2.5"
 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.4 → bfocus-0.2.5}/tests/fixtures/cases.json

@@ -1295,6 +1295,7 @@
                 "name": "Paula Reis",
                 "email": "paula@padaria.example",
                 "phone": null,
+                "document": null,
                 "role": "Financeiro",
                 "access": true,
                 "is_primary": true,
@@ -1323,6 +1324,7 @@
           "name": "Paula Reis",
           "email": "paula@padaria.example",
           "phone": null,
+          "document": null,
           "role": "Financeiro",
           "access": true,
           "is_primary": true,
@@ -1381,6 +1383,7 @@
                 "name": "Paula Reis",
                 "email": "paula@padaria.example",
                 "phone": null,
+                "document": null,
                 "role": "Financeiro",
                 "access": false,
                 "is_primary": true,
@@ -1409,6 +1412,7 @@
           "name": "Paula Reis",
           "email": "paula@padaria.example",
           "phone": null,
+          "document": null,
           "role": "Financeiro",
           "access": false,
           "is_primary": true,
@@ -1474,6 +1478,199 @@
         }
       }
     },
+    {
+      "id": "people.upsert/document_merged",
+      "op": "people.upsert",
+      "args": {
+        "customer_external_id": "ERP 1042",
+        "person_external_id": "app-91",
+        "name": "Paula Reis",
+        "document": "529.982.247-25"
+      },
+      "exchanges": [
+        {
+          "retry": false,
+          "request": {
+            "method": "PUT",
+            "path": "/api/v1/integration/customers/ERP%201042/people/app-91",
+            "query": {},
+            "body": {
+              "person": {
+                "name": "Paula Reis",
+                "document": "529.982.247-25"
+              }
+            }
+          },
+          "response": {
+            "status": 200,
+            "headers": {},
+            "body": {
+              "code": 200,
+              "data": {
+                "external_id": "app-77",
+                "name": "Paula Reis",
+                "email": "paula@padaria.example",
+                "phone": null,
+                "document": "52998224725",
+                "role": "Financeiro",
+                "access": true,
+                "is_primary": true,
+                "customer_external_id": "ERP 1042",
+                "custom_fields": [
+                  {
+                    "key": "matricula",
+                    "label": "Matrícula",
+                    "value": "4471",
+                    "visibility": "interno"
+                  }
+                ],
+                "identifiers": [
+                  {
+                    "external_id": "app-91",
+                    "label": null,
+                    "source": "api"
+                  }
+                ],
+                "linked": false,
+                "merged_into": "app-77",
+                "status": "updated"
+              },
+              "message": "Executado com sucesso"
+            }
+          }
+        }
+      ],
+      "expect": {
+        "result": {
+          "external_id": "app-77",
+          "name": "Paula Reis",
+          "email": "paula@padaria.example",
+          "phone": null,
+          "document": "52998224725",
+          "role": "Financeiro",
+          "access": true,
+          "is_primary": true,
+          "customer_external_id": "ERP 1042",
+          "custom_fields": [
+            {
+              "key": "matricula",
+              "label": "Matrícula",
+              "value": "4471",
+              "visibility": "interno"
+            }
+          ],
+          "identifiers": [
+            {
+              "external_id": "app-91",
+              "label": null,
+              "source": "api"
+            }
+          ],
+          "linked": false,
+          "merged_into": "app-77",
+          "status": "updated"
+        }
+      }
+    },
+    {
+      "id": "people.upsert/document_conflict",
+      "op": "people.upsert",
+      "args": {
+        "customer_external_id": "ERP 1042",
+        "person_external_id": "app-77",
+        "document": "111.444.777-35"
+      },
+      "exchanges": [
+        {
+          "retry": false,
+          "request": {
+            "method": "PUT",
+            "path": "/api/v1/integration/customers/ERP%201042/people/app-77",
+            "query": {},
+            "body": {
+              "person": {
+                "document": "111.444.777-35"
+              }
+            }
+          },
+          "response": {
+            "status": 409,
+            "headers": {},
+            "body": {
+              "code": 409,
+              "data": {
+                "field": "document"
+              },
+              "message": "PERSON_DOCUMENT_CONFLICT",
+              "error": "PERSON_DOCUMENT_CONFLICT",
+              "validation": {
+                "field": "document"
+              },
+              "request_id": "req-conformance-01"
+            }
+          }
+        }
+      ],
+      "expect": {
+        "error": {
+          "type": "conflict",
+          "code": "PERSON_DOCUMENT_CONFLICT",
+          "status": 409,
+          "request_id": "req-conformance-01"
+        }
+      }
+    },
+    {
+      "id": "people.upsert/document_invalid",
+      "op": "people.upsert",
+      "args": {
+        "customer_external_id": "ERP 1042",
+        "person_external_id": "app-77",
+        "document": "123.456.789-00"
+      },
+      "exchanges": [
+        {
+          "retry": false,
+          "request": {
+            "method": "PUT",
+            "path": "/api/v1/integration/customers/ERP%201042/people/app-77",
+            "query": {},
+            "body": {
+              "person": {
+                "document": "123.456.789-00"
+              }
+            }
+          },
+          "response": {
+            "status": 422,
+            "headers": {},
+            "body": {
+              "code": 422,
+              "data": {
+                "field": "document"
+              },
+              "message": "PERSON_DOCUMENT_INVALID",
+              "error": "PERSON_DOCUMENT_INVALID",
+              "validation": {
+                "field": "document"
+              },
+              "request_id": "req-conformance-01"
+            }
+          }
+        }
+      ],
+      "expect": {
+        "error": {
+          "type": "validation",
+          "code": "PERSON_DOCUMENT_INVALID",
+          "status": 422,
+          "request_id": "req-conformance-01",
+          "validation": {
+            "field": "document"
+          }
+        }
+      }
+    },
     {
       "id": "people.list/ok",
       "op": "people.list",
@@ -1500,6 +1697,7 @@
                   "name": "Paula Reis",
                   "email": "paula@padaria.example",
                   "phone": null,
+                  "document": null,
                   "role": "Financeiro",
                   "access": true,
                   "is_primary": true,
@@ -1519,6 +1717,7 @@
                   "name": "Rui Lima",
                   "email": null,
                   "phone": "+5511999990000",
+                  "document": null,
                   "role": "Compras",
                   "access": false,
                   "is_primary": false,
@@ -1539,6 +1738,7 @@
             "name": "Paula Reis",
             "email": "paula@padaria.example",
             "phone": null,
+            "document": null,
             "role": "Financeiro",
             "access": true,
             "is_primary": true,
@@ -1558,6 +1758,7 @@
             "name": "Rui Lima",
             "email": null,
             "phone": "+5511999990000",
+            "document": null,
             "role": "Compras",
             "access": false,
             "is_primary": false,
@@ -1594,6 +1795,7 @@
                 "name": "Paula Reis",
                 "email": "paula@padaria.example",
                 "phone": null,
+                "document": null,
                 "role": "Financeiro",
                 "access": false,
                 "is_primary": true,
@@ -1620,6 +1822,7 @@
           "name": "Paula Reis",
           "email": "paula@padaria.example",
           "phone": null,
+          "document": null,
           "role": "Financeiro",
           "access": false,
           "is_primary": true,
@@ -2050,6 +2253,120 @@
         }
       }
     },
+    {
+      "id": "people.batch/document",
+      "op": "people.batch",
+      "args": {
+        "items": [
+          {
+            "customer_external_id": "ERP 1042",
+            "external_id": "app-77",
+            "document": "529.982.247-25"
+          },
+          {
+            "customer_external_id": "ERP 1042",
+            "external_id": "app-91",
+            "name": "Paula Reis",
+            "document": "52998224725"
+          }
+        ]
+      },
+      "exchanges": [
+        {
+          "retry": false,
+          "request": {
+            "method": "POST",
+            "path": "/api/v1/integration/people/batch",
+            "query": {},
+            "body": {
+              "items": [
+                {
+                  "customer_external_id": "ERP 1042",
+                  "person": {
+                    "external_id": "app-77",
+                    "document": "529.982.247-25"
+                  }
+                },
+                {
+                  "customer_external_id": "ERP 1042",
+                  "person": {
+                    "external_id": "app-91",
+                    "name": "Paula Reis",
+                    "document": "52998224725"
+                  }
+                }
+              ]
+            }
+          },
+          "response": {
+            "status": 200,
+            "headers": {},
+            "body": {
+              "code": 200,
+              "data": {
+                "results": [
+                  {
+                    "index": 0,
+                    "status": "updated",
+                    "external_id": "app-77",
+                    "merged_into": null,
+                    "linked": false,
+                    "error": null,
+                    "code": null
+                  },
+                  {
+                    "index": 1,
+                    "status": "updated",
+                    "external_id": "app-77",
+                    "merged_into": "app-77",
+                    "linked": false,
+                    "error": null,
+                    "code": null
+                  }
+                ],
+                "summary": {
+                  "created": 0,
+                  "updated": 2,
+                  "unchanged": 0,
+                  "error": 0
+                }
+              },
+              "message": "Executado com sucesso"
+            }
+          }
+        }
+      ],
+      "expect": {
+        "result": {
+          "results": [
+            {
+              "index": 0,
+              "status": "updated",
+              "external_id": "app-77",
+              "merged_into": null,
+              "linked": false,
+              "error": null,
+              "code": null
+            },
+            {
+              "index": 1,
+              "status": "updated",
+              "external_id": "app-77",
+              "merged_into": "app-77",
+              "linked": false,
+              "error": null,
+              "code": null
+            }
+          ],
+          "summary": {
+            "created": 0,
+            "updated": 2,
+            "unchanged": 0,
+            "error": 0
+          }
+        }
+      }
+    },
     {
       "id": "customers.identifiers.add/with_label",
       "op": "customers.identifiers.add",