# Amasystem Emissor Fiscal v0.6.0 — contrato de integracao

## Endpoints v1
- GET `/api/v1/health` (status geral, sem credenciais)
- GET `/api/v1/capabilities` (escopo autenticado, modelos autorizados, operacoes disponiveis e indisponiveis)
- GET `/api/v1/readiness` (diagnostico de pendencias impeditivas para producao fiscal)
- GET `/api/v1/integrations/me`
- POST `/api/v1/documents` (CRIA RASCUNHO, nao envia nota)
- GET `/api/v1/documents/{id}` (escopo por empresa)
- GET `/api/v1/documents/by-origin?source_reference=...`
- GET `/api/v1/integration-events?after=0` (polling por cursor)
- GET `/api/v1/fiscal-policy?doc_type=NFE&operation_date=2026-10-12` (informativo de vigencia)
- POST `/api/v1/documents/{id}/emit` => HTTP 501 intencional ate homologacao real.

## Contrato
Enviar `Authorization: Bearer af_<64 caracteres hex>`, `Content-Type: application/json`, `Idempotency-Key: <identificador unico>`.
Exemplo (somente rascunho):
```json
{"doc_type":"NFE","recipient_name":"Cliente Exemplo","recipient_tax_id":"","description":"Venda numero 123","gross_amount":"125.90","source_system":"FARMA","source_instance":"loja-01","source_reference":"venda-123"}
```
HTTP 201 significa rascunho gravado, **nao significa nota emitida**. Para evitar duplicidade, repetir a mesma chave com o mesmo payload devolve o documento anterior; com payload diferente retorna 409.

## Reforma tributaria
A configuracao de vigencia nao pode adiar requisitos obrigatorios. As tabelas legais de referencia nao sao automaticamente populadas: validar atos e notas tecnicas aplicaveis antes de habilitar calculos e layouts de producao.

## Bloqueios para emissao real
- Implementar por modelo construcao XML completa, validacao XSD atualizada, assinatura digital, tratamento de certificados e revogacao, enderecos oficiais e contingencia.
- Implementar numeracao atomica, protocolo, reconciliacao, eventos de cancelamento e outros previstos por modelo, distribuicao e PDFs oficiais.
- Homologar modelos por UF, municipio, regime e versao de layout, usando certificados de teste e evidencias verificaveis.
- Operacionalizar rate limit, auditoria imutavel, segredo rotacionavel, DLQ, cron, webhooks HMAC e observabilidade; implantar com HTTPS e armazenamento privado.

## Implantacao
1. Criar backup de arquivos e banco da v0.5.0.
2. Preservar `config.php` e area privada; substituir os arquivos.
3. Rodar `database/update.sql` somente na atualizacao 0.5 -> 0.6; nova instalacao usa `database/install.sql`.
4. Executar `php bin/verify-package.php` e verificar `/health`, `/capabilities`, `/readiness` no servidor.
5. Nao utilizar para emissao fiscal real ate todos os bloqueios de readiness serem eliminados e homologados.