Service Attestations

O Service Attestations conecta uma organização ao sistema de escala e repasse de quem paga (hoje, o Pega Plantão) e guarda, para cada serviço prestado e cada repasse gerado, o que a fonte afirmou: quem prestou, para quem, quando, por quanto e quando será pago. Cada atestado tem versão e hash; quando a fonte muda um valor ou retira um item, o bloco percebe e avisa por evento.

É agnóstico: não sabe de antecipação, médico ou guia. Um "atestado" é só "a fonte afirma que este serviço foi prestado por este sujeito, para este pagador, por este valor". O painel decide o que fazer com isso (no primeiro uso, a antecipação de plantão confirmado).

Enquanto a credencial real do Pega não existe, tudo roda com o provedor simulado (MOCK), determinístico, com o mesmo formato. Trocar para o real é criar uma conexão PEGA_PLANTAO.

O cenário. Um fundo antecipa ao médico o repasse que a organização social (OS) vai pagar no dia 20. O lastro é "o médico trabalhou e a OS vai pagar".

O que trava hoje.

• A prova é um PDF ou print enviado pelo próprio cedente.
• O valor muda depois (glosa, plantão cancelado) e ninguém fica sabendo até o vencimento.
• Cada produto que quisesse ler a escala teria de embutir um cliente HTTP do provedor.

O custo de não resolver. Antecipar sobre lastro declarado é risco de fraude e de glosa sem aviso.

Lastro confirmado pela fonte. O dado vem de quem paga, não de quem recebe.

Mudança vira evento. Versão + hash por atestado; o consumidor não precisa reler tudo.

Trocar de fonte não muda o consumidor. Simulado e real devolvem o mesmo canônico.

Panorama. Quem antecipa recebível de serviço confere demonstrativo à mão ou integra cada fonte dentro do próprio produto.

Nossos diferenciais

1. Canônico + versão + evento. Difícil de copiar sem o motor de leitura e a trilha.
2. Simulado com o mesmo formato da fonte. Homologa o fluxo inteiro sem credencial.

Quando escolher o concorrente. Se a operação tem uma única fonte, sem multi-tenant e sem necessidade de trilha, uma integração direta pode bastar.

Unidade de cobrança. Conexão ativa por mês (proposta; ainda não medida pelo Billing).

O que dispara custo. Conexões ativas e volume de atestados lidos.

ROI. Uma glosa evitada numa antecipação paga meses de conexão. Sem número defensável ainda.

Decisões não óbvias.

• O motor é separável. src/service-attestations/sync/ não conhece atestado: recebe itens { kind, externalId, windowDate, payload, raw } e fala com o domínio por interfaces (SyncStore, SyncHooks, SyncRunStore). Há teste que falha se aparecer termo do domínio ou import de fora do diretório. É o corte para o bloco irmão de rastreio da garantia viva (Traccar, resumo por lote): quando ele existir, sync/ sobe para src/shared sem mudar o contrato (regra de dois — não se extrai antes do segundo consumidor).
• Cancelamento só com leitura completa. O driver diz quais tipos leu por inteiro (completeKinds). Um dia que falhou deixa o tipo incompleto e nada dele é cancelado.
• Token em memória. O token do Pega dura ~10 min e cabe numa leitura; não se persiste.
• Sem @Service() resolvido pelo container. Tudo é montado à mão em src/shared/container/modules/service-attestations.ts (defeito do typedi sem design:paramtypes).

Monolito vs. standalone. As rotas existem nos dois. A leitura agendada só liga no processo standalone (main.ts).

Glossário

Modelo de dados

Canônico (Attestation): subjectDocument (CPF), subjectName, subjectBusinessDocument (CNPJ), subjectBusinessName, payerDocument, payerName, location, sector, serviceStart, serviceEnd (ISO), competence (YYYY-MM), amountCents, payoutDate (YYYY-MM-DD), payoutGroup, status, contentHash, version, firstSeenAt, lastSeenAt.

Máquina de estados

Prefixo /service-attestations/api/v1. Respostas { data } (listas com meta: { total, page, pageSize }). Erros { error, message, details }.

POST /provider-configs

