bfocus 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6989b99e0788e360a77f8853de9a52f5e9628db20515a2ccbb9c57fd173e4c23
-  data.tar.gz: 3e3a8766862577d33ddf9e8bb3959b380fbd995f43e97688bd7f8bf05d3a06c2
+  metadata.gz: cde8597ee9adbdde78b052fc3527eb19ed6a5045f73829424d835f696dcd95c9
+  data.tar.gz: 867ddf4b2644cbe30252ac5ca6d482e6a4a5216049a4469e6f5f2d5ed4f5757b
 SHA512:
-  metadata.gz: 337c578cf5bde255220540a83297d298a89a08f97e31f72a274a25b7614c5c9b68b9cd782a95f39382ed3b858019d42a0dd16a4fc66483a281e6e43bce1e2b18
-  data.tar.gz: 5291a2a3e6b1cd5e6fd6bd7bf9d5dfb2e3abc12aa14cccc70b9fc1d2400eba5980e56edc62e2ccfa988acff36c3afb6bff13f9180cbb2e1c27f610bdc2c45716
+  metadata.gz: 7a5abc2452240b5f164b164e72bb4e2d895cd70e4ff6479f64d7ba39fa34ecbf0af48e32d75c3c5fe97642f566edf0007e23ab3ec0c8ea921140bbc62614ecda
+  data.tar.gz: 91a342991a7a3859e6664b94bd73282fe1d3892226de023372243325bb3a2f738c580575126e0fda360298b310b8b36eed00118165540331f24c9591450add7f

data/README.md

@@ -154,6 +154,22 @@ client.people.identifiers.add("app-77", "crm-p5")
 client.people.identifiers.remove("app-77", "crm-p5")
 ```
 
+### Ler os identificadores da pessoa (para reconciliar)
+
+`client.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**.
+
+```ruby
+ids = client.people.identifiers.list("crm-p5") # o id extra que "sumiu" da listagem
+ids["external_id"]                             # => "app-77" — o principal do cadastro
+ids["identifiers"].each { |i| puts "#{i['external_id']} #{i['label']} #{i['source']}" }
+```
+
 ## Pessoas
 
 As pessoas (usuários do seu sistema) de cada cliente, em `client.people`. O `external_id` da pessoa
@@ -174,10 +190,111 @@ client.people.upsert("erp-1042", "app-77", access: true) # devolve o acesso
 
 - **Nunca duplica.** O e-mail (ou o telefone) acha a pessoa que já chegou por e-mail, pelo widget
   ou por outro sistema, e ela é **adotada** (ganha o seu `external_id`).
