Prompts prontos para seu assistente de IA gerar o código de integração perfeito com a Fiscal Contora.

# Contexto da API Fiscal Contora para Geração de Código

Você é um engenheiro de software especialista em integração de APIs fiscais e arquitetura de microsserviços.
Sua tarefa é implementar a camada de integração HTTP e recepção de Webhooks da plataforma **Fiscal Contora** no meu projeto.

## Arquitetura e Regras Gerais:
1. **Base URL:** `https://fiscal.contora.com.br/api/v1`
2. **Autenticação:** Toda requisição REST deve enviar os cabeçalhos:
   - `Authorization: Bearer <TOKEN_API>`
   - `Accept: application/json`
   - `Content-Type: application/json`
3. **Arquitetura Multi-Tenant:**
   - 1 Único Token Master da Software House pode administrar N empresas clientes.
   - Para especificar o emitente, informe o header HTTP `X-Company-Document: <CNPJ_SEM_MASCARA>` ou use rotas com prefixo `/companies/{company_id}/...`.
4. **Padrão de Resposta da API:**
   - Sucesso (HTTP 2xx): `{ "ok": true, "data": { ... } }`
   - Erro (HTTP 4xx/5xx): `{ "ok": false, "message": "...", "error": { "type": "...", "details": { ... } } }`

## Validação Criptográfica de Webhooks:
1. As notificações via webhook enviam os cabeçalhos `X-Fiscal-Signature` e `X-Fiscal-Timestamp`.
2. A assinatura esperada é calculada com: `HMAC-SHA256(timestamp + "." + rawBody, webhookSecret)` em hexadecimal.
3. A comparação de hash DEVE ser feita com segurança contra timing attacks (ex: `hash_equals` no PHP, `crypto.timingSafeEqual` no Node.js, `hmac.compare_digest` no Python).
4. O endpoint receptor deve responder com HTTP 200 `{ "ok": true }` em menos de 5 segundos e processar o payload de forma assíncrona (fila/job).

## Sua Tarefa:
Escreva na linguagem e framework do meu projeto:
1. A classe Client / Service base com métodos para chamadas GET, POST, PUT, DELETE tratando erros envelopados e retentativas exponenciais em falhas transitórias (HTTP 429 e 5xx).
2. O Controller / Handler do Webhook com a função de validação de assinatura e despacho para a fila de processamento assíncrono.
Por favor, aguarde minha instrução com a linguagem/framework desejado antes de gerar o código.

# Contexto da API Fiscal Contora: Emissão de NF-e e NFC-e

Você é um especialista em emissão de NF-e (Modelo 55) e NFC-e (Modelo 65) via API da **Fiscal Contora**.
Sua tarefa é criar o serviço de montagem de payload e ciclo de vida de autorização.

## Ciclo de Vida do Documento:
1. **Passo 1 (Criação do Rascunho):** `POST /nfe/drafts` com os dados do emitente, destinatário, produtos e tributos.
2. **Passo 2 (Montagem & Validação SEFAZ):** `POST /nfe/drafts/{id}/build` para gerar e assinar o XML.
3. **Passo 3 (Despacho Assíncrono):** `POST /nfe/drafts/{id}/dispatch` com `{ "action": "authorize" }`.
4. **Passo 4 (Consulta de Status):** `GET /nfe/drafts/{id}/status`.
5. **Download de Artefatos:** `GET /nfe/drafts/{id}/artifacts/xml_authorized` e `GET /nfe/drafts/{id}/artifacts/pdf_danfe`.

## Regras Fiscais Avançadas Suportadas:
- **Reforma Tributária 2026 (IBS / CBS):**
  - Informar `items[].taxes.ibscbs` com `cst`, `classification_code` (cClassTrib de 6 dígitos), `state_rate` (0.1%), `cbs_rate` (0.9%). A API calcula automaticamente as bases e totaliza no XML.
