Prévia: a API abre junto com o painel.

Erros e limites

Todo erro da API tem o mesmo formato, em português, com o que aconteceu e o que fazer:

{
  "erro": {
    "codigo": "dados_invalidos",
    "mensagem": "A nota tem 1 campo para corrigir.",
    "como_resolver": "Corrija os campos de \"detalhes\" e envie de novo. Nada foi enviado à SEFIN.",
    "detalhes": [
      {
        "campo": "valores.aliquota_iss",
        "mensagem": "Alíquota do ISS: não informe quando o ISS não é retido (regra E0625).",
        "codigo_sefin": "E0625"
      }
    ],
    "requisicao_id": "req_01JC8Z5N3QK7T2V9X5B6N1R0QE"
  }
}

• codigo: estável, para o seu código decidir o que fazer. A lista está abaixo.
• mensagem e como_resolver: para mostrar a uma pessoa.
• detalhes: um item por campo, com o caminho (tomador.documento) e, quando a regra é da SEFIN, o código dela em codigo_sefin.
• codigo_sefin: quando a recusa veio da SEFIN, o código principal.
• nota_id: a nota envolvida, quando há (por exemplo, a nota rejeitada).
• requisicao_id: informe no chamado se precisar de ajuda.

Recusa antes do envio e recusa da SEFIN

O NFSeIA confere as regras da SEFIN antes de enviar. O que dá para saber antes volta como 400 dados_invalidos: nada foi enviado, nada foi criado, nenhum número foi gasto. O que só a SEFIN sabe (por exemplo, regras do município) volta como 422 nota_rejeitada, e a nota fica guardada como rejeitada, com os erros traduzidos. Nos dois casos, corrija e emita de novo com a mesma referencia_externa.

422 só sai quando a recusa é definitiva e conferida: o NFSeIA consulta a SEFIN pelo Id da DPS e só marca rejeitada quando a nota comprovadamente não existe lá. Se a SEFIN disser que a DPS já existe (E0014), se a consulta não for conclusiva ou se o XML não conferir, a resposta é 202 com a nota pendente (motivo conferindo_identidade), e a referência continua presa a ela.

Quando repetir

• Pode repetir com a mesma Idempotency-Key: 409 idempotencia_em_andamento, 429, 500 e 503, depois do tempo de Retry-After. Essas respostas não ficam guardadas, e não há risco de nota em dobro: se a falha veio depois do envio à SEFIN, repetir devolve o estado atual da nota.
• Corrija antes de repetir: 400, 401, 402, 403, 404, 409 idempotencia_reutilizada e 422. Repetir igual dá o mesmo erro.
• 202 com nota pendente não é erro. Não repita a emissão: a nota pode estar sendo autorizada. Espere o webhook ou consulte a nota.

O que nunca aparece num erro

Um erro traz só os campos do formato acima. Nunca vão em resposta, erro ou conteúdo entregue à IA: o corpo bruto da SEFIN, XML de DPS ou NFS-e, chaves, segredos ou qualquer material de certificado. As mensagens da SEFIN chegam traduzidas, com o código em codigo_sefin.

Códigos

Qualquer operação pode responder 401, 403, 429, 500 e 503, além das listadas na referência.

Limites

Os valores são os iniciais e podem subir com o uso; mudanças entram aqui antes de valer.

Toda resposta traz os cabeçalhos do limite de requisições:

Passou do limite, a resposta é 429, com Retry-After em segundos:

{
  "erro": {
    "codigo": "limite_de_requisicoes",
    "mensagem": "Esta chave passou de 120 requisições por minuto.",
    "como_resolver": "Espere 12 segundos (cabeçalho Retry-After) e tente de novo.",
    "detalhes": [],
    "requisicao_id": "req_01JC8Z6C6EA0H5J2M8R9C4F3EV"
  }
}

Cota do plano

A cota de notas é por mês e conta só as notas de produção autorizadas. Ao chegar a 80% e a 95%, o e-mail da empresa e o webhook cota.perto_do_fim avisam. Acabou a cota, a emissão volta 402 cota_esgotada até a troca de plano (em um clique, no painel) ou o mês seguinte. Não há cobrança de excedente.