> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntas frequentes

> Perguntas frequentes sobre a engineAPI: certificados, NFS-e, planos, sandbox, integrações e suporte.

Respostas para as dúvidas mais comuns de parceiros e desenvolvedores.

## Certificados

<AccordionGroup>
  <Accordion title="Aceita certificado A3?">
    **Não.** A engineAPI trabalha exclusivamente com certificados **A1** (arquivo .pfx/.p12). O certificado A3 (token USB/cartão) não é compatível com APIs cloud por exigir interação física com o dispositivo.

    Se seu cliente usa A3, ele precisará adquirir um certificado A1 junto a uma Autoridade Certificadora (AC) como Certisign, Serasa ou SafeWeb.
  </Accordion>

  <Accordion title="Qual o formato aceito?">
    Arquivo **.pfx** ou **.p12** com senha. O upload é feito via endpoint (campo
    multipart **`file`**, não `certificate`):

    ```
    POST /v1/companies/:id/certificate
    ```

    A senha é criptografada em repouso e nunca é retornada após o upload.
  </Accordion>

  <Accordion title="O que acontece quando o certificado vence?">
    As emissões passam a falhar, tipicamente `400` com `error.erros[]` (rejeição da
    SEFAZ por certificado inválido/vencido) ou `500` se a falha for na leitura do
    arquivo. Recomendamos:

    * Monitorar o campo `certExpiry` via `GET /v1/companies/:id`
    * Configurar o webhook `certificate.expiring` (dispara em 30/15/7/3/1 dias antes)
    * Renovar com antecedência de 30 dias
  </Accordion>

  <Accordion title="Posso usar o mesmo certificado em homologação e produção?">
    **Sim**, mas não recomendamos. O ideal é usar certificados de teste (alguns ACs emitem gratuitamente para homologação) no emissor em homologação e reservar o certificado de produção para o emissor de produção.
  </Accordion>
</AccordionGroup>

## NFS-e

<AccordionGroup>
  <Accordion title="NFS-e funciona em qualquer cidade?">
    **Depende.** A NFS-e não é padronizada nacionalmente. A engineAPI suporta municípios
    que seguem o padrão **ABRASF** e o **Padrão Nacional (SEFIN/ADN)**.

    Consulte o suporte para verificar se o município do seu cliente é suportado.
  </Accordion>

  <Accordion title="Qual o código de serviço da NFS-e?">
    O campo `servico.itemListaServico` segue a **Lista de Serviços da LC 116/2003**. Exemplos comuns:

    * `01.07`: Suporte técnico em informática
    * `01.01`: Análise e desenvolvimento de sistemas
    * `17.01`: Assessoria e consultoria

    O seu cliente/contador sabe qual código se aplica. Com `resolverTributacao: true`, o
    Cérebro Fiscal pode preencher esse campo a partir do cadastro do emissor
    (`servicoPadraoLc116`).
  </Accordion>

  <Accordion title="A alíquota de ISS varia?">
    **Sim.** Cada município define suas alíquotas. A engineAPI não calcula o valor do
    ISS, você informa `servico.aliquotaIss` no payload (não existem os campos
    `valorISS`/`issRetido` no contrato).
  </Accordion>
</AccordionGroup>

## Planos e preços