-- A mesma pessoa enviada com **outro cliente** é **transferida** para ele.
+- A mesma pessoa enviada com **outro cliente** NÃO é transferida: fica **ligada** também a ele
+  (`"linked" => true` na resposta). O cadastro é único e a mesma pessoa circula por vários clientes.
+- **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`
-  (contato principal), `extra_emails`, `extra_phones`.
+  (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`.
+
+### 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.
+
+```ruby
+pessoa = client.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" }
+  ]
+)
+pessoa["custom_fields"].each do |campo|
+  puts "#{campo['key']} #{campo['value']} #{campo['visibility']}" # visibility vem do bFocus
+end
+```
+
+### 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.
+
+```ruby
+client.people.upsert("erp-1042", "app-77", clear: ["phone"])          # some o telefone
+client.people.upsert("erp-1042", "app-77", clear: %w[email phone])    # somem os dois
+```
+
+Três regras que parecem contraintuitivas e são de propósito:
+
+- **Apagar é explícito.** `phone: nil`, `clear: []` e não passar o argumento continuam significando
+  **"não mexe"** — a SDK não traduz `nil` em `clear`. Fazer o `nil` apagar teria apagado, em
+  silêncio e na primeira carga seguinte, o dado de todo sistema que manda `nil` 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` (`Bfocus::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` (`Bfocus::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 `client.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 `error.data` (a API repete o mesmo
+detalhe em `error.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.
+
+```ruby
+begin
+  client.people.upsert("erp-1042", "app-77", name: "Paula Reis", email: "paula@padaria.example")
+rescue Bfocus::ConflictError => e
+  raise unless %w[PERSON_EMAIL_TAKEN PERSON_PHONE_TAKEN].include?(e.code)
+
+  dono = e.data
+  if dono["owner_customer_external_id"] == "erp-1042"
+    # A mesma pessoa, com dois ids: o seu vira mais um identificador dela.
+    client.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(e.code, dono)
+  end
+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.
 
 ## Lotes — `customers.batch` e `people.batch`
 
@@ -410,10 +527,10 @@ Todos são `Hash` com chaves string (campos novos podem aparecer a qualquer mome
 | Contato (`customers.contacts.*`) | `id`, `external_id`, `name`, `role`, `email`, `phone`, `notes`, `is_primary`, `created_at`, `updated_at` |
 | Produto vinculado (`customers.products.*`) | `id`, `slug`, `name`, `is_active` |
 | Interação (`customers.interactions.*`) | `id`, `content`, `is_internal`, `author_kind`, `author_name`, `created_at` |
-| Pessoa (`people.list`, `delete`) | `external_id` (pode ser `nil`), `name`, `email`, `phone`, `role`, `access`, `is_primary`, `customer_external_id` |
+| Pessoa (`people.list`, `delete`) | `external_id` (pode ser `nil`), `name`, `email`, `phone`, `role`, `access`, `is_primary`, `customer_external_id`, `custom_fields` (lista de `{key, label, value, visibility}`) |
 | Pessoa gravada (`people.upsert`) | a pessoa + `status` (`created`/`updated`/`unchanged`) |
 | Cliente com identificadores (`customers.identifiers.add`, `remove`) | o cliente + `identifiers` (lista de `{external_id, label, source}`) |
-| Identificadores da pessoa (`people.identifiers.add`, `remove`) | `external_id`, `identifiers` (lista de `{external_id, label, source}`) |
+| Identificadores da pessoa (`people.identifiers.list`, `add`, `remove`) | `external_id`, `identifiers` (lista de `{external_id, label, source}`) |
 | Lote (`customers.batch`, `people.batch`) | `results` (lista de `{index, status, external_id, merged_into, error, code}`; `status` ∈ `created`/`updated`/`unchanged`/`error`), `summary` (`{created, updated, unchanged, error}`) |
 | Produto (`products.*`) | `id`, `slug`, `name`, `description`, `color`, `icon`, `is_active`, `sort_order`, `current_version`, `ai_level`, `created_at`, `updated_at` |
 | Release note (`release_notes.*`) | `id`, `product`, `version`, `title`, `description_html`, `audience`, `is_published`, `require_ack_internal`, `require_ack_external`, `published_at`, `created_at`, `updated_at` |
@@ -440,7 +557,10 @@ Qualquer resposta fora de 2xx levanta `Bfocus::Error` (ou uma subclasse):
 | `Bfocus::ServerError` | 5xx |
 | `Bfocus::NetworkError` | conexão/timeout — `status == 0`, `code == "NETWORK_ERROR"` |
 
-Todas têm `code`, `status`, `request_id`, `validation`, `retry_after`, `required_scope` e `body`.
+Todas têm `code`, `status`, `request_id`, `validation`, `data`, `retry_after`, `required_scope` e
+`body`. O `data` é o `data` do corpo: 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`,
 `MODULE_NOT_CONTRACTED`, `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

data/lib/bfocus/errors.rb

@@ -21,6 +21,12 @@ module Bfocus
     attr_reader :request_id
     # @return [Hash{String=>String}] motivos por campo (erros de validação); `{}` quando não há.
     attr_reader :validation
+    # @return [Hash] 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 {#validation}, por compatibilidade com as SDKs que ainda não expunham `data`.
+    attr_reader :data
     # @return [Integer, Float, nil] segundos do header `Retry-After` (só em 429).
     attr_reader :retry_after
     # @return [String, nil] escopo que faltou na chave (header `X-Required-Scope`, só em 403).
@@ -29,11 +35,12 @@ module Bfocus
     attr_reader :body
 
     def initialize(message = nil, code: nil, status: 0, request_id: nil, validation: nil,
-                   retry_after: nil, required_scope: nil, body: nil)
+                   retry_after: nil, required_scope: nil, body: nil, data: nil)
       @code = code
       @status = status
       @request_id = request_id
       @validation = validation.is_a?(Hash) ? validation.dup : {}
+      @data = data.is_a?(Hash) ? data.dup : {}
       @retry_after = retry_after
       @required_scope = required_scope
       @body = body

data/lib/bfocus/resources/people.rb

@@ -8,6 +8,21 @@ module Bfocus
     # Retorno: `{"external_id", "identifiers" => [{"external_id", "label", "source"}, …]}`.
     # Id que já pertence a outro cadastro: `ConflictError` com `code == "IDENTIFIER_IN_USE"`.
     class PersonIdentifiers < Base
+      # Todos os identificadores da pessoa: o principal (`"external_id"` do retorno) e os extras.
+      # `GET /people/{person_external_id}/identifiers` (escopo `customers:read`). Aceita no
+      # caminho o principal OU qualquer um dos extras.
+      #
+      # É a fonte de verdade para RECONCILIAR: {People#list} mostra só o identificador principal,
+      # então um id que virou extra some de lá sem ter sumido do cadastro — e, sem esta leitura,
+      # era preciso ESCREVER (tentar um {#add}) para descobrir o que tinha acontecido.
+      #
+      # @return [Hash]
+      # @raise [Bfocus::NotFoundError] `PERSON_NOT_FOUND`.
+      def list(person_external_id, timeout: nil)
+        call("GET", "/people/#{segment(person_external_id, 'person_external_id')}/identifiers",
+             timeout: timeout)
+      end
+
       # Liga `extra_id` à pessoa (idempotente). `PUT /people/{person_external_id}/identifiers/{extra_id}`
       #
       # @param label [String, nil] rótulo livre. Não informado = sem corpo.
@@ -35,7 +50,8 @@ module Bfocus
     #
     # Pessoa: `"external_id"` (pode ser `nil` para quem chegou por e-mail/widget sem id),
     # `"name"`, `"email"`, `"phone"`, `"role"`, `"access"`, `"is_primary"`,
-    # `"customer_external_id"`. O `upsert` devolve também `"status"`
+    # `"customer_external_id"` e `"custom_fields"` (lista de `{"key", "label", "value",
+    # "visibility"}`). O `upsert` devolve também `"status"`
     # (`"created"`/`"updated"`/`"unchanged"`).
     #
     # O `external_id` da pessoa é o mesmo `user_external_id` assinado no widget — por isso não
@@ -53,22 +69,38 @@ module Bfocus
       # `PUT /customers/{customer_external_id}/people/{person_external_id}`
       #
       # Só o que vier muda; `nil` limpa. O e-mail (ou telefone) acha a pessoa que já chegou por
-      # outro caminho e ela é adotada, nunca duplicada; se ela estava em outro cliente, é
-      # transferida. `access: true` devolve o acesso retirado por {#delete}.
+      # outro caminho e ela é adotada, nunca duplicada. Se ela já existia em OUTRO cliente, NÃO é
+      # transferida: fica ligada também a este (cadastro único, `"linked" => true` na resposta).
+      # `access: true` devolve o acesso retirado por {#delete}.
       #
       # @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.
       # @param extra_phones [Array<String>] telefones adicionais.
-      # @return [Hash] a pessoa + `"status"`.
+      # @param custom_fields [Array<Hash>] campos personalizados (`{"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 ficar de fora é REMOVIDO. Não passar o
+      #   argumento não mexe em nada. A visibilidade é decidida no bFocus e preservada entre
+      #   sincronizações.
+      # @param clear [Array<String>] campos a APAGAR nesta pessoa: `["email"]`, `["phone"]` ou os
+      #   dois. Apagar é EXPLÍCITO: `phone: nil`, `clear: []` e não passar o argumento continuam
+      #   significando "não mexe" — a SDK não traduz `nil` em `clear`. Campo fora da lista aceita
+      #   é RECUSADO pela API (422 `PERSON_CLEAR_FIELD_INVALID`), não ignorado; e só se limpa a
+      #   PRÓPRIA ficha: alcançando 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.
+      # @return [Hash] a pessoa + `"status"`, `"linked"` (já existia em outro cliente e agora está
+      #   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,
-                 idempotency_key: nil, timeout: nil)
+                 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,
-          "is_primary" => is_primary, "extra_emails" => extra_emails, "extra_phones" => extra_phones
+          "is_primary" => is_primary, "extra_emails" => extra_emails, "extra_phones" => extra_phones,
+          "custom_fields" => custom_fields, "clear" => clear
         )
         call("PUT", "/customers/#{cid}/people/#{pid}",
              body: { "person" => person }, idempotency_key: idempotency_key, timeout: timeout)