{
  "name": "Pega Plantão — OS Bem Viver",
  "providerType": "PEGA_PLANTAO",
  "credentials": { "clientId": "…", "clientSecret": "…", "username": "…", "password": "…" },
  "settings": {
    "baseUrl": "https://api.pegaplantao.com.br",
    "payerDocument": "11222333000181",
    "payerName": "OS Bem Viver",
    "windowDays": 45,
    "syncIntervalMinutes": 15,
    "timezone": "America/Sao_Paulo"
  },
  "isActive": true,
  "isDefault": true
}

{
  "name": "Pega Plantão — OS Bem Viver",
  "providerType": "PEGA_PLANTAO",
  "credentials": { "clientId": "…", "clientSecret": "…", "username": "…", "password": "…" },
  "settings": {
    "baseUrl": "https://api.pegaplantao.com.br",
    "payerDocument": "11222333000181",
    "payerName": "OS Bem Viver",
    "windowDays": 45,
    "syncIntervalMinutes": 15,
    "timezone": "America/Sao_Paulo"
  },
  "isActive": true,
  "isDefault": true
}

Resposta 201: a conexão com hasCredentials — nunca credentials.

Erros

1. Conectar o simulado (staging)

curl -s -X POST "$BB/service-attestations/api/v1/provider-configs" -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Simulado","providerType":"MOCK","settings":{"payerDocument":"11222333000181","payerName":"OS Teste"}}'

curl -s -X POST "$BB/service-attestations/api/v1/provider-configs" -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"Simulado","providerType":"MOCK","settings":{"payerDocument":"11222333000181","payerName":"OS Teste"}}'

2. Ler agora

curl -s -X POST "$BB/service-attestations/api/v1/provider-configs/$ID/sync" -H "x-api-key: $KEY"

curl -s -X POST "$BB/service-attestations/api/v1/provider-configs/$ID/sync" -H "x-api-key: $KEY"

3. Consultar os repasses

curl -s "$BB/service-attestations/api/v1/attestations?kind=payout&status=confirmed" -H "x-api-key: $KEY"

curl -s "$BB/service-attestations/api/v1/attestations?kind=payout&status=confirmed" -H "x-api-key: $KEY"

4. Provocar mudança e cancelamento (smoke)

curl -s -X PATCH "$BB/service-attestations/api/v1/provider-configs/$ID" -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"settings":{"mockOverrides":[{"externalId":"MOCK-REP-202609-P01","action":"cancel"},{"externalId":"MOCK-REP-202609-P02","action":"amount","amountCents":500000}]}}'
curl -s -X POST "$BB/service-attestations/api/v1/provider-configs/$ID/sync" -H "x-api-key: $KEY"
# → changed: 1, cancelled: 1; eventos service-attestations.attestation.changed|cancelled

curl -s -X PATCH "$BB/service-attestations/api/v1/provider-configs/$ID" -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"settings":{"mockOverrides":[{"externalId":"MOCK-REP-202609-P01","action":"cancel"},{"externalId":"MOCK-REP-202609-P02","action":"amount","amountCents":500000}]}}'
curl -s -X POST "$BB/service-attestations/api/v1/provider-configs/$ID/sync" -H "x-api-key: $KEY"
# → changed: 1, cancelled: 1; eventos service-attestations.attestation.changed|cancelled

Trocar MOCK → PEGA_PLANTAO. Crie uma conexão PEGA_PLANTAO com a credencial real e baseUrl; teste (POST …/test); desative a MOCK (PATCH { "isActive": false }). Nada muda no consumidor: mesmo canônico, mesmos eventos.

Reagir a eventos. Assine service-attestations.attestation.* no webhooks-engine e busque o detalhe em GET /attestations/:id — o evento não leva dado pessoal.

• webhooks-engine: entrega os eventos do iam-events às assinaturas.
• audit-trail: mapeia service-attestations.attestation|sync|provider_config.
• Operador da plataforma: service-attestations.simulated-provider.* vai ao stream do operador (@shared/lib/operator-events), nunca a webhook.

Eventos (payload sem PII):

Migrations: prisma/migrations/20261016180000_service_attestations_core e 20261016200000_service_attestations_raw_retention_index (índice em updated_at; ambas idempotentes). No Launch, pela fase 0 (scripts/launch/), com MIGRATIONS="20261016180000_service_attestations_core 20261016200000_service_attestations_raw_retention_index".

