bfocus 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81fd7ca10ae4eb62028ffbc3e5470247f3017717fdfdc9dc2e6f7563be832df3
-  data.tar.gz: 76800d60498520cb5d3d05870f1b11b5bae78fff6e3036a32807c03f451ab811
+  metadata.gz: a1002f7169bb429c47c8e0b664f24498fca553c8dbe00a694a5f73269b125169
+  data.tar.gz: cfa713f8914a6071c813f3a2bfd6dbd4093421570c36895897a6d151582d4075
 SHA512:
-  metadata.gz: 521f1c6a0ee7b7faa0b9ea653382cad776041ce9be204d66574a6de500402f551e91e54cfb0a2f619e0ee6e0584598cdde1a4dcff721a1df7c59da0c1c4461fb
-  data.tar.gz: 7937ef07106aea158c7c55b8fb313bbd69e3dd9b862c39bd64c682cd2a28d312d2b6bd7a63b928dc41a3fd649057227feba31f092cc8b61300556fd9e7f1e8cc
+  metadata.gz: c26cd338fb79a94dadab4d5d1d045efc6fd36c0c149e4dd819c95aff74ff6e651e0ddf2b17e59e85ad56d41dcc1adc87fb3b0290dad9347c07b506874c8773be
+  data.tar.gz: 8da928fb019d68836af2d6fef305a2b898054d6975773a4c7974324c2f79529543c2eb0a98876f81c7674814ab3dcbd52c5f9d58354af5f6dd831f3394106f4b

data/README.md

@@ -195,11 +195,12 @@ client.people.upsert("erp-1042", "app-77", access: true) # devolve o acesso
 - **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.
 - Como no resto da SDK, só o que você passa muda; `nil` limpa (`phone: nil`).
-- Campos: `name`, `email`, `phone`, `role`, `access` (pode usar o atendimento), `is_primary`
+- Campos: `name`, `email`, `phone`, `document` (CPF), `role`, `access` (pode usar o atendimento), `is_primary`
   (contato principal), `extra_emails`, `extra_phones`, `custom_fields`, `clear`.
 - Erros comuns (`code`): `CUSTOMER_NOT_FOUND`, `NAME_REQUIRED` (ao criar), `PERSON_EMAIL_TAKEN`,
   `PERSON_PHONE_TAKEN`, `PERSON_CONTACT_OTHER_CUSTOMER`, `PERSON_EMAIL_STAFF`,
-  `PERSON_CLEAR_FIELD_INVALID`, `PERSON_CLEAR_NOT_OWN_RECORD`.
+  `PERSON_CLEAR_FIELD_INVALID`, `PERSON_CLEAR_NOT_OWN_RECORD`, `PERSON_DOCUMENT_INVALID`,
+  `PERSON_DOCUMENT_CONFLICT`.
 
 ### Campos personalizados da pessoa
 
@@ -252,6 +253,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.
+
+```ruby
+p = client.people.upsert("erp-1042", "app-91", name: "Paula Reis", document: "529.982.247-25")
+p["document"]     # "52998224725"
+p["merged_into"]  # "app-77" se o CPF já era de outra ficha; nil 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: nil` 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, `Bfocus::ValidationError`) e 409 `PERSON_DOCUMENT_CONFLICT` (a
+  ficha já tem OUTRO CPF — a API nunca troca sozinho; `Bfocus::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
@@ -291,10 +316,13 @@ rescue Bfocus::ConflictError => e
 end
 ```
 
-`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 — `customers.batch` e `people.batch`
 

data/lib/bfocus/resources/people.rb

@@ -73,6 +73,13 @@ module Bfocus
       # transferida: fica ligada também a este (cadastro único, `"linked" => true` na resposta).
       # `access: true` devolve o acesso retirado por {#delete}.
       #
+      # @param document [String] 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 → `"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). `nil`/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).
       # @param access [Boolean] pode abrir chamados/usar o widget.
       # @param is_primary [Boolean] contato principal do cliente.
       # @param extra_emails [Array<String>] e-mails adicionais.
@@ -93,12 +100,13 @@ module Bfocus
       #   ligada a este também) e `"merged_into"` (o id que você mandou era um apelido; este é o
       #   principal do cadastro).
       def upsert(customer_external_id, person_external_id, name: UNSET, email: UNSET, phone: UNSET,
-                 role: UNSET, access: UNSET, is_primary: UNSET, extra_emails: UNSET, extra_phones: UNSET,
+                 document: UNSET, role: UNSET, access: UNSET, is_primary: UNSET, extra_emails: UNSET, extra_phones: UNSET,
                  custom_fields: UNSET, clear: UNSET, idempotency_key: nil, timeout: nil)
         cid = segment(customer_external_id, "customer_external_id")
         pid = segment(person_external_id, "person_external_id")
         person = compact(
-          "name" => name, "email" => email, "phone" => phone, "role" => role, "access" => access,
+          "name" => name, "email" => email, "phone" => phone, "document" => document, "role" => role,
+          "access" => access,
           "is_primary" => is_primary, "extra_emails" => extra_emails, "extra_phones" => extra_phones,
           "custom_fields" => custom_fields, "clear" => clear
         )

data/lib/bfocus/version.rb

@@ -3,5 +3,5 @@
 module Bfocus
   # Versão da gem. O `scripts/release-sdks.sh` do monorepo bumpa esta linha por regex e o
   # `bfocus.gemspec` lê daqui — mantenha o formato exato `VERSION = "X.Y.Z"`.
-  VERSION = "0.2.4"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bfocus
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Berni Software