<AccordionGroup>
  <Accordion title="Qual o custo?">
    Varia por plano (Dev é grátis para sandbox/homologação; Starter, Growth, Scale e
    Enterprise têm preços diferentes). A tabela de preços vigente, que muda com mais
    frequência que esta doc, está em [engineapi.com.br/precos](https://engineapi.com.br/precos).
  </Accordion>

  <Accordion title="Tem período de teste?">
    **Sim.** Todo emissor nasce em homologação (`ambienteFiscal: 2`) e a `ek_test_` está
    disponível para qualquer partner, mesmo sem assinatura paga. As notas emitidas em
    homologação não têm validade fiscal e não são cobradas.
  </Accordion>

  <Accordion title="A cobrança é por nota emitida?">
    Depende do plano: cada plano tem um limite de requests/segundo (ver
    [Rate Limits](/guides/rate-limits)) e a metering conta 1 por
    documento **autorizado** (não por tentativa).
  </Accordion>
</AccordionGroup>

## Integração técnica

<AccordionGroup>
  <Accordion title="Tem SDK oficial?">
    **Sim**, para TypeScript, PHP e Python: classe `EngineApiClient` com os módulos
    `nfe`/`companies`. Confirme a disponibilidade nos registries (npm/Packagist/PyPI)
    antes de instalar; na dúvida, integre direto via REST com qualquer HTTP client. Ver
    [SDKs](/sdks/typescript).
  </Accordion>

  <Accordion title="Posso usar em produção sem certificado?">
    **Não.** O certificado digital A1 é obrigatório para assinar os documentos fiscais junto a SEFAZ/SEFIN. Sem ele, nenhuma emissão (NF-e, NFC-e, NFS-e) é possível.
  </Accordion>

  <Accordion title="Qual o formato das respostas?">
    Toda resposta de sucesso vem envelopada:

    ```json theme={null}
    {
      "data": { "...": "..." },
      "meta": { "requestId": "req_abc123", "timestamp": "2026-07-06T12:00:00.000Z" }
    }
    ```

    Em caso de erro, o formato é RFC 7807 (Problem Details):

    ```json theme={null}
    {
      "error": {
        "type": "https://engineapi.com.br/errors/BAD_REQUEST",
        "title": "Requisição Inválida",
        "status": 400,
        "detail": "SEFAZ rejeitou (CStat=539): Rejeicao: Duplicidade de NF-e",
        "erros": [{ "codigo": "539", "descricao": "Rejeicao: Duplicidade de NF-e" }],
        "instance": "/v1/nfe",
        "requestId": "req_abc123",
        "timestamp": "2026-07-06T12:00:00.000Z"
      }
    }
    ```

    Não existem os campos `success`/`sefazCode`/`sefazMessage`, ver
    [Erros e Rejeições](/guides/errors) para o contrato completo.
  </Accordion>

  <Accordion title="A API suporta IA para integração?">
    **Sim.** A engineAPI é **AI-Ready**. Veja o guia [Integração com IA](/guides/ai-integration) para detalhes.
  </Accordion>
</AccordionGroup>

## Operacional

<AccordionGroup>
  <Accordion title="Qual o uptime?">
    O SLA varia por plano: a tabela vigente está nos [Termos de
    Uso](https://engineapi.com.br/legal/termos), seção 5.

    A SEFAZ, porém, tem manutenções programadas (geralmente domingos à noite). Nesses períodos, emissões podem falhar com erro `503`. A API retorna automaticamente quando o serviço volta.
  </Accordion>

  <Accordion title="O que acontece se a SEFAZ cair?">
    A engineAPI retorna erro `503 Service Unavailable` com a mensagem da SEFAZ (envelope RFC 7807). Recomendamos:

    1. Implementar retry com backoff (ver [Erros e Rejeições](/guides/errors))
    2. Monitorar o status do SEFAZ via `GET /v1/nfce/status` (ou equivalente do modelo)
    3. Informar o usuário final que o serviço está temporariamente indisponível

    **O que `GET /v1/nfce/status` garante:** o campo `status` só é `UP`/`DOWN` quando a API
    fez uma consulta REAL e autenticada na SEFAZ (`NFE_StatusServico`) com o certificado de
    um emissor seu. Sem um emissor resolvível (sua conta ainda sem emissor cadastrado, ou
    2+ emissores sem informar `issuerId` na query), a resposta é `status: 'UNKNOWN'`: a API
    nunca inventa "no ar" sem ter perguntado de verdade. Com 1 único emissor cadastrado, a
    resolução é automática; com 2+, informe `?issuerId=` pra escolher qual CNPJ consultar.
  </Accordion>

  <Accordion title="Tem webhooks?">
    **Sim.** Configure via `PATCH /v1/webhooks/config` para receber, entre outros:

    * `invoice.authorized`/`invoice.rejected`/`invoice.canceled`
    * `certificate.expiring`

    Veja o guia [Webhooks](/guides/webhooks) para a lista completa de eventos e o formato do payload (`{id, type, timestamp, data}`).
  </Accordion>

  <Accordion title="Qual o prazo para cancelar uma nota?">
    | Modelo | Documento | Prazo                                                                                                                              |
    | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | 55     | NF-e      | 24 horas após a autorização                                                                                                        |
    | 65     | NFC-e     | 30 minutos após a autorização (padrão nacional por UF; em GO, art. 167-S-Q do RCTE-GO), desde que a mercadoria não tenha circulado |

    Passado o prazo, a SEFAZ rejeita com **cStat 501** (repassado verbatim em
    `error.erros[]` no **`400`**) e a nota permanece autorizada. Não há
    cancelamento extemporâneo de NFC-e/NF-e via API. O remédio legal é emitir uma **NF-e
    de devolução** com `finNFe: 4`, `referenciadas` e pagamento sem pagamento (`forma:
            "90"`, valor zero); a API valida essa combinação antes de numerar. Veja o guia
    [NFC-e](/guides/nfce) e [Erros e Rejeições](/guides/errors).
  </Accordion>
</AccordionGroup>

## Suporte

Email: [suporte@engineapi.com.br](mailto:suporte@engineapi.com.br), resposta em até 4 horas úteis. Chat integrado no
[Dashboard](https://app.engineapi.com.br).