Retenção do bruto: agendador próprio (jobs/raw-retention.scheduler.ts, LockedPass service-attestations:raw-retention:sweep:lock) a cada 6 h, primeira passada 60 s após subir. Apaga em lotes de 500 (FOR UPDATE SKIP LOCKED, seguro com N réplicas), no máximo 200 lotes ou 8 min por passada; o resto fica para a próxima. Uma linha de log por passada (service-attestations: retenção do bruto concluída, com deleted) e o evento service-attestations.raw-retention.purged por organização afetada. Depois de apagado, o detalhe com includeRaw=true devolve raw: null; a próxima leitura que mudar o atestado regrava.

Provedor PEGA_PLANTAO: leituras GET /api/v1/demonstrativos/repasse?dataDeGeracao= (dia a dia), GET /api/v1/plantoes?filtro.dataInicio&filtro.dataFim (janelas de 7 dias; 204 = vazio), GET /api/v1/fornecedores (paginado, paginaAtual/itensPorPagina), POST /api/v1/profissionais/situacao (nomes, melhor esforço). Token POST /token (Basic do cliente, grant_type=password); renova com < 60 s; 401 → renova uma vez; refresh tenta POST, cai para GET com query e, por fim, refaz o login. Nenhuma escrita: lista de leitura conferida antes do envio. Intervalo mínimo de 250 ms entre chamadas.

Padrões nossos (declarados). Competência do repasse do Pega = mês anterior à DataRepasse, com serviço do primeiro ao último dia dela (a fonte não informa). Duas linhas de repasse com a mesma chave no mesmo dia viram um repasse com a soma. externalId sem código da fonte = <CodigoGrupoGeracao>-<hash16> (nunca CPF).

Simulado (MOCK). 12 profissionais (CPF e CNPJ válidos), dois hospitais, setores UTI Adulto, Pronto-socorro, Centro cirúrgico, Enfermaria clínica e UTI Neonatal; 4 a 8 plantões de 12 h por mês; repasse mensal por profissional = soma dos plantões, gerado no dia 5 e pago no dia 20 (útil) do mês seguinte.

Regra da prévia (para sempre haver repasse a receber): a competência em curso já sai como repasse a partir do dia 1 dela — para que sempre exista um repasse a receber com prazo para adiantar (o anterior vence no dia 20) — com o mesmo externalId, o mesmo valor (a escala do mês inteiro) e a mesma payoutDate (dia 20 útil do mês seguinte); só o windowDate é o dia 1. No dia 5 do mês seguinte ela fecha e o windowDate passa a ser o dia 5 (o windowDate não entra no hash, então não há changed). A data de referência é o until da janela. Resultado: em qualquer dia, todo profissional tem ao menos um repasse com payoutDate no futuro — dias 5–19, o fechado do mês anterior; dias 20–4, a prévia do mês em curso. Meses já fechados não mudam.

• Credencial cifrada (aes-256-gcm), decifrada só ao montar o driver; nunca em resposta, log, evento ou SyncRun. Mensagens de erro da fonte não levam corpo nem segredo.
• Escopo por organização em toda consulta; fora dela é 404.
• Eventos sem CPF, nome ou CNPJ. O externalId nunca carrega CPF.
• Fonte real só por https em produção; driver só leitura.
• Simulado em produção só com concessão do operador (ou lista de reserva).

• Sem subconta (X-Subaccount-Id e chave de subconta são recusados pelo middleware).
• Sem retenção automática de attestation_raws.
• O exemplo da doc do Pega corta os campos do plantão: a identificação do profissional é procurada por nomes prováveis (CodigoProfissional, CPF…) e confirmada na primeira leitura real.
• Feriados não entram no "dia útil" do simulado.

Como trocar do simulado para o Pega? Criar uma conexão PEGA_PLANTAO com a credencial real. Nada mais muda.

Por que um atestado sumiu como cancelled? Uma leitura completa da janela não o devolveu. Leituras parciais nunca cancelam.

O painel guarda a senha do Pega? Não. A credencial vai direto ao bloco e não sai dele.