sgp-sdk 1.2.0 → 2.0.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,234 @@
+# Changelog
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/); versionamento
+[SemVer](https://semver.org/lang/pt-BR/). `experimental.*` é a exceção declarada: pode mudar de forma
+incompatível em uma versão menor.
+
+## 2.0.0-beta.2 (2026-11-06)
+
+### Adicionado
+
+- `contracts.checkConnection(input)`: o veredito do SGP sobre a conexão (`POST /api/ura/verificaacesso/`,
+  form, com barra final). `contrato` ou `telefone`; `status_all: 1` e, pela documentação,
+  `status_filter` e `uracontato`; `protocolo_ura` **não** é oferecido (abre ocorrência: use
+  `occurrences.create`). **Declarada ESCRITA**: o fornecedor documenta que, em manutenção ativa, o SGP
+  abre uma ocorrência por padrão mesmo sem `protocolo_ura` (não testado). Nunca é repetida, uma falha
+  traz `effect` (em geral `"unknown"`), e o JSDoc recomenda `maintenance.list()` antes. `data` é
+  SEMPRE um array: o SGP devolve um array (com `status_all`), `[]` (contrato fora do filtro padrão) ou
+  um objeto único (contrato ativo sem `status_all`), que o SDK embrulha. Novo `CONNECTION_STATUS`
+  (0 nada checado, 1 online, 2 offline, 9 manutenção; só 1 e 2 observados). `login` é segredo;
+  `razaoSocial` e `cpfCnpj` são pessoais. Fora da `scripts/probe.ts`, por ser escrita.
+- `contracts.listServices(input?)`: serviços de um contrato com estado online e sessão
+  (`POST /api/suporte/contrato/list/`, form, com barra final). Um array com uma linha por serviço
+  (internet e TV); a linha online traz a sessão RADIUS (`rad_*`). Filtros do SGP: `contrato_id` e
+  `cliente_id` (exercitados), `cliente_nome`, `cliente_cpfcnpj`, `servico_login` (documentados).
+  **Exige ao menos um filtro**: sem filtro o SGP lista os serviços de todos os clientes com senhas em
+  texto claro, então o SDK recusa a chamada sem filtro (`INVALID_INPUT`, `attempts: 0`, nada enviado).
+  Normalizado por campo: ids em texto e contadores RADIUS
+  viram número, `contrato_status` vem aparado; `servico_id` numérico é exigido por linha. Login,
+  senha, MACs, IPs (inclusive IPv6 e NAS) e ids de sessão são segredos; nome, contato e endereço são
+  pessoais (`getSensitivity("contracts.listServices")`). Leitura: aceita `maxRetries`. A linha online
+  é reconstruída da forma mascarada de um contrato real (só tipos).
+- `occurrences.list(input?)`: lista ocorrências com suas ordens de serviço
+  (`POST /api/ura/ocorrencia/list/`, form). É o caminho do chamado até a OS: `ordens_servicos[].id`
+  (o `numero` da ocorrência é o `ocorrencia` da OS). Uma página, com a `paginacao` do SGP (`total`
+  nunca calculado; sem `total` numérico é `INVALID_RESPONSE`). **Exige ao menos um filtro**: sem
+  filtro o SGP lista as ocorrências de todos os clientes (até 1000), então o SDK recusa a chamada sem
+  filtro (`INVALID_INPUT`, `attempts: 0`, nada enviado); `offset` e `limit` sozinhos não contam. `contrato: 0` e texto vazio em filtro são recusados localmente. Nome, texto livre e
+  responsáveis são dados pessoais (`getSensitivity("occurrences.list")`). Leitura: aceita
+  `maxRetries`.
+- `maintenance.list()`: novo grupo `maintenance` (SGP "manutenção"), `GET /api/ura/manutencao/list/`,
+  sem filtro. Devolve **todos** os avisos, inclusive os inativos: o consumidor filtra por `ativa` e
+  pelo período. Array do SGP, sem envelope; sem dado de cliente. Leitura: aceita `maxRetries`.
+- `coverage.checkAddress(input)`: viabilidade por endereço (`POST /api/ura/viabilidade/`, form) com
+  os filtros do SGP (`cep`, `cidade`, `logradouro`, `bairro`, `numero_inicial`, `numero_final`; ao
+  menos um). Devolve o objeto do SGP como veio (observado `{ viabilidade: true }` e `{}`): **sem a
+  chave `viabilidade` é desconhecido, nunca "sem cobertura"**, e a resposta de "sem cobertura" nunca
+  foi observada. O endereço é dado pessoal. Leitura: aceita `maxRetries`.
+- `workOrders.get(input)`: uma OS por id (`POST /api/os/list/id/{id}`, form, sem barra final). O SGP
+  devolve um objeto plano de 72 campos (OS, cliente, contrato, endereço, plano e serviço), mantido
+  como veio; só `os_id` é exigido. **Traz senhas em texto claro**: `servico_password`,
+  `wan_password`, `wifi_password` e `wifi_password_5` (e login, MAC, IP do serviço e IP do NAS) são
+  segredos; nome, e-mail, contatos, endereço, texto livre e responsáveis são pessoais
+  (`getSensitivity("workOrders.get")`). Leitura: aceita `maxRetries`.
+- `workOrders.listComments(input)`: comentários de uma OS (`GET /api/os/{id}/comentario/list/`).
+  Array do SGP, sem envelope. Só `[]` foi observado: o formato dos itens vem da coleção do
+  fornecedor. Leitura: aceita `maxRetries`.
+- `coverage.listGateways()`: lista os gateways de mapa do provedor (`GET /api/ura/listgatewaymapa`).
+  O `id` de cada um é o `gateway` que `coverage.check` recebe, então não é mais preciso `request()`
+  para descobri-lo. Leitura: aceita `maxRetries`.
+- `services.addGeneric(input)` e `services.removeGeneric(input)`: serviço extra do tipo genérico
+  (`POST /api/servico/generico` e `DELETE /api/servico/generico/{servico_id}`), a rota que a TSMX
+  recomenda. Escritas, nunca repetidas. `planobase_id` é `PlanId` de um plano criado como genérico no
+  painel. Só uma exchange foi observada: o 400 de plano de outro tipo, que vira `REJECTED` com
+  `reason: "PLAN_NOT_GENERIC"` e `effect: "none"` (corpo reconstruído). O sucesso das duas rotas é
+  apenas documentado: `data` é o objeto JSON do SGP, sem campo assumido. Remover o único serviço do
+  contrato é recusado pelo SGP segundo o fornecedor, sem código de motivo por falta de corpo
+  observado.
+- `occurrences.create`: a recusa com HTTP 200 e `status: 0` cujo `msg` é "Data e hora de agendamento
+  inválida, formato esperado: AAAA-MM-DD HH:MM" (agendamento com segundos; captura bruta, observada uma
+  vez, cliente sintético) agora é `REJECTED` com `reason: "INVALID_SCHEDULE"` e `effect: "none"` (a
+  releitura de `occurrences.list({ contrato })` achou o mesmo total antes e depois: nada foi criado). Só
+  casa com `status` igual ao número 0 e `msg` em texto que começa por "Data e hora de agendamento
+  inválida" (aparado, sem diferenciar maiúsculas); qualquer outra recusa `status: 0` segue `REJECTED`
+  sem `reason` e com `effect: "unknown"`. O JSDoc passa a dizer que `data_hora_agendamento` tem de ser
+  exatamente `AAAA-MM-DD HH:MM` (o SDK não confere o formato: quem decide é o SGP) e registra o que se
+  observou: ocorrência sem `motivoos` é aceita e o SGP cria a OS mesmo assim, `status_encerrado: 1`
+  encerra ocorrência e OS, e encerrar uma OS de instalação (`motivoos` 10) não altera o status do
+  contrato. A fixture da recusa deixa de ser reconstruída.
+
+### Alterado
+
+- **Mudança de comportamento (versus beta.1): `cpfcnpj` canônico nas escritas que gravam o
+  documento**, `preRegistrations.create` e `crm.customers.create` (as leituras não mudam). O SDK
+  tira `.`, `-`, `/` e espaços e envia o documento na máscara da base: em `personType: "F"`, exatamente 11
+  dígitos viram `999.999.999-99`; em `"J"`, exatamente 14 alfanuméricos (12 letras ou dígitos e 2
+  dígitos, a regra da Receita) viram `AA.AAA.AAA/AAAA-99`, com as letras em maiúsculas. Entrada já na
+  máscara segue igual. **Qualquer outra entrada é recusada localmente**: `INVALID_INPUT`,
+  `attempts: 0`, `effect: "none"`, nada enviado, e `error.issues` traz `["cpfcnpj: expected ..."]`
+  (só o caminho e o formato esperado, nunca o valor). Isso inclui tamanho errado, caracteres
+  inválidos, letras em CPF ou nas 2 últimas posições do CNPJ, o tipo trocado (CNPJ em `F`, CPF em `J`)
+  e texto vazio. Só o formato: sem dígitos verificadores. Motivo: o pré-cadastro grava o documento
+  como recebido e o CRM compara com a forma formatada; um CPF só com dígitos escapou da checagem de
+  duplicidade e criou outro cliente. `error.issues` agora também aparece em `INVALID_INPUT` (só neste
+  caso). Ver MIGRATION, seção 8.
+- `preRegistrations.create`: o sucesso agora tipa os ids que o SGP devolveu numa captura
+  bruta (um cliente sintético): `precadastro_id` (`number`), `new_cliente_id` (`CustomerId`) e
+  `new_contrato_id` (`number`), todos opcionais e normalizados como os demais (texto numérico vira
+  número, `""` vira `null`, texto formatado sai de `data` com `warning`). **Não são invariantes**: os
+  registros mais antigos listam só `message` e o decoder da 1.x descartava chaves desconhecidas, então
+  não se sabe se os ids já eram enviados antes (a fixture só com `message` é reconstruída e fica como
+  segundo caso, documentado), e o SDK nunca inventa um id ausente; sem eles, releia por `customers.list({ cpfcnpj })`, como antes. Chaves
+  desconhecidas seguem preservadas. Versus beta.1 essas três chaves eram `unknown`: ver MIGRATION,
+  seção 8.
+- `crm.customers.create`: o 400 `errors.cpfcnpj` "Já existe um cliente com o CPF informado." (documento já cadastrado, captura bruta de um cliente sintético) agora é `REJECTED` com `reason: "DOCUMENT_ALREADY_REGISTERED"` (o mesmo de `preRegistrations.create`) e `effect: "none"`; qualquer outro erro de campo segue sem `reason`. O JSDoc foi corrigido: o SGP recusa documento já cadastrado em qualquer status (o status 6 inclusive); a exceção observada é um cliente com o documento gravado sem formatação (ex.: pré-cadastro só com dígitos), não detectado e duplicado; leia `customers.list({ cpfcnpj })` antes.
+- **Mudança de comportamento (versus beta.1): `invoices.list`**. `titulos[].valor`, `valorDesconto`,
+  `valorCorrigido`, `valorPago` e `valorPagoParcial` já eram `number | null` na beta.1; o tipo não muda.
+  Um `""` em `valor` (o SGP manda texto vazio quando não há valor) saía de `data` com um `warning` e agora
+  chega como `null`, nunca `0`. Ver MIGRATION, seção 8.
+- `crm.customers.create` e `preRegistrations.create`: o 400 de CPF com dígitos verificadores errados
+  (captura bruta de um cliente sintético, documento fictício) agora é `REJECTED` com
+  `reason: "DOCUMENT_INVALID"` e `effect: "none"` (releitura: nada foi criado). No CRM o corpo é
+  `{"errors":{"cpfcnpj":"CPF inválido."}}`; no pré-cadastro é `{"message":"CPF inválido","error":"Requisição
+  inválida."}`, uma forma nova com `message` e `error` (`error.sgp` traz o `error`; o `message` fica em
+  `response.body`). Só o texto observado casa, sem diferenciar maiúsculas; qualquer outro 400 segue sem
+  `reason`. O SDK continua conferindo só o formato do documento: os dígitos verificadores do CNPJ nunca
+  foram testados.
+- `preRegistrations.create`: o 400 `{"message":"Login <login> já existe","error":"Requisição inválida."}`
+  (login PPPoE já em uso; captura bruta, observada uma vez, cliente sintético) agora é `REJECTED` com
+  `reason: "LOGIN_ALREADY_REGISTERED"` e `effect: "none"` (releituras por documento e por login: nada foi
+  criado). Só o corpo observado casa (exatamente as chaves `message` e `error`, ambas texto; `message`
+  começa com `Login `, traz um login não vazio e termina com ` já existe`, sem diferenciar maiúsculas);
+  qualquer outro 400 segue sem `reason`. O login que o `message` repete nunca é copiado para um campo do
+  erro: `error.sgp` traz só o `error`, e o `message` fica em `response.body`. O JSDoc recomenda
+  `customers.list({ login })` antes de criar.
+- `customers.list`: novo filtro `login` (documentado pelo fornecedor), que casa o login PPPoE exato
+  (observado ao vivo: o login inteiro lista o cliente; um prefixo e um login inexistente listam nada). O
+  `login` é segredo em `getSensitivity("customers.list")`.
+- **Quebra de tipo (versus 2.0.0-beta.1): normalização por campo**. Onde o
+  SGP manda o mesmo campo com tipo variável ou em texto, `data` traz um só; `""` e `null` viram `null`,
+  texto formatado nunca é adivinhado (campo sai de `data` com `warning`; o original fica em
+  `response.body`). Nomes inalterados. Campos: `coverage.check` `lat`, `lng`, `distancia`, `id` (`number | null`; antes `number | string`);
+  `services.addTv` e `services.removeTv` `clientecontrato_id` (`number | null`, antes `string`);
+  `workOrders.get` `servico_id`, `contrato_status_id` e `os_setor_id` (`number | null`) e
+  `contrato_status` (aparado); `preRegistrations.listPlans` `gateway.gateway_id` e `gateway.id`
+  (`number | null`). Ver MIGRATION, seção 8.
+- `occurrences.create`: a nota de que a ligação ocorrência para OS "não foi confirmada" foi
+  substituída pelo que se observou: `occurrences.list` devolve a OS da ocorrência. Que o `protocolo`
+  do `create` é igual ao `numero` do `list` segue sem captura bruta.
+- `contracts.listStatusReasons`: a fixture agora é uma captura bruta ao vivo (status, content-type e
+  corpo) no lugar da reconstruída; a ordem dos ids é a do SGP (1, 2, 4, 3, 5, 6, 7). COMPATIBILITY:
+  Observado.
+- `scripts/probe.ts`: a checagem da whitelist do token virou `GET /api/ura/tecnicos` (sem a barra
+  final, que o SGP recusa com 403 `TOKEN_ROUTE_NOT_ALLOWED`; com a barra a rota responde 200). Uma
+  leitura, que não muda dado mesmo que a rota venha a ser liberada.
+- COMPATIBILITY e README: seção "Limitações confirmadas pelo fornecedor (TSMX, 06/11)" (sem API para
+  segundo contrato em cliente definitivo, telefonia, extras de internet e multimídia, "Alterar Titular";
+  extras pela API só TV e genérico; documentação oficial só no Postman; sem rota de correspondência
+  entre os dois catálogos de plano). As linhas PJ (`/J`) de `preRegistrations.create` e
+  `crm.customers.create` passam a "Confirmado pelo fornecedor, não testado". CNPJ alfanumérico: os
+  filtros `cpfcnpj` de leitura o aceitam (200 em `customers.list` e `invoices.list`, o 400 de sempre
+  em `crm.contracts.list`, sem rejeição de formato; observado ao vivo, sem nenhum achado porque
+  nenhum cliente tem esse CNPJ); a criação de PJ com ele não foi testada.
+
+## 2.0.0-beta.1 (2026-11-06)
+
+Redesenho completo como gateway de integração do SGP. Quebra de contrato sem aliases:
+veja o [guia de migração](MIGRATION.md). Publicada na tag `next` do npm; `latest` continua na 1.2.0
+até a 2.0.0 estável.
+
+### Mudanças incompatíveis
+
+- **Superfície nova, em inglês e agrupada por conceito do SGP**: `customers`, `crm.customers`,
+  `crm.contracts`, `preRegistrations`, `contracts`, `services`, `plans`, `occurrences`, `workOrders`,
+  `invoices`, `documents`, `coverage`, `catalogs`, `experimental.annotations` e `request()`. Os
+  namespaces `ura`, `os`, `precadastro`, `crm.*` antigos e `suporte` foram removidos; os campos dos
+  dados mantêm os nomes do SGP. Parâmetros posicionais (`clienteId`, `file`) viraram campos da
+  entrada.
+- **Configuração**: `createSgpClient({ baseUrl, credentials: { kind: "token", token, app }, ... })`.
+  Configuração inválida **lança** `InvalidConfigurationError` na criação; `baseUrl` precisa ser uma
+  origem (sem caminho).
+- **Modelo de resultado**: `{ ok, data, response, attempts, warnings? }` ou
+  `{ ok: false, error, response, attempts }`, no lugar de `success`/`error.status`/`error.detail`/
+  `error.endpoint`. `response` traz status, headers (credenciais redigidas) e corpo (`json`, `text`,
+  `empty`, `unavailable` ou `withheld`), ou `null` quando não houve resposta.
+- **Códigos de erro**: `INVALID_INPUT`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`,
+  `ROUTE_NOT_ALLOWED` (restrição local do SDK: `request()` na rota de anotações), `NOT_FOUND`, `REJECTED`, `UPSTREAM`, `NETWORK`, `TIMEOUT`,
+  `ABORTED`, `INVALID_RESPONSE`. Saem `VALIDATION`, `METHOD_NOT_ALLOWED`, `SCHEMA_MISMATCH` e
+  `UNKNOWN`; o antigo `ROUTE_NOT_ALLOWED` virou `FORBIDDEN` com `reason: "TOKEN_ROUTE_NOT_ALLOWED"`.
+- **Efeito de escritas**: `outcome` (`not_applied`/`unknown`) virou `error.effect` (`none`/`unknown`),
+  presente em toda escrita. `"none"` agora exige evidência (recusa local, cancelamento antes do envio,
+  erro de campo ou de negócio do SGP, ou recusa conhecida da operação); um 4xx de formato não
+  reconhecido é `"unknown"`.
+- **Fidelidade**: chaves desconhecidas são preservadas em todos os níveis (o 1.x as descartava) e os
+  arrays que chegavam como `[{}]` agora chegam inteiros. Um item que não pode ser interpretado é
+  `INVALID_RESPONSE`. Campos secundários com tipo inesperado saem de `data` com `warnings`; o original
+  fica em `response.body`.
+- **`coverage.check` não converte mais** `lat`, `lng` e `distancia` para número.
+- **Entradas estritas**: chaves desconhecidas são recusadas localmente (`INVALID_INPUT`). Só os campos
+  que o fornecedor marca como obrigatórios são obrigatórios.
+- **IDs com marca**: `CustomerId`, `PlanId` e `PreRegistrationPlanId` (tipos de compilação); os dois
+  catálogos de planos não se misturam.
+- **Dados sensíveis**: `omitSensitive` e as tuplas `*SecretKeys`/`*PersonalKeys` foram substituídos por
+  `getSensitivity`, `pick` (allowlist) e `toSafeLog`.
+- **Constantes renomeadas**: `formaCobrancaCodigo` para `BILLING_METHOD`, `modoAquisicao` para
+  `ACQUISITION_MODE`, `crmStatus` para `CRM_STATUS`.
+- **Anotações**: `ura.listAnnotations` virou `experimental.annotations.list`. O corpo da resposta é
+  retido (`withheld`), cada anotação traz `raw`, identidade de outro cliente em qualquer profundidade
+  falha a chamada, e `request()` recusa a rota.
+- Todos os exports `*Definition`, `*KeyFields` e `*ItemPath` foram removidos (a definição de uma
+  operação é interna).
+
+### Adicionado
+
+- Operações novas: `preRegistrations.create` (PF/PJ, endereço em campos soltos com os nomes do SGP) e `preRegistrations.listPlans`,
+  `contracts.update`, `contracts.updateStatus`, `contracts.listStatusReasons`, `services.changePlan`,
+  `services.addTv`, `services.removeTv`, `crm.contracts.createByCpfCnpj` e `crm.contracts.list`.
+- `request()`: chamada bruta a uma rota que nenhum método cobre, com a mesma autenticação, prazo,
+  cancelamento e hooks (só caminhos sob `/api/`, sem redirecionamento, sem retry, `effect: "unknown"`
+  depois do envio).
+- Por chamada: `abortSignal`, `timeoutMs` (um orçamento de tempo por chamada lógica) e `maxRetries`.
+  `TIMEOUT` (prazo do SDK) distinto de `ABORTED` (seu sinal).
+- Retry opt-in para leituras (`maxRetries`, padrão 0), só em falhas transitórias, com backoff,
+  jitter e `Retry-After`. Escritas e `request()` nunca são repetidos. `attempts` em todo resultado.
+- Hooks opcionais e síncronos (`onRequest`, `onResponse`, `onError`) só com metadados; um hook que
+  falha não altera o resultado (registro em `diagnostics`).
+- `error.reason` por operação com evidência (`DOCUMENT_ALREADY_REGISTERED`, `STATUS_NOT_CHANGED`,
+  `CUSTOMER_NOT_IN_CRM`, `CONTRACT_NOT_ACTIVE`, `TOKEN_ROUTE_NOT_ALLOWED`) e `error.sgp` com os campos de
+  erro do SGP como vieram.
+- Constantes `CONTRACT_STATUS` e `SERVICE_TYPE`; `ACQUISITION_MODE` compartilhada entre CRM e
+  pré-cadastro.
+- Documentação em português: README, [MIGRATION.md](MIGRATION.md),
+  [COMPATIBILITY.md](COMPATIBILITY.md) e exemplos (`examples/` do repositório) compilados e executados na CI.
+- CI no GitHub Actions e verificações do pacote construído (tipos de consumidor em NodeNext e Bundler,
+  smoke em Node e Bun, conteúdo do `npm pack`).
+
+### Em aberto antes da 2.0.0 estável
+
+- Testes unitários também no Node (hoje no Bun; o Node é coberto pelo smoke do pacote construído).
+- Rotas e recusas ainda reconstruídas ou não observadas: veja [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## 1.x
+
+Congelada. A última versão é a 1.2.0; as versões 1.0.0 a 1.2.0 estão nas tags `v1.0.0` a `v1.2.0` do
+repositório.

package/COMPATIBILITY.md

@@ -0,0 +1,231 @@
+# Matriz de compatibilidade
+
+O que foi **provado**, e como, para cada operação do sgp-sdk 2.0. Serve para saber até onde confiar
+no contrato de uma operação antes de usá-la em produção.
+
+- **Instância:** uma instância de produção de um provedor. Nenhuma outra foi usada.
+- **Versão do SGP:** **desconhecida**. Nenhuma observação foi associada a uma versão do SGP, e
+  comportamento pode mudar entre versões.
+- **Dados:** as escritas observadas usaram clientes, contratos e serviços de teste sintéticos criados
+  para a verificação. Esta matriz não traz hosts, credenciais nem identificadores reais, e omite ids.
+- **Datas:** `AAAA-MM-DD` (UTC, a data do identificador da execução de verificação). Capturas feitas
+  para a série 1.x aparecem como "1.x" com a data em que a fixture entrou no repositório
+  (2026-10-30 a 2026-10-31); a data exata da captura não foi registrada (não verificado).
+
+## Níveis de evidência
+
+| Nível                                       | Significa                                                                                                                                            |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Observado (bruta)**                       | Resposta real da instância, com status, headers e corpo registrados como foram recebidos.                                                            |
+| **Observado (corpo)**                       | Resposta real da instância, mas só o corpo foi registrado (mascarado); os headers da fixture são reconstruídos.                                      |
+| **Confirmado pelo fornecedor, não testado** | O suporte da TSMX afirmou por escrito o comportamento (06/11); nunca foi exercitado nesta instância.                                                 |
+| **Documentado**                             | Descrito pelo fornecedor (coleção de requisições ou suporte), **nunca visto** numa resposta real.                                                    |
+| **Reconstruído**                            | Corpo ou texto reconstruído de relatos (prosa de verificações), do contrato da série 1.x ou de testes, **sem captura**. O formato real pode diferir. |
+
+Quando a resposta real difere do esperado, o SDK falha de forma segura: `INVALID_RESPONSE`, e numa
+escrita `effect: "unknown"`. Um nível "Observado" prova **um** comportamento, uma vez ou poucas;
+não é uma garantia de contrato do SGP. A prova de "nada foi aplicado" é uma releitura do estado, não
+uma garantia.
+
+As fixtures que alimentam os testes estão em `fixtures/` do repositório (fora do pacote npm), cada uma
+com a fonte (`source`) e o nível de evidência (`evidence`) no próprio arquivo. A data da execução de
+verificação aparece na fonte quando existe; as fixtures derivadas da série 1.x não têm data, e o
+cenário é o caminho do arquivo (`<grupo>/<operação>/<caso>`).
+
+## Matriz por operação
+
+Cada linha é um cenário. As colunas "Data" e "Evidência" valem para aquele cenário.
+
+### `customers`
+
+| Operação           | Cenário                                                                                      | Evidência         | Data       | Observação                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------- | ----------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `customers.list`   | Página de um cliente de teste, com contratos e serviços aninhados                            | Observado (corpo) | 2026-11-05 | Os aninhados chegam inteiros (nada de `[{}]`)                                                   |
+| `customers.list`   | Filtro `login`: o login exato lista o cliente; um prefixo e um login inexistente listam nada | Observado (corpo) | 2026-11-06 | Filtro documentado pelo fornecedor; casa o login PPPoE exato (três leituras, cliente sintético) |
+| `customers.search` | Busca por contrato, um candidato                                                             | Observado (corpo) | 1.x        | Corpo mascarado                                                                                 |
+| `customers.search` | Sem resultado (`contratos: []`)                                                              | Reconstruído      | n/d        | Vem de um teste da 1.x                                                                          |
+
+### `crm`
+
+| Operação                        | Cenário                                                             | Evidência                               | Data         | Observação                                                                                                                                                                                                                                                                            |
+| ------------------------------- | ------------------------------------------------------------------- | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crm.customers.create`          | PF (`/F`): 200 com `cliente_id` e `message`                         | Observado (bruta)                       | 2026-11-05   | Com um CPF que já existia, o SGP criou **outro** cliente com o mesmo documento (ambos listados por `customers.list`)                                                                                                                                                                  |
+| `crm.customers.create`          | PF: 400 CPF já no CRM (`DOCUMENT_ALREADY_REGISTERED`)               | Observado (bruta)                       | 2026-11-06   | Documento já cadastrado (cliente sintético), em qualquer status (o status 6 também recusa; um cliente definitivo que nunca passou pelo CRM também); releitura: nada foi criado. Exceção: documento gravado sem formatação (pré-cadastro só com dígitos) não é detectado (linha acima) |
+| `crm.customers.create`          | PF: 400 CPF com dígitos verificadores errados (`DOCUMENT_INVALID`)  | Observado (bruta)                       | 2026-11-06   | `{"errors":{"cpfcnpj":"CPF inválido."}}` (cliente sintético, documento fictício); releitura: nada foi criado. Dígitos verificadores de CNPJ: nunca testados (veja Lacunas conhecidas)                                                                                                 |
+| `crm.customers.create`          | PF: o CRM grava o CPF formatado (`999.999.999-99`)                  | Observado (bruta)                       | 2026-11-06   | Cliente sintético: um CPF enviado só com dígitos voltou formatado em `customers.list`; o 400 de duplicidade compara com a forma formatada. O SDK envia sempre a máscara canônica (veja Notas das capturas)                                                                            |
+| `crm.customers.create`          | PF: 400 de validação de campo (nome com dígitos)                    | Observado (bruta)                       | 2026-11-05   | Releitura: nada foi criado                                                                                                                                                                                                                                                            |
+| `crm.customers.create`          | PJ (`/J`)                                                           | Confirmado pelo fornecedor, não testado | 06/11 (TSMX) | Funciona como o `/F`, trocam só os dados da empresa; nunca exercitado. CNPJ alfanumérico em criação: não testado (veja Lacunas conhecidas)                                                                                                                                            |
+| `crm.customers.updateStatus`    | Status 6 ("Contrato realizado no SGP"): 200                         | Observado (bruta)                       | 2026-11-06   | Também 200 com `codigo` 6 em cliente CRM sem contratos. Os demais códigos de `CRM_STATUS` nunca foram enviados                                                                                                                                                                        |
+| `crm.customers.updateStatus`    | Cliente que já saiu do CRM: 404 `{error:"Cadastro não encontrado"}` | Reconstruído                            | 1.x          | `NOT_FOUND`, `effect: "none"`                                                                                                                                                                                                                                                         |
+| `crm.contracts.create`          | Por id: 200 com `clientecontrato`, `message`, `cliente`             | Observado (bruta)                       | 2026-11-06   | O contrato apareceu em `contracts.list` depois                                                                                                                                                                                                                                        |
+| `crm.contracts.create`          | Por id: 400 por falta de `nas`                                      | Observado (bruta)                       | 2026-11-06   | Nada foi criado                                                                                                                                                                                                                                                                       |
+| `crm.contracts.create`          | Por id: 400 "Não encontrado cliente CRM" (`CUSTOMER_NOT_IN_CRM`)    | Reconstruído                            | 2026-11-05   | Texto vindo da prosa do relato; a releitura mostrou nenhum contrato adicionado                                                                                                                                                                                                        |
+| `crm.contracts.create`          | `modoaquisicao` 2 recusado                                          | Observado (sem fixture)                 | 2026-10-31   | A documentação do fornecedor lista 1 e 2; o SDK aceita só 0 e 1                                                                                                                                                                                                                       |
+| `crm.contracts.create`          | `login`, `senha`, `modoaquisicao` exigidos para serviço de Internet | Documentado                             | n/d          | Só a falta de `nas` foi observada                                                                                                                                                                                                                                                     |
+| `crm.contracts.createByCpfCnpj` | Sucesso (200)                                                       | Documentado                             | n/d          | **Nenhum sucesso foi observado nesta rota**; assume-se o formato da rota por id                                                                                                                                                                                                       |
+| `crm.contracts.createByCpfCnpj` | 400 "Não encontrado cliente CRM" (`CUSTOMER_NOT_IN_CRM`)            | Observado (bruta)                       | 2026-11-05   | Releitura: nada foi adicionado. Só CPF foi exercitado (CNPJ não)                                                                                                                                                                                                                      |
+| `crm.contracts.list`            | 200 com contratos                                                   | Observado (bruta)                       | 2026-11-06   | Valores pessoais mascarados                                                                                                                                                                                                                                                           |
+| `crm.contracts.list`            | 200 sem contratos                                                   | Observado (bruta)                       | 2026-11-05   |                                                                                                                                                                                                                                                                                       |
+| `crm.contracts.list`            | 400 para documento que não é cliente CRM                            | Observado (bruta)                       | 2026-11-05   | `REJECTED`, sem `reason`                                                                                                                                                                                                                                                              |
+
+### `preRegistrations`
+
+| Operação                       | Cenário                                                                                   | Evidência                               | Data         | Observação                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preRegistrations.create`      | Sucesso (`/F`): 200 com `precadastro_id`, `new_cliente_id`, `new_contrato_id` e `message` | Observado (bruta)                       | 2026-11-06   | Cliente sintético; a releitura (`customers.list` pelo CPF) trouxe o mesmo cliente e o mesmo contrato. Os ids são opcionais: os registros mais antigos listam só `message`, e o decoder da 1.x descartava chaves desconhecidas, então não se sabe se os ids já eram enviados antes                                |
+| `preRegistrations.create`      | Sucesso (`/F`): 200 só com `message`                                                      | Documentado                             | 2026-11-05   | O texto do corpo é o exemplo do fornecedor; ao vivo só o status 200 e a chave `message` foram vistos (o decoder da 1.x descartava chaves desconhecidas)                                                                                                                                                          |
+| `preRegistrations.create`      | PF: 400 CPF com dígitos verificadores errados (`DOCUMENT_INVALID`)                        | Observado (bruta)                       | 2026-11-06   | `{"message":"CPF inválido","error":"Requisição inválida."}`: forma nova, com `message` e `error`; `error.sgp` traz só o `error` e o `message` fica em `response.body`. Cliente sintético, documento fictício; releitura: nada foi criado. Dígitos verificadores de CNPJ: nunca testados                          |
+| `preRegistrations.create`      | PF: 400 login PPPoE já em uso (`LOGIN_ALREADY_REGISTERED`)                                | Observado (bruta)                       | 2026-11-06   | `{"message":"Login <login> já existe","error":"Requisição inválida."}`: o `message` repete o login enviado; `error.sgp` traz só o `error`, e o `message` fica em `response.body`. Uma única captura (cliente sintético, login de outro cliente sintético); releituras por documento e por login: nada foi criado |
+| `preRegistrations.create`      | CPF existente: 402 (`DOCUMENT_ALREADY_REGISTERED`)                                        | Observado (bruta)                       | 2026-11-05   | Releitura: nenhum cliente nem contrato adicionado                                                                                                                                                                                                                                                                |
+| `preRegistrations.create`      | CPF formatado (`999.999.999-99`) gravado como enviado                                     | Observado (bruta)                       | 2026-11-06   | Cliente sintético: `customers.list` devolveu o CPF idêntico ao enviado, e o `crm.customers.create` seguinte foi recusado (400 de duplicidade). Um CPF só com dígitos (captura anterior) escapou dessa checagem. O SDK agora envia sempre a máscara canônica                                                      |
+| `preRegistrations.create`      | PJ (`/J`)                                                                                 | Confirmado pelo fornecedor, não testado | 06/11 (TSMX) | Funciona como o `/F`, trocam só os dados da empresa; nunca exercitado. CNPJ alfanumérico em criação: não testado (veja Lacunas conhecidas)                                                                                                                                                                       |
+| `preRegistrations.listPlans`   | Lista de planos do pré-cadastro                                                           | Observado (corpo)                       | 2026-11-05   | Requisição multipart, sem barra final                                                                                                                                                                                                                                                                            |
+| `preRegistrations.listDueDays` | Lista de vencimentos                                                                      | Observado (corpo)                       | 1.x          |                                                                                                                                                                                                                                                                                                                  |
+| `preRegistrations.listSellers` | Lista de vendedores                                                                       | Observado (corpo)                       | 1.x          |                                                                                                                                                                                                                                                                                                                  |
+
+### `contracts`
+
+| Operação                      | Cenário                                                                                     | Evidência                      | Data       | Observação                                                                                                                                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contracts.listServices`      | Contrato sintético offline: 3 linhas (2 internet, 1 TV)                                     | Observado (bruta)              | 2026-11-06 | Status, content-type e corpo. Senha e login do serviço em claro (trocados na fixture), IP do NAS trocado por endereço de documentação; ids como texto, `contrato_status` com espaço, `servico_online` booleano só nas linhas de internet |
+| `contracts.listServices`      | Contrato sem serviço: `[]`                                                                  | Observado (bruta)              | 2026-11-06 | Status, content-type e corpo                                                                                                                                                                                                             |
+| `contracts.listServices`      | Linha de serviço ONLINE com sessão RADIUS (`rad_*`)                                         | Reconstruído                   | n/d        | Nenhum serviço sintético estava online; chaves e tipos vêm da forma mascarada de um contrato real (só tipos), valores inventados, sem headers                                                                                            |
+| `contracts.checkConnection`   | Contrato sintético suspenso, sem `status_all`: 200 `[]`                                     | Observado (bruta)              | 2026-11-06 | Rodado pela descoberta, não pelo SDK. Ocorrências antes e depois iguais (nenhuma manutenção ativa)                                                                                                                                       |
+| `contracts.checkConnection`   | Mesmo contrato com `status_all: 1`: array, um item por serviço de internet, `status` 2      | Observado (bruta)              | 2026-11-06 | `login` trocado na fixture. Nenhuma ocorrência aberta (sem manutenção ativa)                                                                                                                                                             |
+| `contracts.checkConnection`   | Contrato ativo sem `status_all`: objeto único com `status` 1 e `msg` "Serviço Online"       | Reconstruído                   | n/d        | Forma mascarada de um contrato real (só chaves e tipos); o SDK embrulha o objeto em array                                                                                                                                                |
+| `contracts.checkConnection`   | Em manutenção ativa o SGP abre uma ocorrência por padrão, mesmo sem `protocolo_ura`         | Documentado                    | n/d        | Nunca testado: por isso a operação é uma escrita; `telefone`, `status_filter` e `uracontato` também nunca foram enviados                                                                                                                 |
+| `contracts.list`              | Filtro por contrato: array com um resumo                                                    | Observado (corpo)              | 1.x        |                                                                                                                                                                                                                                          |
+| `contracts.updateStatus`      | Suspenso para Ativo: 200 com `resposta`                                                     | Observado (bruta)              | 2026-11-05 | A releitura confirmou Ativo                                                                                                                                                                                                              |
+| `contracts.updateStatus`      | Ativo para Suspenso: 200 com `resposta`                                                     | Observado (bruta)              | 2026-11-05 | A releitura confirmou Suspenso                                                                                                                                                                                                           |
+| `contracts.updateStatus`      | Inativo para Ativo: 200                                                                     | Observado, corpo não capturado | n/d        | Confirmado por releitura                                                                                                                                                                                                                 |
+| `contracts.updateStatus`      | Ativo para Inativo: 400 `{error:"Status de Contrato não alterado."}` (`STATUS_NOT_CHANGED`) | Reconstruído                   | 2026-11-05 | Status e texto vêm do relato do suporte; a releitura mostrou o contrato ainda Ativo (o painel não oferece Inativo a partir de Ativo)                                                                                                     |
+| `contracts.updateStatus`      | Status 6 ("Novo")                                                                           | Documentado                    | n/d        | Nunca observado; significado e transições desconhecidos                                                                                                                                                                                  |
+| `contracts.updateStatus`      | Status 3, 5 e 7                                                                             | Documentado                    | n/d        | Vêm do painel do SGP; nunca enviados                                                                                                                                                                                                     |
+| `contracts.update`            | `forma_cobranca`: 200 com `resposta.alterados`                                              | Observado (bruta)              | 2026-11-05 | A leitura seguinte mostrou a nova forma. Os demais campos documentados pelo fornecedor não são aceitos pelo SDK                                                                                                                          |
+| `contracts.listStatusReasons` | Lista de motivos (`[{ id, motivo }]`)                                                       | Observado (bruta)              | 2026-11-06 | Leitura ao vivo: 7 motivos, ids 1 a 7 na ordem 1, 2, 4, 3, 5, 6, 7. Registrados status, content-type e corpo; os demais headers não. A lista é configuração do provedor                                                                  |
+
+### `services`
+
+| Operação                 | Cenário                                                          | Evidência         | Data       | Observação                                                                                                                                                                              |
+| ------------------------ | ---------------------------------------------------------------- | ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `services.changePlan`    | 200 `{ msg }` (ida e volta de plano)                             | Observado (bruta) | 2026-11-05 | Observado duas vezes, corpo idêntico; só `servico_tipo` 1 enviado                                                                                                                       |
+| `services.addTv`         | 201 com `servico_id`                                             | Observado (bruta) | 2026-11-05 |                                                                                                                                                                                         |
+| `services.addTv`         | 400 contrato não ativo (`CONTRACT_NOT_ACTIVE`)                   | Reconstruído      | 2026-11-05 | Texto vindo da prosa do relato (o formato `errors` como array não está provado em captura bruta); a releitura mostrou nada adicionado                                                   |
+| `services.removeTv`      | 200 `{ msg, clientecontrato_id, servico_id }` (DELETE multipart) | Observado (bruta) | 2026-11-05 | Remoção do serviço criado na mesma execução                                                                                                                                             |
+| `services.addGeneric`    | 400 plano não é do tipo genérico (`PLAN_NOT_GENERIC`)            | Reconstruído      | 2026-11-05 | A recusa foi vista ao vivo (plano do tipo internet, nada adicionado na releitura), mas só o texto foi guardado; o formato `{ error }` vem do mapa de rotas validadas, sem captura bruta |
+| `services.addGeneric`    | Sucesso (qualquer 2xx com objeto JSON)                           | Documentado       | n/d        | Nunca observado: o provedor não tem plano genérico e planos não são criados para teste. Nenhum campo da resposta é assumido                                                             |
+| `services.removeGeneric` | Sucesso (qualquer 2xx com objeto JSON)                           | Documentado       | n/d        | Nunca observado: nenhum serviço genérico foi criado. O fornecedor documenta que a rota não remove o único serviço do contrato; essa recusa nunca foi vista                              |
+
+### `plans`, `invoices`, `workOrders`, `occurrences`
+
+| Operação                  | Cenário                                                                                             | Evidência         | Data       | Observação                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------- | --------------------------------------------------------------------------------------------------- | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans.list`              | Catálogo de planos                                                                                  | Observado (corpo) | 2026-11-05 |                                                                                                                                                                                                                                                                                                                                                                     |
+| `invoices.list`           | Página vazia de um cliente sem títulos                                                              | Observado (corpo) | 2026-11-05 |                                                                                                                                                                                                                                                                                                                                                                     |
+| `invoices.list`           | Página com títulos                                                                                  | Reconstruído      | n/d        | Nunca houve captura de uma página populada: chaves e tipos seguem a fixture da 1.x, os valores são inventados                                                                                                                                                                                                                                                       |
+| `workOrders.list`         | Filtro por contrato                                                                                 | Observado (corpo) | 2026-11-05 |                                                                                                                                                                                                                                                                                                                                                                     |
+| `workOrders.list`         | Primeira página de várias (`limit` 1, `total` maior que `parcial`)                                  | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                                                                                                                                     |
+| `workOrders.get`          | Objeto plano de 72 campos de uma OS aberta                                                          | Observado (bruta) | 2026-11-06 | Status, content-type e corpo. Senha do serviço em texto claro (trocada na fixture); `wifi_*` e `wan_*` vieram vazios; MAC e IP nulos; `servico_id` e `contrato_status_id` são texto, `contrato_status` tem espaço à esquerda (a SDK os normaliza: números e texto aparado). Cliente de teste sintético                                                              |
+| `workOrders.get`          | 403 antes da rota estar no token                                                                    | Observado (bruta) | 2026-11-06 | `FORBIDDEN` com `TOKEN_ROUTE_NOT_ALLOWED`; sem fixture, o teste usa o corpo em linha                                                                                                                                                                                                                                                                                |
+| `workOrders.get`          | Resposta como array de um elemento; Wi-Fi, WAN, MAC e IP preenchidos; OS finalizada                 | Documentado       | n/d        | Só na coleção do fornecedor; o SGP mandou o objeto e nunca devolveu esses valores. Um array é `INVALID_RESPONSE`                                                                                                                                                                                                                                                    |
+| `workOrders.listComments` | OS sem comentários: `[]`                                                                            | Observado (bruta) | 2026-11-06 | Status, content-type e corpo                                                                                                                                                                                                                                                                                                                                        |
+| `workOrders.listComments` | 403 antes da rota estar no token                                                                    | Observado (bruta) | 2026-11-06 | Mesmo `detail` do 403 de `workOrders.get`; sem fixture                                                                                                                                                                                                                                                                                                              |
+| `workOrders.listComments` | Itens (`comentario_id`, `comentario`, `usuario`, `data_cadastro`, `checklist_*`, `usuario_setores`) | Documentado       | n/d        | Só na coleção do fornecedor; nenhum comentário foi visto. Exigido do item: ser objeto                                                                                                                                                                                                                                                                               |
+| `workOrders.listReasons`  | Lista de motivos                                                                                    | Observado (corpo) | 1.x        | `id` e `codigo` distintos                                                                                                                                                                                                                                                                                                                                           |
+| `occurrences.create`      | Sucesso: `status` 1, `id`, `protocolo`                                                              | Observado (corpo) | 1.x        | Corpo mascarado; a data da resposta não foi registrada. Nenhuma captura bruta cruzou o `protocolo` com o `numero` de `occurrences.list`                                                                                                                                                                                                                             |
+| `occurrences.create`      | Recusa: HTTP 200 com `status` 0 e `msg` do formato de `data_hora_agendamento` (`INVALID_SCHEDULE`)  | Observado (bruta) | 2026-11-06 | Agendamento com segundos (`2026-11-13 09:00:00`): `{"msg":"Data e hora de agendamento inválida, formato esperado: AAAA-MM-DD HH:MM","status":0,...}`, `effect: "none"`. Uma captura (cliente sintético); a releitura de `occurrences.list({ contrato })` achou o mesmo total antes e depois: nada foi criado. Casa só o início do `msg`, sem diferenciar maiúsculas |
+| `occurrences.create`      | Recusa: HTTP 200 com `status` 0 e outro `msg`                                                       | Reconstruído      | n/d        | Vem do contrato da 1.x; sem captura nem releitura, por isso `REJECTED` sem `reason` e `effect: "unknown"`                                                                                                                                                                                                                                                           |
+| `occurrences.create`      | Ocorrência sem `motivoos` (sem agendamento), `status_encerrado: 1`                                  | Observado         | 2026-11-06 | Aceita; o SGP criou também a OS, e `status_encerrado: 1` encerrou ocorrência e OS. Uma vez, por releitura (cliente sintético)                                                                                                                                                                                                                                       |
+| `occurrences.create`      | Encerrar uma OS de instalação (`motivoos` 10) com `status_encerrado: 1`                             | Observado         | 2026-11-06 | O contrato (inativo) continuou inativo: encerrar a OS não o ativou. Uma vez, por releitura (cliente sintético)                                                                                                                                                                                                                                                      |
+| `occurrences.list`        | Filtro por contrato (`contrato` e `limit`): ocorrência com sua OS                                   | Observado (bruta) | 2026-11-06 | Status, content-type e corpo. A OS vem em `ordens_servicos[].id`; o `numero` da ocorrência é o `ocorrencia` da OS (vistos uma vez). Cliente de teste sintético                                                                                                                                                                                                      |
+| `occurrences.list`        | Contrato sem ocorrência: `total` 0 e lista vazia                                                    | Observado (bruta) | 2026-11-06 |                                                                                                                                                                                                                                                                                                                                                                     |
+| `occurrences.list`        | 401 antes da rota estar no token                                                                    | Observado (bruta) | 2026-11-06 | `UNAUTHORIZED` com `detail`, não o 403 das outras rotas de suporte. Captura no run 2026-11-06T19-14-48; sem fixture, o teste usa o corpo em linha                                                                                                                                                                                                                   |
+| `occurrences.list`        | Filtros `ocorrencia`, `status`, `contrato_status`, datas                                            | Documentado       | n/d        | Coleção do fornecedor; nunca enviados. Os filtros `pop`, `tipo` (arrays) e `hora_*` não são oferecidos                                                                                                                                                                                                                                                              |
+| `occurrences.list`        | Chamada sem filtro                                                                                  | Documentado       | n/d        | O SGP lista as ocorrências de todos os clientes (até 1000); nunca executada, de propósito. O SDK recusa a chamada sem filtro (`INVALID_INPUT`, nada enviado); `offset` e `limit` não contam como filtro                                                                                                                                                             |
+| `occurrences.list`        | `comentarios` com itens                                                                             | Documentado       | n/d        | Sempre vazio na captura; o item (`comentario`, `usuario`, `data_cadastro`) só vem da coleção do fornecedor. `servico` e `protocolos_externos` também vieram vazios e a coleção não os cita: conteúdo desconhecido                                                                                                                                                   |
+| `occurrences.listTypes`   | Lista de tipos                                                                                      | Observado (corpo) | 1.x        | `classificacoes` e `setores` sempre vazios nas capturas                                                                                                                                                                                                                                                                                                             |
+| `occurrences.listMethods` | Lista de métodos                                                                                    | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                                                                                                                                     |
+
+### `documents`, `coverage`, `catalogs`, `experimental`
+
+| Operação                        | Cenário                                                                         | Evidência         | Data       | Observação                                                                                                                                                                                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `documents.add`                 | Sucesso: 2xx com corpo vazio                                                    | Reconstruído      | n/d        | Vem do contrato da 1.x e de seus testes; sem captura dos headers                                                                                                                                                                               |
+| `documents.list`                | Lista de documentos                                                             | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                |
+| `coverage.check`                | Gateway SGPMaps; Geogrid; sem CTO no raio                                       | Observado (corpo) | 1.x        | Geogrid manda números como texto (a SDK os converte em números)                                                                                                                                                                                |
+| `coverage.checkAddress`         | `cep` sozinho: `{ viabilidade: true }`                                          | Observado (bruta) | 2026-11-06 | Status, content-type e corpo; o mesmo corpo na execução das 19:14                                                                                                                                                                              |
+| `coverage.checkAddress`         | `cidade` sozinha: `{}`                                                          | Observado (bruta) | 2026-11-06 | 200 sem a chave `viabilidade`: resposta "não sei", nunca `false`                                                                                                                                                                               |
+| `coverage.checkAddress`         | Endereço sem cobertura                                                          | Documentado       | n/d        | **Nunca observado**: a coleção do fornecedor só mostra `true`. O que o SGP manda nesse caso é desconhecido; o SDK repassa o que vier                                                                                                           |
+| `coverage.checkAddress`         | Combinação de filtros; `logradouro`, `bairro`, `numero_inicial`, `numero_final` | Documentado       | n/d        | Coleção do fornecedor ("use um dos filtros"); nunca enviados                                                                                                                                                                                   |
+| `maintenance.list`              | Três avisos, todos com `ativa: false`                                           | Observado (bruta) | 2026-11-06 | Status, content-type e corpo; o mesmo corpo na execução das 19:14. Sem filtro: devolve também os inativos. As listas `pops`, `nas`, `aps`, `sources`, `switches`, `olts`, `oltpons`, `ctos` e `vlans` vieram vazias                            |
+| `maintenance.list`              | Aviso ativo; itens das listas de elementos afetados                             | Documentado       | n/d        | Só a coleção do fornecedor (que mostra `ativa` e `enviar_sms` como `1`; o SGP mandou booleanos). Nunca visto                                                                                                                                   |
+| `coverage.listGateways`         | Lista de gateways (Geogrid e SGPMaps)                                           | Observado (corpo) | 2.0        | Captura bruta ao vivo (status, content-type e corpo); lista vazia e 403 de token sem a rota não foram observados                                                                                                                               |
+| `catalogs.listPops`             | Lista de POPs                                                                   | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                |
+| `catalogs.listNas`              | Lista de NAS                                                                    | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                |
+| `catalogs.listBillingProfiles`  | Lista de portadores                                                             | Observado (corpo) | 1.x        |                                                                                                                                                                                                                                                |
+| `experimental.annotations.list` | Resposta com anotações de vários clientes                                       | Reconstruído      | n/d        | Corpo sintético no formato observado; os tipos dos campos foram contados ao vivo, sem persistir nenhuma anotação. Que o SGP ignora os filtros `cliente_id` e `contrato_id` foi observado ao vivo, mas sem captura positiva do cliente de teste |
+
+### Comportamentos transversais
+
+| Comportamento                                                                                                          | Evidência                                              | Observação                                                                  |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
+| 403 "credenciais ... não foram fornecidas" (rota fora do token, barra final errada) e 403/401 "credenciais incorretas" | Observado (registro de decisão do projeto, 2026-11-05) | Corpo bruto não anexado ao repositório (não verificado)                     |
+| Erros `errors` como array ("Ocorreu um erro: ...") são o invólucro genérico do SGP                                     | Observado (registro de decisão do projeto)             | Por isso ficam em `effect: "unknown"` salvo recusa conhecida da operação    |
+| `RATE_LIMITED` (429), limites de taxa do SGP                                                                           | Nunca observado                                        | O ajuste de retry é estimativa                                              |
+| 502 com corpo HTML como `UPSTREAM`                                                                                     | Coberto por teste                                      | Se foi visto numa resposta real: não verificado                             |
+| `request()`                                                                                                            | Sem evidência própria                                  | Depende da rota chamada: nenhum sucesso ou recusa de negócio é interpretado |
+
+## Limitações confirmadas pelo fornecedor (TSMX, 06/11)
+
+Afirmações do suporte da TSMX (Erick Silva, 05/11; Natanael Azevedo, 06/11) sobre o que a API do
+SGP **não** faz, mais o que nós mesmos constatamos (marcado como tal). O SDK não as testa nem contorna.
+
+- **Segundo contrato em cliente definitivo:** sem API. "No momento não seria possível adicionar um
+  segundo contrato em cadastros definitivos via API" e "Não é possível adicionar um segundo ponto de
+  internet via api". As rotas testadas confirmam: pré-cadastro com CPF existente é recusado (402) e a
+  rota CRM só enxerga clientes do CRM (400).
+- **Telefonia:** sem API. "No momento não temos end-points para adicionar serviços de telefonia".
+- **Serviços extras:** pela API só TV (`services.addTv`) e genérico (`services.addGeneric`).
+  Internet adicional (como locação de roteador, que é plano do tipo internet) e multimídia: só pelo painel.
+- **"Alterar Titular" e migração de contrato:** sem rota de API. Constatação nossa: nenhuma rota na
+  coleção e 404 em todas as variantes sondadas; a resposta da TSMX ("No momento não seria possível")
+  provavelmente se refere a isso, mas não foi dada a essa pergunta de forma explícita.
+- **Documentação oficial:** só a coleção do Postman ("No momento a disponibilização seria apenas via
+  postman"); não há Swagger/OpenAPI.
+- **Planos dos dois catálogos:** os IDs do pré-cadastro e do cliente definitivo são diferentes, e a
+  TSMX não indicou rota que devolva a correspondência (nem há uma na coleção); o consumidor casa pela
+  descrição.
+
+## Lacunas conhecidas
+
+- Formato do documento nas escritas que o gravam: o SDK envia CPF (`F`) ou CNPJ (`J`) na máscara
+  canônica e recusa o resto localmente, sem validar dígitos verificadores. O SGP valida os do CPF
+  (400 `DOCUMENT_INVALID`, observado ao vivo); os dígitos verificadores de um CNPJ nunca foram
+  testados, então não se sabe se o SGP os confere. A máscara do CNPJ
+  alfanumérico (`AA.AAA.AAA/AAAA-99`, maiúsculas) segue a Receita, mas nenhuma criação com ele foi
+  testada: o SGP pode recusá-lo ou gravá-lo de outro jeito. Os filtros de leitura (`cpfcnpj`) não são
+  alterados: `customers.list` casa a forma só com dígitos e a formatada nos dois sentidos, e não casa
+  documento parcial (observado ao vivo, 06/11).
+- Só PF e CPF foram exercitados em `preRegistrations.create` e `crm.customers.create`. PJ e CNPJ
+  só têm a confirmação do fornecedor (TSMX, 06/11), sem teste. CNPJ alfanumérico: os filtros
+  `cpfcnpj` de leitura **aceitam** o formato (observado ao vivo em 06/11, só leitura, com o exemplo
+  da Receita em três formas: com máscara, sem máscara e em minúsculas): `customers.list` e
+  `invoices.list` responderam 200 com `total` 0 em todas, igual ao controle numérico, e
+  `crm.contracts.list` respondeu o 400 "Não encontrado cliente CRM com documento ..." em todas (o
+  SGP formata o documento numérico na mensagem e devolve o alfanumérico exatamente como foi
+  enviado). Um **achado** nunca foi observado (constatação registrada no repositório, 06/11); a
+  **criação** de PJ com CNPJ alfanumérico não foi testada. O texto do `CUSTOMER_NOT_IN_CRM` de
+  `crm.contracts.createByCpfCnpj` só reconhece documento numérico. Para os tipos `E`/`EJ` o
+  fornecedor não tem exemplo que funcione; só via `request()`, sem prova.
+- O sucesso de `crm.contracts.createByCpfCnpj` nunca foi visto.
+- Recusas que são apenas reconstruídas: `STATUS_NOT_CHANGED`, `CUSTOMER_NOT_IN_CRM` por id,
+  `CONTRACT_NOT_ACTIVE`, o 404 de `crm.customers.updateStatus` (só o corpo veio de uma captura da
+  1.x), a recusa `status: 0` de `occurrences.create` com outro `msg` que não o do agendamento e o corpo vazio de `documents.add`. Se o SGP mandar outra forma, o efeito cai em `"unknown"`.
+- Não existe rota de API para um segundo contrato de um cliente definitivo nem para extras de
+  serviço além de TV e genérico (roteador, multimídia, telefonia): o fornecedor confirmou (veja
+  [Limitações confirmadas pelo fornecedor](#limitações-confirmadas-pelo-fornecedor-tsmx-0611)); hoje,
+  só pelo painel do SGP.
+- `experimental.annotations.list` depende do SGP corrigir o filtro no lado dele, e o isolamento local
+  é uma heurística por padrão de chave: dados de outro cliente sob chaves que não são de identidade
+  não seriam detectados.
+- Limites de taxa do SGP e a igualdade entre o `protocolo` de `occurrences.create` e o `numero` de `occurrences.list` não foram confirmados.