@@ -81,9 +113,13 @@ module Bfocus
              timeout: timeout)
       end
 
-      # Retira o acesso da pessoa (ela continua no histórico).
+      # Retira o acesso da pessoa NESTE cliente (ela continua no histórico).
       # `DELETE /customers/{customer_external_id}/people/{person_external_id}`
-      # @return [Hash] a pessoa, com `"access" => false`.
+      #
+      # O acesso é DO VÍNCULO: a mesma pessoa circula por vários clientes e tirar o acesso aqui
+      # não tira o dela nos outros.
+      # @return [Hash] a pessoa, com `"access" => false` e `"unlinked"` (`true` = ela segue ativa
+      #   em outros clientes; `false` = era só deste e foi desligada).
       def delete(customer_external_id, person_external_id, idempotency_key: nil, timeout: nil)
         cid = segment(customer_external_id, "customer_external_id")
         pid = segment(person_external_id, "person_external_id")

data/lib/bfocus/transport.rb

@@ -211,6 +211,7 @@ module Bfocus
       human = nil
       request_id = nil
       validation = {}
+      data = {}
 
       if payload.is_a?(Hash)
         err = payload["error"]
@@ -222,6 +223,10 @@ module Bfocus
         end
         human = msg if msg.is_a?(String) && !msg.empty? && msg != code
         validation = payload["validation"] if payload["validation"].is_a?(Hash)
+        # `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.
+        data = payload["data"] if payload["data"].is_a?(Hash)
         rid = payload["request_id"]
         request_id = rid if rid.is_a?(String) && !rid.empty?
       elsif !text.strip.empty?
@@ -247,6 +252,7 @@ module Bfocus
         status: status,
         request_id: request_id,
         validation: validation,
+        data: data,
         retry_after: retry_after,
         required_scope: required_scope,
         body: payload.nil? ? present(text) : payload

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.0"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bfocus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Berni Software
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-19 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies: []
 description: Clientes, produtos, release notes, base de conhecimento e agentes de
   IA do bFocus. Zero dependências de runtime, novas tentativas e idempotência automáticas.