bfocus 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 427efa66516864dfd256464bb24bbda1dad9dae5d4c4df4da9b7e5f1c4cd7d7c
-  data.tar.gz: aff4271f81c03da6ffb70e16860e594f7e6428d582d79ea56fe31cfd783f472e
+  metadata.gz: 3daefe09e7aa1fed098c71ffdbc8f0b43c020519b72031355aac21a8b16011ed
+  data.tar.gz: a21b02db9aff17837cf93cc6063b16324e4593382543fa7c1c0eedd032d916a9
 SHA512:
-  metadata.gz: 837084970aaf2a9ee8e4f383c74787021773a0057081ea60f8adf64512813a01abf860029d3333f5d0b624c540bfc3333367c6901f4677b8439f3b1c8d159505
-  data.tar.gz: f7a941f57940c96fc38c8d7b71dc97a545f4e8edf03d06b63c4b17da7a0c8cd6b8cc13b5220a5d1f4530fa38c2f021e88c41343831492aa11bb7a096a95ba7ab
+  metadata.gz: 111b5a2790952c3ba34c11d7d7f8d101b620b3e44b1869730d6663daf97a2f28c27880febb48aca95e3112f41e9159ba5c2174986d7242ad4b242f9ab8ff15c0
+  data.tar.gz: 8a8ee123b356b52e8c8fbfeded349d168bdad83c39a010e3328b7635a0424e13f5413295e2c991e4a9a82fe3444c3200cc0fbbe471c82132468a548ac02c0e02

data/README.md

@@ -1,7 +1,7 @@
 # bfocus
 
