API REST - Estoque NFe

Autenticacao

Todas as rotas exigem um token de usuario no header Authorization. O token e gerado no portal Optago, na tela do usuario, aba Tokens: clique em Gerar token, de um nome que lembre onde ele vai ser usado e copie o valor na hora, porque ele aparece uma unica vez.

Caracteristica	Como funciona
Validade	Nao expira sozinho. Vale enquanto voce nao revogar, o que combina com integracao e cliente MCP que ficam configurados.
Revogacao	Pelo proprio portal, na mesma aba Tokens. Pode levar ate 5 minutos para deixar de valer aqui, porque a validacao fica em cache.
Escopo	Respeitado na chamada: um token Somente leitura consulta e baixa arquivos, mas nao manifesta (resposta `403 forbidden`).

Headers

Header	Valor
Authorization	`Bearer <token>` - obrigatorio em todas as rotas
Content-Type	`application/json` - obrigatorio apenas em requisicoes com body (POST)

Exemplo

curl "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe" \
  -H "Authorization: Bearer <seu-token>"

O usuario do token precisa ter acesso ativo ao sistema estoque-nfe no SSO Optago, e pertencer a empresa do CNPJ consultado. Sem isso a resposta e 403 forbidden mesmo com token valido. Para manifestar, o usuario precisa ainda ser gestor da empresa.

Rate limit

As rotas sao limitadas a 120 requisicoes por minuto por usuario (e 600 por minuto por IP, como guarda). Ao exceder, a API responde 429 rate_limited com o header Retry-After em segundos. O limite vale igualmente para a API REST e para o servidor MCP.

Listar documentos capturados

Retorna os documentos fiscais recebidos da SEFAZ via Distribuicao DFe. Suporta filtragem por status de manifestacao, disponibilidade de XML e periodo de emissao, com paginacao.

GET /api/v1/{cnpj}/nfe

Parametros de rota

Parametro	Tipo	Descricao
cnpj	string	obrigatorio CNPJ da empresa, apenas digitos (14 caracteres). Ex: `12345678000190`. O usuario autenticado deve pertencer a ela.

Query string

Parametro	Tipo	Padrao	Descricao
manifestacao_status	string	-	opcional Filtra por status: `pendente`, `enviada`, `expirado`.
xml_disponivel	string	-	opcional Filtra por disponibilidade: `nao_verificado`, `disponivel`, `indisponivel`.
data_de	string	-	opcional Data de emissao minima no formato `YYYY-MM-DD`.
data_ate	string	-	opcional Data de emissao maxima no formato `YYYY-MM-DD`.
page	integer	1	opcional Numero da pagina.
per_page	integer	50	opcional Itens por pagina. Maximo: `200`.

Requisicao

curl "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe?manifestacao_status=pendente&per_page=10" \
  -H "Authorization: Bearer <token>"

Resposta 200 OK

{
  "data": [
    {
      "chave_acesso":          "35240812345678901234550010000001231000012344",
      "nsu":                    "000000000102458",
      "emitente_cnpj":         "12345678901234",
      "emitente_nome":         "Fornecedor Exemplo Ltda",
      "valor_nf":              4820.50,
      "data_emissao":          "2026-08-18",
      "situacao_sefaz":        "1",
      "xml_disponivel":        "disponivel",
      "importado":             false,
      "manifestacao_tipo":     null,
      "manifestacao_status":   "pendente",
      "manifestacao_protocolo": null,
      "manifestacao_enviada_em": null,
      "created_at":            "2026-08-18 03:15:42",
      "updated_at":            "2026-08-18 03:15:42"
    }
  ],
  "pager": {
    "page":     1,
    "per_page": 10,
    "total":    47,
    "pages":    5
  }
}

Bearer Token

CNPJ da empresa apenas digitos

Filtros opcionais

GET https://estoquenfe.optago.app.br/api/v1/{cnpj}/nfe

Obter XML da NF-e

Retorna o XML completo e autorizado da NF-e (procNFe). O sistema busca primeiro no armazenamento local; se nao encontrado, consulta a SEFAZ via DistDFe. A resposta e application/xml com header de download.

GET /api/v1/{cnpj}/nfe/{chave_acesso}/xml

Parametros de rota

Parametro	Tipo	Descricao
cnpj	string	obrigatorio CNPJ da empresa, apenas digitos.
chave_acesso	string	obrigatorio Chave de acesso da NF-e com 44 digitos, retornada pelo endpoint de listagem.

Retorna 409 xml_unavailable quando o XML completo ainda nao esta disponivel na SEFAZ. Neste caso, o campo xml_disponivel do documento sera nao_verificado ou indisponivel - aguarde a disponibilizacao e tente novamente.

Requisicao - salvar como arquivo

curl "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe/35240812345678901234550010000001231000012344/xml" \
  -H "Authorization: Bearer <token>" \
  -o nota.xml

Resposta

Status	Content-Type	Descricao
200 OK	application/xml	XML completo (`procNFe`) com protocolo de autorizacao da SEFAZ.
409	application/json	XML nao disponivel - `error: "xml_unavailable"`, com mensagem explicativa.

Bearer Token

CNPJ da empresa apenas digitos

Chave de acesso 44 digitos

GET https://estoquenfe.optago.app.br/api/v1/{cnpj}/nfe/{chave}/xml

Obter PDF (DANFE) da NF-e

Gera o DANFE (representacao grafica da NF-e) em PDF a partir do mesmo XML autorizado. Mesma seguranca do XML: o CNPJ e resolvido, o acesso do usuario do token e validado e o documento e buscado pela chave. A resposta e application/pdf com header de download.

GET /api/v1/{cnpj}/nfe/{chave_acesso}/pdf

