# API REST CIOT em PHP

API REST em PHP 8+ para integracao com emissao de CIOT usando Bearer Token, JSON, cURL, validacoes e logs.

## Estrutura

- `src/CiotAPI.php`: classe principal que valida os dados, monta o payload, envia via cURL e trata respostas.
- `public/index.php`: endpoint REST para receber requisicoes JSON.
- `config/ciot.php`: configuracao de ambiente, tokens, URLs e timeouts.
- `examples/emitir_ciot.php`: exemplo de uso direto da classe.
- `examples/emitir_ciot_mdfe.php`: exemplo que le o XML MDF-e de teste e emite CIOT em homologacao.
- `examples/request.json`: payload JSON de exemplo.
- `examples/request_encerramento.json`: payload JSON de encerramento.
- `examples/curl.ps1`: exemplo para chamar a API no PowerShell.
- `examples/curl_encerrar.ps1`: exemplo para encerrar CIOT no PowerShell.
- `public/teste.html`: pagina simples para testar AJAX e imprimir o retorno.
- `docs/MANUAL_INTEGRACAO_CLIENTES.md`: manual completo para entregar aos sistemas/clientes que consumirao a API.
- `docs/DEPLOY_RENDER_GRATIS.md`: passo a passo para publicar a API gratis no Render.
- `.env.example`: exemplo das variaveis de ambiente para publicar a API online.
- `logs/ciot.log`: arquivo gerado automaticamente com logs de requisicao e resposta.
- `mock-provider/public/index.php`: provedor CIOT simulado para homologacao local.
- `scripts/start-mock-provider.ps1`: inicia o mock na porta `8081`.
- `scripts/start-api.ps1`: inicia a API na porta `8090` usando o PHP portatil.
- `scripts/lint.ps1`: valida a sintaxe dos arquivos PHP.

## Ambiente padrao

Para entregar esta API para outro sistema online, leia tambem `docs/MANUAL_INTEGRACAO_CLIENTES.md`.

O projeto nasce em homologacao:

```php
'environment' => getenv('CIOT_ENV') ?: 'homologation'
```

Por padrao, a homologacao aponta para o mock local:

```powershell
http://127.0.0.1:8081/api/v1
```

Para testar producao, defina a variavel:

```powershell
$env:CIOT_ENV = 'production'
```

Tambem configure as URLs oficiais do seu provedor CIOT:

```powershell
$env:CIOT_HOMOLOGATION_URL = 'https://homologacao.seu-provedor.com.br/api/v1'
$env:CIOT_PRODUCTION_URL = 'https://api.seu-provedor.com.br/v1'
```

## Tokens

A API usa dois tokens:

- `API_BEARER_TOKEN`: token para proteger o endpoint REST local.
- `CIOT_PROVIDER_TOKEN`: token enviado ao provedor CIOT no header `Authorization: Bearer`.

Exemplo:

```powershell
$env:API_BEARER_TOKEN = 'token-local-forte'
$env:CIOT_PROVIDER_TOKEN = 'token-fornecido-pelo-provedor'
```

## Executar servidor local

Este projeto inclui um PHP portatil em `runtime/php`. Para testar tudo localmente, abra dois terminais.

Terminal 1, provedor CIOT simulado:

```powershell
cd D:\windows\CIOT
.\scripts\start-mock-provider.ps1
```

Terminal 2, API REST:

```powershell
cd D:\windows\CIOT
.\scripts\start-api.ps1
```

Validar sintaxe:

```powershell
cd D:\windows\CIOT
.\scripts\lint.ps1
```

Tambem e possivel iniciar manualmente:

Sem Composer:

```powershell
cd D:\windows\CIOT
.\runtime\php\php.exe -S 127.0.0.1:8090 -t public public\index.php
```

Com Composer:

```powershell
cd D:\windows\CIOT
composer run serve
```

## Chamada REST

```powershell
cd D:\windows\CIOT
.\examples\curl.ps1
```

Rotas principais da API separada:

```text
GET  /                  abre a pagina de teste no navegador
GET  /status            status JSON da API
POST /emitir-ciot       emissao de CIOT
POST /encerrar-ciot     encerramento de CIOT
GET  /teste.html        pagina simples de teste AJAX e impressao
```

Header obrigatorio nas chamadas AJAX externas:

```text
Authorization: Bearer troque-este-token-local
Content-Type: application/json
Accept: application/json
```

Exemplo AJAX para emissao:

```javascript
fetch('http://127.0.0.1:8090/emitir-ciot', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer troque-este-token-local',
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: JSON.stringify(payloadCompletoDoSistema)
})
  .then(response => response.json())
  .then(retorno => console.log(retorno));
```

## Pagina de teste e impressao

Com os servidores ligados, abra:

```text
http://127.0.0.1:8090/teste.html
```

Na pagina de teste, tambem e possivel enviar o certificado A1 em formato `.pfx` e consultar o status do certificado.

A pagina envia o JSON via AJAX, exibe o retorno completo e monta a impressao usando os campos retornados pela API: `sucesso`, `mensagem`, `ciot`, `protocolo`, `data_emissao`, `data_encerramento` e `tipo_operacao`.

## Encerramento

Para encerrar um CIOT em homologacao:

```powershell
cd D:\windows\CIOT
.\examples\curl_encerrar.ps1
```

JSON esperado para encerramento:

```json
{
  "ciot": "124242264104",
  "protocolo": "HML-260EC4BA2F71",
  "data_encerramento": "2026-06-12T11:00:00-03:00",
  "motivo": "ENTREGA_CONCLUIDA",
  "observacao": "Encerramento de teste em homologacao.",
  "cidade_encerramento": {
    "cidade": "Curitiba",
    "uf": "PR"
  },
  "mdfe": {
    "chave": null,
    "numero": null
  },
  "cte": {
    "chave": null,
    "numero": null
  },
  "referencia_externa": "ENCERRAMENTO-TESTE"
}
```

Campos minimos para encerramento:

```json
{
  "ciot": "124242264104"
}
```

Quando `data_encerramento` nao for enviada, a API usa a data/hora atual. Quando `motivo` nao for enviado, usa `ENTREGA_CONCLUIDA`.

## Teste com XML MDF-e

O arquivo `XML MDFE TESTE/51.xml` pode ser usado para emitir um CIOT em homologacao local:

```powershell
cd D:\windows\CIOT
.\runtime\php\php.exe .\examples\emitir_ciot_mdfe.php
```

Para testar um segundo XML dentro da pasta `XML MDFE TESTE`, copie o arquivo para essa pasta e informe o nome dele:

```powershell
cd D:\windows\CIOT
.\runtime\php\php.exe .\examples\emitir_ciot_mdfe.php outro-arquivo.xml
```

Tambem pode informar o caminho completo:

```powershell
cd D:\windows\CIOT
.\runtime\php\php.exe .\examples\emitir_ciot_mdfe.php "D:\windows\CIOT\XML MDFE TESTE\outro-arquivo.xml"
```

Campos extraidos do XML de teste:

```json
{
  "cpf_motorista": "48465879672",
  "nome_motorista": "Edmilson Ferreira",
  "placa_veiculo": "OPN7295",
  "rntrc": "00129944",
  "valor_frete": 26410.65,
  "origem": {
    "cidade": "Sete Lagoas",
    "uf": "MG"
  },
  "destino": {
    "cidade": "Uberlandia",
    "uf": "MG"
  }
}
```

## Certificado A1

Foi identificado no Windows o certificado `GRG TRANSPORTES LTDA:32256965000136`, thumbprint `5FFC96F49371C5E734D16121CDC2CA8C7740E15D`, com chave privada.

Em homologacao local, o certificado nao e exigido. Quando o provedor CIOT real exigir mTLS, exporte o certificado A1 para `.pfx` e configure:

```powershell
$env:CIOT_CLIENT_CERT_PATH = 'D:\caminho\certificado.pfx'
$env:CIOT_CLIENT_CERT_PASSWORD = 'senha-do-pfx'
$env:CIOT_CLIENT_CERT_TYPE = 'P12'
```

Nao grave a senha do certificado no codigo.

A requisicao deve enviar:

```json
{
  "cpf_motorista": "529.982.247-25",
  "nome_motorista": "Joao da Silva",
  "placa_veiculo": "ABC1D23",
  "rntrc": "12345678",
  "valor_frete": 2500.75,
  "origem": {
    "cidade": "Sao Paulo",
    "uf": "SP"
  },
  "destino": {
    "cidade": "Curitiba",
    "uf": "PR"
  }
}
```

## Retorno padronizado

```json
{
  "sucesso": true,
  "mensagem": "CIOT emitido com sucesso.",
  "ciot": "1234567890",
  "protocolo": "PROTOCOLO-123",
  "data_emissao": "2026-06-12T10:00:00-03:00"
}
```

## Tratamento de erros

A classe trata conexao, timeout, JSON invalido e os codigos HTTP `200`, `201`, `400`, `401`, `403`, `404`, `429` e `500`.

## Integracao futura MDF-e e CT-e

O payload ja inclui o bloco `integracoes_futuras` com `mdfe` e `cte`, permitindo anexar chaves, numeros e metadados desses documentos quando a integracao for ampliada.

## Observacao importante

As URLs `exemplo-ciot.com.br` sao placeholders. Para producao real, substitua pelas URLs e pelo contrato de payload do provedor CIOT homologado/contratado.