- **Responsável Técnico (infRespTec):**
  - Injeção automática em nível de conta ou informada no payload (`technical_responsible` com CNPJ, contato, fone e hash CSRT).
- **Cobrança e Parcelamento (DANFE):**
  - Informar bloco `billing` com `invoice` (vLiq) e array `installments` (`number`, `due_date`, `amount`) para que o quadro de duplicatas seja impresso no DANFE em PDF.

## Sua Tarefa:
Escreva a função / service que monta o payload completo de venda de mercadoria (ou NFC-e de PDV), executa os 3 passos de emissão e retorna a chave de acesso (44 dígitos), protocolo e links de download do XML e PDF. Aguarde minha confirmação da linguagem para gerar.

# Contexto da API Fiscal Contora: Emissão de NFS-e (Nacional e Municipal)

Você é um especialista em emissão de NFS-e (Nota Fiscal de Serviços Eletrônica) via API da **Fiscal Contora**.

## Particularidades do Ecossistema NFS-e:
1. **Padrão Nacional (Sefin Nacional / SPED) & Provedores Municipais:**
   - Suporte unificado via `POST /nfse/drafts` e despacho via `POST /nfse/drafts/{id}/dispatch`.
2. **Substituição de NFS-e Nacional (Grupo `subst`):**
   - Não se cancela a nota anterior isoladamente: na nota substituta informa-se `substitution: { "replaced_access_key": "50_DIGITOS", "reason_code": "01".."05" | "99", "reason": "Motivo descritivo" }`.
   - O Sefin Nacional cancela automaticamente a nota antiga com o evento 105102 e vincula a nova chave.
3. **Inscrição Municipal e CNC (Rejeições E0116 / E0120):**
   - A API gerencia o envio da tag `<IM>` via flag `nfse_municipal_registration_in_cnc` (true para envio, false para omissão em MEIs ou prefeituras sem sincronismo no CNC).
4. **Terceiro Setor & Imunidade Tributária (Programa Contora Social):**
   - Entidades sem fins lucrativos (399-9, 306-9, ONGs, fundações) emitem com `special_tax_regime: "imune"`, `iss_requirement: "imunidade"`, alíquota `0.00` e CST PIS/COFINS `08` (sem incidência).

## Sua Tarefa:
Gere a estrutura de dados (DTO / Interface) e a função de envio para NFS-e padrão, substituição e emissão imune na linguagem do meu projeto. Aguarde minha instrução.

# Contexto da API Fiscal Contora: Devolução e Grupo autXML

Você é um especialista em operações de devolução e compartilhamento fiscal na API da **Fiscal Contora**.

## Regras de Devolução (Finalidade 4 - finNFe=4):
1. **Documentos Referenciados Obrigatórios (NFref):**
   - Para evitar a Rejeição 321 da SEFAZ, o nó `referenced_documents: [{ "access_key": "44_DIGITOS_NOTA_ORIGEM" }]` é obrigatório.
2. **IPI Devolvido (Grupo impostoDevol / vIPIDevol):**
   - Empresas que devolvem mercadoria com IPI sem serem contribuintes industriais devem informar `items[].returned_ipi: { "ipi_rate": 10.00, "returned_amount": 150.00 }`.
   - NUNCA jogar o valor do IPI em "Outras Despesas" (`vOutro`).

## Grupo de Autorização de Download XML (`autXML`):
1. Para que a contabilidade do cliente ou a transportadora baixe o XML completo na Distribuição DFe da SEFAZ sem erro de Rejeição 486:
   - Informar `authorized_xml_downloads: ["CNPJ_CONTABILIDADE", "CNPJ_TRANSPORTADORA"]` (até 10 documentos autorizados).

## Sua Tarefa:
Escreva a rotina que monta uma NF-e de devolução referenciando a nota de compra, destacando o IPI devolvido e autorizando o CNPJ do escritório contábil via `authorized_xml_downloads`. Aguarde minha instrução de linguagem.