-SDK oficial em **Ruby** da API pública do [bFocus](https://bfocus.com.br): clientes, produtos,
-release notes, base de conhecimento e agentes de IA.
+SDK oficial em **Ruby** da API pública do [bFocus](https://bfocus.com.br): clientes, pessoas,
+produtos, release notes, base de conhecimento e agentes de IA.
 
 Zero dependências de runtime (só biblioteca padrão: `net/http`, `json`, `openssl`,
 `securerandom`) · Ruby 3.0+ · novas tentativas e idempotência automáticas.
@@ -93,8 +93,8 @@ Construir o cliente não faz nenhuma chamada de rede. O cliente não guarda esta
   escrita aceitam `idempotency_key:` (veja [Novas tentativas](#novas-tentativas-e-idempotência)).
 - Datas (`updated_since`) aceitam `Time`/`DateTime` — convertidos para ISO 8601 em UTC com `Z` —,
   `Date` (meia-noite UTC) ou string, que passa como veio.
-- Hashes de entrada (`custom_fields`, itens do `batch_upsert`, `history`) aceitam chaves símbolo
-  ou string.
+- Hashes de entrada (`custom_fields`, itens do `batch_upsert`/`customers.batch`/`people.batch`,
+  `history`) aceitam chaves símbolo ou string.
 
 ## Clientes
 
@@ -139,6 +139,257 @@ client.customers.interactions.list_all("ERP 1042").each do |i|
 end
 ```
 
+### Identificadores extras
+
+Ligue o id de **outro sistema seu** (CRM, loja, app…) ao mesmo cadastro: depois disso o cliente (ou
+a pessoa) é encontrado por qualquer um dos ids. É idempotente (ligar de novo não muda nada). Se o id
+já pertence a outro cadastro, a API recusa com `Bfocus::ConflictError` e `code == "IDENTIFIER_IN_USE"`.
+
+```ruby
+cliente = client.customers.identifiers.add("erp-1042", "crm-88", label: "CRM") # label é opcional
+cliente["identifiers"] # => [{"external_id" => "crm-88", "label" => "CRM", "source" => "api"}]
+client.customers.identifiers.remove("erp-1042", "crm-88")
+
+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
+é o mesmo `user_external_id` que você assina para o [widget](#identidade-do-widget).
+
+```ruby
+pessoa = client.people.upsert(
+  "erp-1042", "app-77",
+  name: "Paula Reis", email: "paula@padaria.example", role: "Financeiro", is_primary: true,
+  extra_emails: ["paula.reis@pessoal.example"]
+)
+pessoa["status"] # => "created", "updated" ou "unchanged"
+
+client.people.list("erp-1042")            # todas as pessoas do cliente
+client.people.delete("erp-1042", "app-77") # retira o acesso; a pessoa continua no histórico
+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.
+- 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`, `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`
+
+Até **500 itens por chamada** (`Bfocus::BATCH_MAX`). Acima disso a SDK lança `ArgumentError` antes
+de qualquer requisição — ela não divide sozinha, porque o `index` de cada resultado é a posição no
+lote que **você** enviou. Divida assim:
+
+```ruby
+clientes = meus_clientes.map do |c|
+  { external_id: "erp-#{c.id}", name: c.nome, document: c.cnpj, email: c.email }
+end
+
+clientes.each_slice(Bfocus::BATCH_MAX) do |fatia|
+  resultado = client.customers.batch(fatia)
+  resultado["results"].each do |item|
+    next unless item["status"] == "error"
+
+    warn "#{fatia[item['index']][:external_id]}: #{item['error']} (HTTP #{item['code']})"
+  end
+end
+```
+
+- Cada item de `customers.batch` é `external_id` + os campos do `customers.upsert`.
+- Cada item de `people.batch` é **plano**: `customer_external_id` + `external_id` (da pessoa) + os
+  campos do `people.upsert`.
+- Retorno: `results` (um por item: `index`, `status` — `created`/`updated`/`unchanged`/`error` —,
+  `external_id`, `merged_into`, `error` com o código estável e `code` com o status HTTP do item) +
+  `summary` (`created`, `updated`, `unchanged`, `error`).
+- **Um erro não desfaz os outros**: confira `summary["error"]` e registre os itens com erro.
+- Lista vazia devolve o resultado zerado sem fazer requisição.
+- `idempotency_key:` vale para o lote inteiro (um lote = uma chamada).
+
+## Sincronizar clientes e usuários do seu sistema
+
+**Ids com o prefixo do sistema, sem `:`.** Use `-` como separador — `erp-1042` para clientes,
+`app-77` para pessoas — ou UUIDs puros: vários sistemas seus convivem no mesmo bFocus sem colisão. A
+assinatura do widget recusa `:` (é o separador dela), então não use `:` em nenhum `external_id` de
+cliente ou pessoa.
+
+**Carga inicial (no deploy):** clientes em fatias de 500 → vincule cada um ao produto → pessoas em
+fatias de 500.
+
+```ruby
+def carga_inicial(client, clientes, usuarios)
+  clientes.each_slice(Bfocus::BATCH_MAX) do |fatia|
+    r = client.customers.batch(fatia.map { |c| { external_id: "erp-#{c.id}", name: c.nome } })
+    registrar_erros(r, fatia) if r["summary"]["error"].positive?
+  end
+
+  clientes.each { |c| client.customers.products.attach("erp-#{c.id}", "erp-cloud") }
+
+  usuarios.each_slice(Bfocus::BATCH_MAX) do |fatia|
+    itens = fatia.map do |u|
+      { customer_external_id: "erp-#{u.cliente_id}", external_id: "app-#{u.id}",
+        name: u.nome, email: u.email }
+    end
+    r = client.people.batch(itens)
+    registrar_erros(r, fatia) if r["summary"]["error"].positive?
+  end
+end
+```
+
+**Depois, no dia a dia**, espelhe cada evento do seu sistema:
+
+| No seu sistema | No bFocus |
+| --- | --- |
+| criou/alterou cliente | `customers.upsert` |
+| criou/alterou usuário | `people.upsert` |
+| excluiu/desativou usuário | `people.delete` |
+| excluiu cliente | `customers.delete` |
+
+Vincule o cliente ao produto com `customers.products.attach`. Se a resposta trouxer `merged_into`,
+o cadastro foi unificado em outro: atualize o id do seu lado.
+
+**Nunca bloqueie a requisição do seu usuário esperando o bFocus.** Enfileire (job/outbox) e tente de
+novo com backoff; a SDK já repete 429/5xx com a mesma `Idempotency-Key`, e a fila cobre
+indisponibilidades longas.
+
+```ruby
+# app/jobs/bfocus_sync_usuario_job.rb (ActiveJob; o mesmo vale para Sidekiq etc.)
+class BfocusSyncUsuarioJob < ApplicationJob
+  retry_on Bfocus::NetworkError, Bfocus::RateLimitError, Bfocus::ServerError,
+           wait: :polynomially_longer, attempts: 10
+
+  def perform(usuario_id)
+    u = Usuario.find(usuario_id)
+    if u.ativo?
+      BFOCUS.people.upsert("erp-#{u.cliente_id}", "app-#{u.id}", name: u.nome, email: u.email)
+    else
+      BFOCUS.people.delete("erp-#{u.cliente_id}", "app-#{u.id}")
+    end
+  end
+end
+
+# no model, depois de salvar — a requisição do usuário não espera o bFocus:
+after_commit { BfocusSyncUsuarioJob.perform_later(id) }
+```
+
 ## Produtos
 
 ```ruby
@@ -273,6 +524,11 @@ 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`, `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.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` |
 | Artigo — resumo (`kb.articles.list`, `list_all`) | `id`, `external_id`, `product`, `title`, `excerpt`, `status`, `origin`, `published_at`, `created_at`, `updated_at` |
@@ -298,7 +554,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
@@ -374,6 +633,28 @@ assinatura = Bfocus.sign_widget_identity(
 # que abre o widget.
 ```
 
+### Identidade do widget v2 (com validade)
+
+A v2 carimba o instante na assinatura, então uma assinatura vazada deixa de valer sozinha:
+
+```ruby
+user_hash = Bfocus.sign_widget_identity_v2(
+  ENV.fetch("BFOCUS_WIDGET_SECRET"),
+  "app-77",   # user_external_id: sem ":" (é o separador; a API recusa)
+  "erp-1042"  # customer_external_id: a empresa dele
+)
+# => "v2.<ts>.<hex>", ex.: "v2.1789000000.9c1e…"
+
+# instante explícito (segundos unix, não ms; ou Time) — útil em testes:
+Bfocus.sign_widget_identity_v2(segredo, "app-77", "erp-1042", now: 1_789_000_000)
+```
+
+- `hex` = HMAC-SHA256 em hex minúsculo de `"v2:<ts>:<user_external_id>:<customer_external_id>"`.
+- Vale de **7 dias atrás até 5 minutos à frente**: gere a cada renderização da página, **nunca
+  guarde**. Vai no mesmo lugar da v1 (`userHash` do widget).
+- O id do usuário não pode ter `:` (`ArgumentError`) — use `-` como separador (`app-77`).
+- A v1 continua aceita.
+
 ## Versões
 
 **Fixe a versão exata** (`gem "bfocus", "0.1.0"` no `Gemfile`) e suba de uma versão para a outra

data/lib/bfocus/client.rb

@@ -11,8 +11,10 @@ module Bfocus
   #   client.customers.upsert("ERP 1042", name: "Padaria Estrela")
   class Client
     # @return [Resources::Customers] clientes (empresas), com `.contacts`, `.products` e
-    #   `.interactions`.
+    #   `.interactions` e `.identifiers`.
     attr_reader :customers
+    # @return [Resources::People] pessoas (usuários) dos clientes, com `.identifiers`.
+    attr_reader :people
     # @return [Resources::Products] catálogo de produtos.
     attr_reader :products
     # @return [Resources::ReleaseNotes] release notes por produto.
@@ -52,6 +54,7 @@ module Bfocus
       @transport = Transport.new(api_key, base_url: url, timeout: timeout,
                                           max_retries: max_retries, sleeper: sleeper)
       @customers = Resources::Customers.new(@transport)
+      @people = Resources::People.new(@transport)
       @products = Resources::Products.new(@transport)
       @release_notes = Resources::ReleaseNotes.new(@transport)
       @kb = Resources::KnowledgeBase.new(@transport)

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/base.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Bfocus
-  # Recursos da API pública: `customers`, `products`, `release_notes`, `kb`, `ai_agents`.
+  # Máximo de itens por chamada de `customers.batch` e `people.batch`. Acima disso a SDK lança
+  # `ArgumentError` antes de qualquer requisição — ela NÃO divide sozinha, porque o `"index"` de
+  # cada resultado é a posição no lote que você enviou. Divida com `each_slice(Bfocus::BATCH_MAX)`.
+  BATCH_MAX = 500
+
+  # Recursos da API pública: `customers`, `people`, `products`, `release_notes`, `kb`, `ai_agents`.
   #
   # Convenções (iguais em todos os métodos):
   #
@@ -61,6 +66,42 @@ module Bfocus
       def compact(fields)
         Codec.compact(fields)
       end
+
+      # Resultado de um lote vazio (sem requisição).
+      def empty_batch_result
+        { "results" => [], "summary" => { "created" => 0, "updated" => 0, "unchanged" => 0, "error" => 0 } }
+      end
+
+      # Valida a lista de um lote (`customers.batch`/`people.batch`) antes de qualquer
+      # requisição e devolve os itens como Hash de chaves string (sem {UNSET}).
+      # @raise [TypeError] não é lista ou item não é Hash.
+      # @raise [ArgumentError] mais de {Bfocus::BATCH_MAX} itens.
+      def batch_items(items, op)
+        if items.is_a?(Hash) || !items.respond_to?(:each_with_index) || !items.respond_to?(:size)
+          raise TypeError, "#{op}: items precisa ser uma lista de Hash."
+        end
+        if items.size > BATCH_MAX
+          raise ArgumentError, "#{op} aceita até #{BATCH_MAX} itens por chamada (recebeu #{items.size}); " \
+                               "divida em lotes de #{BATCH_MAX}."
+        end
+
+        items.each_with_index.map do |item, index|
+          raise TypeError, "#{op}: items[#{index}] precisa ser um Hash." unless item.is_a?(Hash)
+
+          item.each_with_object({}) do |(key, value), out|
+            out[key.to_s] = value unless value.equal?(UNSET)
+          end
+        end
+      end
+
+      # Campo de id obrigatório num item de lote: String (ou número) não vazia.
+      # @raise [ArgumentError]
+      def batch_id!(item, field, op, index)
+        value = item[field]
+        return value unless value.nil? || value.to_s.empty?
+
+        raise ArgumentError, "#{op}: items[#{index}].#{field} é obrigatório."
+      end
     end
   end
 end

data/lib/bfocus/resources/customers.rb

@@ -101,8 +101,37 @@ module Bfocus
       end
     end
 
+    # Identificadores extras de um cliente — `client.customers.identifiers`: liga o id de OUTRO
+    # sistema seu (CRM, loja…) ao mesmo cadastro, que passa a ser encontrado por qualquer um deles.
+    #
+    # Retorno: o cliente + `"identifiers"` (lista de `{"external_id", "label", "source"}`).
+    # Id que já pertence a outro cadastro: `ConflictError` com `code == "IDENTIFIER_IN_USE"`.
+    class CustomerIdentifiers < Base
+      # Liga `extra_id` ao cliente (idempotente).
+      # `PUT /customers/{external_id}/identifiers/{extra_id}`
+      #
+      # @param label [String, nil] rótulo livre (ex.: `"CRM"`). Não informado = sem corpo.
+      # @return [Hash] o cliente com `"identifiers"`.
+      def add(external_id, extra_id, label: UNSET, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        extra = segment(extra_id, "extra_id")
+        body = label.equal?(UNSET) ? nil : { "label" => label }
+        call("PUT", "/customers/#{ext}/identifiers/#{extra}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Desliga `extra_id` do cliente. `DELETE /customers/{external_id}/identifiers/{extra_id}`
+      # @return [Hash] o cliente com `"identifiers"`.
+      def remove(external_id, extra_id, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        extra = segment(extra_id, "extra_id")
+        call("DELETE", "/customers/#{ext}/identifiers/#{extra}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
     # Clientes (empresas) — `client.customers`. Sub-recursos: {#contacts}, {#products},
-    # {#interactions}.
+    # {#interactions}, {#identifiers}.
     #
     # Cliente: `"id"`, `"external_id"`, `"name"`, `"document"`, `"email"`, `"phone"`,
     # `"website"`, `"notes"`, `"custom_fields"` (lista de `{"key", "label", "type", "value",
@@ -114,12 +143,15 @@ module Bfocus
       attr_reader :products
       # @return [CustomerInteractions]
       attr_reader :interactions
+      # @return [CustomerIdentifiers]
+      attr_reader :identifiers
 
       def initialize(transport)
         super
         @contacts = CustomerContacts.new(transport)
         @products = CustomerProducts.new(transport)
         @interactions = CustomerInteractions.new(transport)
+        @identifiers = CustomerIdentifiers.new(transport)
       end
 
       # Cria ou atualiza um cliente pelo `external_id` do seu sistema. `PUT /customers/{external_id}`
@@ -137,6 +169,31 @@ module Bfocus
         call("PUT", "/customers/#{ext}", body: body, idempotency_key: idempotency_key, timeout: timeout)
       end
 
+      # Cria/atualiza até {Bfocus::BATCH_MAX} (500) clientes numa chamada. `POST /customers/batch`
+      #
+      # Cada item (Hash, chaves string ou símbolo) tem `external_id` (obrigatório) e os mesmos
+      # campos do {#upsert}, com a mesma regra: ausente = não muda; `nil` limpa.
+      #
+      # A SDK **não divide** o lote: mais de 500 itens lança `ArgumentError` antes de qualquer
+      # requisição (use `items.each_slice(Bfocus::BATCH_MAX)`); o `"index"` de cada resultado é
+      # a posição no lote enviado. Um item com erro não desfaz os outros. Lista vazia devolve o
+      # resultado zerado sem chamar a API.
+      #
+      # @return [Hash] `{"results" => [{"index", "status", "external_id", "merged_into", "error",
+      #   "code"}, …], "summary" => {"created", "updated", "unchanged", "error"}}` —
+      #   `"status"` ∈ `created`/`updated`/`unchanged`/`error`; `"error"` é o código estável e
+      #   `"code"` o status HTTP do item.
+      # @raise [ArgumentError] mais de 500 itens ou item sem `external_id`.
+      # @raise [TypeError] `items` não é lista de Hash.
+      def batch(items, idempotency_key: nil, timeout: nil)
+        list = batch_items(items, "customers.batch")
+        return empty_batch_result if list.empty?
+
+        list.each_with_index { |item, index| batch_id!(item, "external_id", "customers.batch", index) }
+        call("POST", "/customers/batch",
+             body: { "items" => list }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
       # Um cliente. `GET /customers/{external_id}`
       # @return [Hash]
       def get(external_id, timeout: nil)

data/lib/bfocus/resources/people.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Identificadores extras de uma pessoa — `client.people.identifiers`: liga o id de OUTRO
+    # sistema seu ao mesmo cadastro.
+    #
+    # 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.
+      # @return [Hash]
+      def add(person_external_id, extra_id, label: UNSET, idempotency_key: nil, timeout: nil)
+        pid = segment(person_external_id, "person_external_id")
+        extra = segment(extra_id, "extra_id")
+        body = label.equal?(UNSET) ? nil : { "label" => label }
+        call("PUT", "/people/#{pid}/identifiers/#{extra}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Desliga `extra_id` da pessoa. `DELETE /people/{person_external_id}/identifiers/{extra_id}`
+      # @return [Hash]
+      def remove(person_external_id, extra_id, idempotency_key: nil, timeout: nil)
+        pid = segment(person_external_id, "person_external_id")
+        extra = segment(extra_id, "extra_id")
+        call("DELETE", "/people/#{pid}/identifiers/#{extra}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
+    # Pessoas (usuários do seu sistema) de um cliente — `client.people`. Sub-recurso:
+    # {#identifiers}.
+    #
+    # 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"` 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
+    # pode ter `:` (use outro separador, ex.: `"app-77"`).
+    class People < Base
+      # @return [PersonIdentifiers]
+      attr_reader :identifiers
+
+      def initialize(transport)
+        super
+        @identifiers = PersonIdentifiers.new(transport)
+      end
+
+      # Cria ou atualiza uma pessoa do cliente pelo `external_id` dela.
+      # `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}.
+      #
+      # @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.
+      # @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"`.
+      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,
+                 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,
+          "custom_fields" => custom_fields, "clear" => clear
+        )
+        call("PUT", "/customers/#{cid}/people/#{pid}",
+             body: { "person" => person }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Pessoas do cliente. `GET /customers/{customer_external_id}/people`
+      # @return [Array<Hash>]
+      def list(customer_external_id, timeout: nil)
+        call("GET", "/customers/#{segment(customer_external_id, 'customer_external_id')}/people",
+             timeout: timeout)
+      end
+
+      # Retira o acesso da pessoa (ela continua no histórico).
+      # `DELETE /customers/{customer_external_id}/people/{person_external_id}`
+      # @return [Hash] a pessoa, com `"access" => false`.
+      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")
+        call("DELETE", "/customers/#{cid}/people/#{pid}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Cria/atualiza até {Bfocus::BATCH_MAX} (500) pessoas numa chamada. `POST /people/batch`
+      #
+      # Cada item (Hash plano, chaves string ou símbolo): `customer_external_id` e `external_id`
+      # (da pessoa), ambos obrigatórios, + os campos do {#upsert} (ausente = não muda; `nil`
+      # limpa). No fio vira `{"customer_external_id" => …, "person" => {"external_id" => …, …}}`.
+      #
+      # A SDK **não divide** o lote: mais de 500 itens lança `ArgumentError` antes de qualquer
+      # requisição (use `items.each_slice(Bfocus::BATCH_MAX)`); o `"index"` de cada resultado é
+      # a posição no lote enviado. Um item com erro não desfaz os outros. Lista vazia devolve o
+      # resultado zerado sem chamar a API.
+      #
+      # @return [Hash] `{"results" => [{"index", "status", "external_id", "merged_into", "error",
+      #   "code"}, …], "summary" => {"created", "updated", "unchanged", "error"}}`
+      # @raise [ArgumentError] mais de 500 itens ou item sem `customer_external_id`/`external_id`.
+      # @raise [TypeError] `items` não é lista de Hash.
+      def batch(items, idempotency_key: nil, timeout: nil)
+        list = batch_items(items, "people.batch")
+        return empty_batch_result if list.empty?
+
+        wire = list.each_with_index.map do |item, index|
+          customer = batch_id!(item, "customer_external_id", "people.batch", index)
+          batch_id!(item, "external_id", "people.batch", index)
+          { "customer_external_id" => customer, "person" => item.reject { |key, _| key == "customer_external_id" } }
+        end
+        call("POST", "/people/batch",
+             body: { "items" => wire }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+  end
+end

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.1.0"
+  VERSION = "0.2.1"
 end

data/lib/bfocus/widget.rb

@@ -27,4 +27,53 @@ module Bfocus
     message = "v1:".b + utf8.call(user_external_id) + ":".b + utf8.call(customer_external_id)
     OpenSSL::HMAC.hexdigest("SHA256", utf8.call(secret), message)
   end
+
+  # Identidade do widget **v2 (com validade)**: como {sign_widget_identity}, mas carimbada com o
+  # instante. Roda no seu backend, sem rede e sem chave de API.
+  #
+  # Devolve `"v2.<ts>.<hex>"`: `ts` = segundos unix inteiros do instante (padrão: agora) e `hex`
+  # = HMAC-SHA256, em hexadecimal minúsculo, de
+  # `"v2:" + ts + ":" + user_external_id + ":" + customer_external_id` (UTF-8). A API aceita de
+  # 7 dias atrás até 5 minutos à frente — gere a cada renderização da página, nunca guarde. Vai
+  # no mesmo lugar da v1 (`userHash` do widget); a v1 continua aceita.
+  #
+  # @param secret [String] segredo de identidade do widget (painel do bFocus).
+  # @param user_external_id [String] `external_id` do usuário (a pessoa) no seu sistema — sem
+  #   `:` (é o separador; a API recusa).
+  # @param customer_external_id [String] `external_id` do cliente (empresa). Prefira `-` a `:` nos
+  #   seus ids (ex.: `"erp-1042"`).
+  # @param now [Integer, Time, nil] instante da assinatura: segundos unix (não ms) ou `Time`.
+  #   Padrão: agora.
+  # @return [String] `"v2.<ts>.<64 hex>"`.
+  # @raise [ArgumentError] segredo vazio, id `nil`, `:` no id do usuário, instante negativo ou de
+  #   tipo inválido.
+  #
+  # @example
+  #   Bfocus.sign_widget_identity_v2(ENV.fetch("BFOCUS_WIDGET_SECRET"), "app-77", "erp-1042")
+  #   # => "v2.<ts>.<hex>"
+  def self.sign_widget_identity_v2(secret, user_external_id, customer_external_id, now: nil)
+    raise ArgumentError, "sign_widget_identity_v2: secret é obrigatório." if secret.nil? || secret.to_s.empty?
+    raise ArgumentError, "sign_widget_identity_v2: user_external_id é obrigatório." if user_external_id.nil?
+    raise ArgumentError, "sign_widget_identity_v2: customer_external_id é obrigatório." if customer_external_id.nil?
+    if user_external_id.to_s.include?(":")
+      raise ArgumentError, "sign_widget_identity_v2: user_external_id não pode ter ':' (é o separador; " \
+                           "a API recusa) — use outro, ex.: \"app-77\": #{user_external_id.to_s.inspect}"
+    end
+
+    ts = case now
+         when nil then Time.now.to_i
+         when Time then now.to_i
+         when Integer then now
+         else
+           raise ArgumentError, "sign_widget_identity_v2: now precisa ser Integer (segundos unix) ou Time."
+         end
+    raise ArgumentError, "sign_widget_identity_v2: now não pode ser negativo (#{ts})." if ts.negative?
+
+    utf8 = lambda do |value|
+      text = value.to_s
+      (text.encoding == ::Encoding::BINARY ? text : text.encode(::Encoding::UTF_8)).b
+    end
+    message = "v2:#{ts}:".b + utf8.call(user_external_id) + ":".b + utf8.call(customer_external_id)
+    "v2.#{ts}.#{OpenSSL::HMAC.hexdigest('SHA256', utf8.call(secret), message)}"
+  end
 end

data/lib/bfocus.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SDK oficial em Ruby da API pública do bFocus: clientes, produtos, release notes, base de
+# SDK oficial em Ruby da API pública do bFocus: clientes, pessoas, produtos, release notes, base de
 # conhecimento e agentes de IA. Só biblioteca padrão (net/http, json, openssl, securerandom).
 #
 # @example
@@ -26,6 +26,7 @@ require_relative "bfocus/codec"
 require_relative "bfocus/transport"
 require_relative "bfocus/resources/base"
 require_relative "bfocus/resources/customers"
+require_relative "bfocus/resources/people"
 require_relative "bfocus/resources/products"
 require_relative "bfocus/resources/release_notes"
 require_relative "bfocus/resources/knowledge_base"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bfocus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 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.
@@ -28,6 +28,7 @@ files:
 - lib/bfocus/resources/base.rb
 - lib/bfocus/resources/customers.rb
 - lib/bfocus/resources/knowledge_base.rb
+- lib/bfocus/resources/people.rb
 - lib/bfocus/resources/products.rb
 - lib/bfocus/resources/release_notes.rb
 - lib/bfocus/transport.rb