Visão Geral da API REST

A Nota Fiscal API segue as convenções RESTful, utilizando verbos HTTP padrão, autenticação via headers e respostas serializadas em JSON com formato envelope.

---

Formato Padrão de Resposta

Respostas de Sucesso (HTTP 200 / 201)

As respostas de sucesso retornam o payload solicitado diretamente ou em envelope claro:

{
  "id": "clt1983hx0001va93jflam789",
  "status": "AUTORIZADA",
  "cStat": 100,
  "xMotivo": "Autorizado o uso da NF-e",
  "chaveAcesso": "35261011222333000181550010000000011987654321",
  "protocolo": "135260000012345"
}

---

Formato Padrão de Erro

Erros na requisição retornam status 4xx ou 5xx com envelope estruturado:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Falha na validação do schema fiscal",
  "details": [
    {
      "field": "destinatario.cpfCnpj",
      "message": "CPF ou CNPJ inválido"
    }
  ]
}

---

Códigos de Status HTTP

Código	Significado	Descrição
200 OK	Sucesso	Requisição processada com êxito (consultas, cancelamentos).
201 Created	Criado	Novo documento fiscal emitido ou certificado cadastrado.
400 Bad Request	Requisição Inválida	Erro no formato do corpo da requisição ou campos ausentes.
401 Unauthorized	Não Autorizado	Chave de API ausente ou inválida.
403 Forbidden	Proibido	O tenant não possui permissão para emitir no ambiente solicitado.
404 Not Found	Não Encontrado	Recurso (nota, certificado ou tenant) inexistente.
409 Conflict	Conflito	Requisição idêntica ainda em processamento.
422 Unprocessable	Regra de Negócio	Rejeição por schema SEFAZ ou divergência fiscal.
500 Server Error	Erro Interno	Falha inesperada no processador fiscal.