Parametros de rota

Parametro	Tipo	Descricao
cnpj	string	obrigatorio CNPJ da empresa, apenas digitos.
chave_acesso	string	obrigatorio Chave de acesso da NF-e com 44 digitos.

O PDF so pode ser gerado quando o XML completo esta disponivel. Se o XML ainda nao foi liberado pela SEFAZ, retorna 409 xml_unavailable (mesma regra do endpoint de XML).

Requisicao - salvar como arquivo

curl "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe/35240812345678901234550010000001231000012344/pdf" \
  -H "Authorization: Bearer <token>" \
  -o danfe.pdf

Resposta

Status	Content-Type	Descricao
200 OK	application/pdf	DANFE em PDF pronto para impressao.
409	application/json	XML nao disponivel - `error: "xml_unavailable"`.

Bearer Token

CNPJ da empresa apenas digitos

Chave de acesso 44 digitos

GET https://estoquenfe.optago.app.br/api/v1/{cnpj}/nfe/{chave}/pdf

Manifestar documento

Registra a manifestacao do destinatario para um documento SEFAZ. Requer papel gestor na empresa - operadores nao tem permissao. Retorna o documento atualizado com o novo status de manifestacao.

POST /api/v1/{cnpj}/nfe/{chave_acesso}/manifestar

Parametros de rota

Parametro	Tipo	Descricao
cnpj	string	obrigatorio CNPJ da empresa, apenas digitos.
chave_acesso	string	obrigatorio Chave de acesso da NF-e com 44 digitos.

Body JSON

Campo	Tipo	Descricao
tipo	string	obrigatorio Tipo de manifestacao. Ver tipos disponiveis.
justificativa	string	condicional Obrigatorio quando `tipo = "operacao_nao_realizada"`. Minimo de 15 caracteres.

Requisicao - confirmacao de operacao

curl -X POST "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe/35240812345678901234550010000001231000012344/manifestar" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tipo":"confirmacao"}'

Requisicao - operacao nao realizada

curl -X POST "https://estoquenfe.optago.app.br/api/v1/12345678000190/nfe/35240812345678901234550010000001231000012344/manifestar" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tipo":"operacao_nao_realizada","justificativa":"Mercadoria devolvida ao remetente antes do recebimento."}'

Resposta 200 OK

{
  "ok": true,
  "documento": {
    "chave_acesso":           "35240812345678901234550010000001231000012344",
    ...
    "manifestacao_tipo":      "confirmacao",
    "manifestacao_status":    "enviada",
    "manifestacao_protocolo":  "135240800012345678",
    "manifestacao_enviada_em":  "2026-08-21 14:32:05"
  }
}

Manifestacoes do tipo ciencia podem ser reenviadas. As demais (confirmacao, desconhecimento, operacao_nao_realizada) sao finais e irreversiveis - a SEFAZ retorna erro se ja existir uma.

Bearer Token

CNPJ da empresa apenas digitos

Chave de acesso 44 digitos

tipo body JSON

justificativa obrigatoria para operacao_nao_realizada

POST https://estoquenfe.optago.app.br/api/v1/{cnpj}/nfe/{chave}/manifestar

Tipos de manifestacao

Os tipos seguem os eventos previstos na legislacao da NF-e. Apenas ciencia e provisorio - os demais sao finais e irreversiveis.

tipo	Evento SEFAZ	Final?	Descricao
ciencia	210210	Nao	Ciencia da Operacao. Destinatario tomou conhecimento, mas ainda nao confirmou. Nao requer justificativa.
confirmacao	210200	Sim	Confirmacao da Operacao. Mercadoria recebida e operacao confirmada. Nao requer justificativa.
desconhecimento	210220	Sim	Desconhecimento da Operacao. O destinatario nao reconhece a transacao. Nao requer justificativa.
operacao_nao_realizada	210240	Sim	Operacao Nao Realizada. Mercadoria nao entregue ou operacao desfeita. Requer `justificativa` com no minimo 15 caracteres.

Erros

Toda resposta de erro segue o mesmo formato JSON, com error (codigo de maquina estavel) e message (descricao em portugues).

Formato de erro

{
  "error":   "unauthorized",
  "message": "Token ausente. Use Authorization: Bearer <token>."
}

HTTP	error	Quando ocorre
400	invalid_cnpj	CNPJ informado nao tem 14 digitos numericos.
401	unauthorized	Header `Authorization` ausente, token malformado, expirado ou revogado no portal.
403	forbidden	Conta sem acesso ao estoque-nfe (`access: false`), usuario nao pertence a empresa, operador tentando manifestar (requer papel `gestor`), ou token de escopo `Somente leitura` tentando manifestar.
404	not_found	Empresa inexistente ou inativa, ou documento nao encontrado na empresa.
409	xml_unavailable	XML completo (`procNFe`) ainda nao disponivel na SEFAZ. Vale para os endpoints de XML e de PDF (o PDF depende do XML).
422	validation	Campo obrigatorio ausente no body (ex: `tipo` nao informado no POST de manifestacao).
422	manifestacao_failed	SEFAZ rejeitou a manifestacao (regra de negocio: ja manifestada, estado invalido, etc.). O campo `message` traz a mensagem original da SEFAZ.
429	rate_limited	Limite de requisicoes excedido (120/min por usuario, 600/min por IP). O header `Retry-After` traz os segundos ate liberar.
500	internal_error	Falha de comunicacao com a SEFAZ ou erro interno. Detalhes registrados nos logs do servidor.
503	sso_unavailable	O SSO Optago nao respondeu a validacao do token. Nao quer dizer token invalido: tente de novo em instantes.

Api de Captura de documentos na Sefaz - Estoque NFe