# Ambientes

| Ambiente        | URL                                | Certificado                                 | Comportamento                                                                                                                                                                                    |
| --------------- | ---------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sandbox**     | `sandbox.api.edocs.ixcsoft.com.br` | Certificado self-signed (gerado localmente) | Simulação interna sem comunicação com o provedor municipal ou nacional. As respostas são simuladas pela plataforma. Útil para validar a integração antes de usar certificado real.               |
| **Homologação** | `api.edocs.ixcsoft.com.br`         | e-CNPJ / e-CPF real (ICP-Brasil)            | Emissão no ambiente de testes do provedor (municipal ou nacional). O provedor processa a requisição, mas as notas não têm validade fiscal. Nem todos os provedores disponibilizam este ambiente. |
| **Produção**    | `api.edocs.ixcsoft.com.br`         | e-CNPJ / e-CPF real (ICP-Brasil)            | Emissão real no provedor (municipal ou nacional). Notas com validade fiscal.                                                                                                                     |

O ambiente (`production` ou `homologation`) é definido em `nfse_config.environment` na configuração da empresa. A URL da API é a mesma para ambos — a plataforma roteia internamente para o endpoint correto do provedor conforme o ambiente configurado.

#### Sandbox — como começar

O sandbox usa uma URL dedicada (`sandbox.api.edocs.ixcsoft.com.br`) e aceita certificados self-signed gerados localmente. Todos os endpoints funcionam da mesma forma que em produção, mas nenhuma requisição é enviada à prefeitura — as respostas são simuladas.

**1. Gere um certificado self-signed para o CNPJ da empresa:**

> **Importante:** o `CN` (Common Name) deve ter o prefixo `SANDBOX:` para que a plataforma reconheça o certificado como sandbox. Certificados sem esse prefixo são rejeitados no upload quando a API está no modo sandbox.

**Linux / macOS:**

```bash
CNPJ="17081562000100"
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=SANDBOX:${CNPJ}/O=Empresa Teste/C=BR"
openssl pkcs12 -export -out sandbox-${CNPJ}.p12 -inkey key.pem -in cert.pem \
  -passout pass:123456
rm key.pem cert.pem
```

**Windows (PowerShell):**

```powershell
$CNPJ = "17081562000100"
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes `
  -subj "/CN=SANDBOX:$CNPJ/O=Empresa Teste/C=BR"
openssl pkcs12 -export -out "sandbox-$CNPJ.p12" -inkey key.pem -in cert.pem `
  -passout pass:123456
Remove-Item key.pem, cert.pem
```

> No Windows, o `openssl` está disponível via [Git for Windows](https://gitforwindows.org/) (incluído no Git Bash) ou pode ser instalado via `winget install OpenSSL`.

**2. Faça upload do certificado gerado:**

```bash
curl -X POST https://sandbox.api.edocs.ixcsoft.com.br/certificates \
  -H "x-api-key: SUA_CHAVE" \
  -F "file=@sandbox-17081562000100.p12" \
  -F "password=123456"
```

**3. Configure a empresa e comece a emitir:**

```bash
# Configurar NFS-e
curl -X PUT https://sandbox.api.edocs.ixcsoft.com.br/nfse/config/companies/COMPANY_ID \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"integration": "national", "environment": "production", ...}'

# Emitir NFS-e
curl -X POST https://sandbox.api.edocs.ixcsoft.com.br/nfse \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '[{...}]'
```

> **Atenção:** O sandbox simula respostas genéricas. O comportamento real (validações, rejeições, prazos) varia por prefeitura e provider. Quando a prefeitura disponibilizar ambiente de homologação, valide com certificado real antes de emitir em produção. Nem todas as prefeituras oferecem homologação — nesses casos, emita a primeira nota em produção com valores baixos para validar o fluxo.

#### Migrar do sandbox para produção

1. Troque a URL de `sandbox.api.edocs.ixcsoft.com.br` para `api.edocs.ixcsoft.com.br`.
2. Faça upload de um certificado real via `POST /certificates` (e-CNPJ ou e-CPF emitido por AC credenciada ICP-Brasil).
3. Configure `environment: production` via `PUT /nfse/config/companies/{company_reference}` (aceita ObjectId ou CNPJ sem máscara).

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ixc-soft.gitbook.io/e-docs/ambientes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.