# Checklist de Integração Pré-Produção > Percorra este checklist **antes de apontar sua integração para > produção**. Cada item é um gate que, se falhar, pode causar incidentes > reais em clientes finais (rejeição SEFAZ, cobrança dupla, segredo > vazado). ## 1. Credenciais e escopos - [ ] **Conta de serviço dedicada** para esta integração (não compartilhe com dev/staging). - [ ] **Escopos mínimos** — só os necessários para a operação. Ex: NF-e → `read:customers, write:customers, read:products, write:products, read:invoices, write:nfe, read:sefaz`. Não peça `admin:*` se não precisa. - [ ] **Chave guardada em cofre** (Vault, AWS Secrets Manager, GCP Secret Manager). **Nunca** em `git`, `.env` commitado, planilha ou e-mail. - [ ] **Rotação de chave** agendada (recomendado: 90 dias). Documente quem é responsável e como operacionalizar. - [ ] **Plano de revogação de emergência** conhecido pela equipe (em caso de vazamento, `POST /api/v1/service-accounts/{id}/revoke`). ## 2. Ambiente e homologação - [ ] **Validou em homologação** (`?ambiente=homologacao` quando aplicável). Viu o retorno `autorizado` da SEFAZ com o protocolo real. - [ ] **Certificado A1 carregado** no portal da empresa-alvo, válido por pelo menos 30 dias. Configure alerta para renovação. - [ ] **Regime tributário, IE/IM, CNAE** configurados no cadastro da empresa. CFOPs e NCMs cadastrados nos produtos. - [ ] **Série fiscal** definida (ex: `1` para NF-e). - [ ] **Cliente de teste** com CNPJ válido (use 11222333000190 — fictício padronizado em dev) e código IBGE correto do destino. ## 3. Tratamento de erros e rate limit - [ ] **Lida com `429 Too Many Requests`** lendo o cabeçalho `Retry-After`. Respeita o valor e não implementa backoff próprio (causa bloqueio). - [ ] **Lida com `502/503`** com exponential backoff + jitter (3-5 tentativas, base 2s). - [ ] **Lida com `400`** mostrando mensagem de validação do backend (`response.json().detail`) e bloqueia reenvio sem correção. - [ ] **Lida com `401`** revogando credenciais e reautenticando (chave foi revogada, rotacionada, ou expirou). - [ ] **Lida com `403`** mostrando qual escopo falta e pedindo ao admin para liberar. ## 4. Webhooks - [ ] **URL pública HTTPS** apontando para seu endpoint, com timeout configurado para ≤ 10s. - [ ] **Validação HMAC** de cada entrega: o header `X-Delfica-Signature` deve bater com `HMAC-SHA256(secret, body)`. Rejeite entregas inválidas. - [ ] **Idempotência** com base no header `X-Delfica-Delivery-Id` — mesma entrega reenviada não pode gerar duplicata. - [ ] **Resposta 2xx em ≤ 5s** — atrasos causam reentrega e podem disparar rate limit. - [ ] **Retry interno** com backoff caso sua fila esteja cheia. ## 5. Segurança e logs - [ ] **Sem PII em logs** — não loga CNPJ, razão social, chave, valor. Se precisar de auditoria, salve em sistema separado (DB) com criptografia em repouso. - [ ] **Sem segredo em código, comentários ou prints** — `grep` pelo prefixo da chave antes de cada commit. - [ ] **TLS 1.2+** em todas as chamadas. Não desabilite verificação de certificado. - [ ] **IP allowlist** (se a Délfica já oferece para sua empresa) — habilite para reduzir superfície de ataque. ## 6. Resiliência operacional - [ ] **Fila local com persistência** — se sua aplicação cai, jobs em andamento não devem ser perdidos. Use Postgres, Redis AOF ou similar. - [ ] **Timeout de leitura ≥ 90s** para emissão de NF-e (SEFAZ pode demorar). Timeout de conexão ≤ 10s. - [ ] **Monitoramento** com alertas em: taxa de 5xx, latência P95, profundidade da fila, e tempo desde a última emissão bem-sucedida. - [ ] **Plano de contingência SEFAZ** — sua integração sabe ativar `FS-DA` (formulário de segurança em contingência) quando `GET /api/v1/public/sefaz-status` retorna `amarelo`/`vermelho` por mais de 5 min. - [ ] **Teste de failover** documentado: como você reemite uma NF-e rejeitada, como cancela uma nota rejeitada, como troca de série quando a atual satura. ## 7. Conformidade e fiscal - [ ] **Conhece as regras de cancelamento** (NF-e: até 24h; CC-e: até 30 dias para eventos específicos). - [ ] **Inutiliza numeração** quando pula sequência (configurado no cadastro da empresa). - [ ] **Carta de correção** usada para ajustes não-tributários. Para ajustes tributários, cancele e reemite. - [ ] **Manifestação do destinatário** feita dentro do prazo (até 30 dias após a emissão) para notas recebidas. ## 8. Testes automatizados - [ ] **Smoke de contrato** validando que o JSON retornado pela API bate com o OpenAPI. Use `$HOST/api/openapi.json` + `openapi-validator`. - [ ] **Smoke end-to-end** emitindo uma NF-e de homologação e validando que o `protocol` foi gravado. - [ ] **Smoke de webhook** recebendo uma entrega real e validando a assinatura. - [ ] **Smoke de rate limit** chamando `/api/v1/healthz` 100x em sequência e validando que o cliente respeita o `Retry-After`. ## 9. Pós-produção - [ ] **Runbook de incidente** documentado (quem chamar, em que canal, com quais comandos). - [ ] **Status page** monitorada: [`/status-api`](./STATUS.md). - [ ] **Webhooks de auto-monitoramento** configurados para receber eventos de saúde da plataforma. - [ ] **Revisão trimestral** de escopos e chaves (revogar o que não usa mais, rotacionar chaves com > 90 dias). ## 10. PSPs de cartão/boleto (Asaas, Stripe, Mercado Pago, Pagar.me) A Délfica aceita webhooks de PSPs em `POST /api/v1/payment/{provider}/webhook` para conciliação automática de cobranças (`customer_subscription_charge`). Diferente dos webhooks da seção 4 (que vão da Délfica para você), **estes vão do PSP para a Délfica** — então a configuração de segurança é no portal da Délfica, não no seu sistema. Mas a sua integração **precisa** validar cobranças que aparecem no extrato do PSP. - [ ] **`webhook_secret` configurado por PSP** no portal da Délfica (`/financeiro/payment-providers`). **Em produção, secret vazio = 401** (sem fallback de dev). Configure alertas para monitorar a `last_test_status` dos PSPs. - [ ] **Cálculo de HMAC compatível** — cada PSP tem fórmula própria: Asaas usa `SHA256(secret)` como token estático; Stripe usa `t=…,v1=…` (HMAC-SHA256 com timestamp, rejeita > 5 min); Mercado Pago usa `ts.body` (HMAC-SHA256); Pagar.me usa `sha1=…` (HMAC-SHA1). Detalhes em `AUTH.md → Segurança de webhooks PSP`. **Não** gere webhooks de teste sem replicar a fórmula exata — vão voltar 401. - [ ] **`X-Tenant-Id` enviado pelo PSP** quando há mais de um tenant usando o mesmo PSP. Se o seu PSP não permite header custom, configure **um** `webhook_secret` por tenant — o sistema auto-resolve com 1 candidato, mas com 2+ pede o header (anti-impersonation). - [ ] **Idempotência por `provider_event_id`** — o PSP reenvia em caso de timeout. Cada `event_id` é processado no máximo uma vez por `(tenant, provider)`; reenvios retornam 200 sem efeito colateral. - [ ] **`externalReference` (PSP) ↔ `external_ref` (cobrança Délfica)** casados na geração — se você emite a cobrança via Délfica e o `externalReference` do pagamento é outra coisa, a auto-aplicação falha e cai em revisão manual em `/financeiro/reconciliacao`. - [ ] **Tolerância de divergência de valor ≤ 1%** — valores que diferem mais que isso da `customer_subscription_charge.amount_brl` são registrados em `payment_webhook_log` com `status='ignored'` e vão para revisão manual (anti-fraude). - [ ] **Reconciliação manual via OFX** como fallback universal — se nem o PSP nem o banco do tenant estão integrados, o tenant pode subir o extrato OFX em `/financeiro/ofx-upload` (escopo `read:reconciliation` + `write:reconciliation`). --- > **Próximos passos**: depois de preencher este checklist, rode > [`smoke_api_docs_consistency.py`](../../tests/smokes/smoke_api_docs_consistency.py) > e [`smoke_developers_portal.py`](../../tests/smokes/smoke_developers_portal.py) > para garantir que seu ambiente de integração continua funcional. > Valide também o smoke de segurança de webhook PSP: > [`smoke_payment_webhook_security.py`](../../tests/smokes/smoke_payment_webhook_security.py) > (13 cenários: HMAC por PSP, auth Bearer + scope, resolução de tenant).