Documentação

Notreve Contábil API

API REST de leitura para ERPs e parceiros. Consulte empresas, notas fiscais e baixe XML e PDF da organização autenticada pela chave.

v1.0 REST Somente leitura JSON · XML · PDF

Visão geral

Base de produção: https://api.contabil.notreve.com.br. Todas as rotas usam o prefixo /v1.

Cada organização tem a sua chave. Ela dá acesso às empresas dessa organização. Para consultar uma empresa específica, use empresa_id.

Item	Valor
Ambiente	Produção
Autenticação	`Authorization: Bearer chave_...`
Limite	120 requisições por minuto por chave
Paginação	`proximo_cursor` e `tem_mais`
Datas	`criado_em` em RFC 3339; `competencia` em `AAAA-MM`
Retenção	`retencao_dias` por empresa e `expira_em` por documento

Autenticação

Crie a chave em app.contabil.notreve.com.br → Integrações. A chave aparece uma única vez. Guarde em local seguro.

curl "https://api.contabil.notreve.com.br/v1/empresas" \
  -H "Authorization: Bearer chave_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Se a chave estiver revogada, expirada ou incorreta, a API responde 401.

Formato de resposta

Sucesso:

{
  "dados": { },
  "paginacao": {
    "proximo_cursor": 123,
    "tem_mais": true
  },
  "requisicao_id": "..."
}

Erro:

{
  "erro": {
    "codigo": "nao_encontrado",
    "mensagem": "Documento não encontrado."
  },
  "requisicao_id": "..."
}

Use proximo_cursor na próxima chamada e pare quando tem_mais for false.

Empresas

GET/v1/empresasListar empresas

Parâmetros: limite (1 a 200, padrão 50) e cursor (último CNPJ retornado).

GET/v1/empresas/{id}Consultar empresa

Retorna CNPJ, razão social, nome fantasia, cidade/UF, status e modelos habilitados.

{
  "dados": [
    {
      "id": "uuid",
      "cnpj": "00000000000000",
      "razao_social": "EMPRESA EXEMPLO",
      "nome_fantasia": "Empresa Exemplo",
      "uf": "ES",
      "cidade": "Vila Velha",
      "ativo": true,
      "modelos": ["nfs-e", "nfe"],
      "retencao_dias": 90
    }
  ],
  "paginacao": { "tem_mais": false },
  "requisicao_id": "..."
}

Documentos

GET/v1/documentosListar notas

Filtros: empresa_id, modelo, competencia_de, competencia_ate, limite, cursor.

GET/v1/documentos/{id}Consultar nota

O {id} aceita o id numérico ou a chave de acesso de 44 dígitos.

{
  "dados": [
    {
      "id": 123,
      "chave": "35261012345678000199550010000001231000001234",
      "empresa_id": "uuid",
      "modelo": "nfe",
      "tipo": "nota",
      "competencia": "2026-10",
      "cancelada": false,
      "papel": "recebida",
      "expurgada": false,
      "criado_em": "2026-10-18T14:30:00Z",
      "retencao_dias": 90,
      "expira_em": "2027-01-16T14:30:00Z"
    }
  ],
  "paginacao": {
    "proximo_cursor": 123,
    "tem_mais": true
  },
  "requisicao_id": "..."
}

XML e PDF

GET/v1/documentos/{id}/xmlBaixar XML

Retorna application/xml com Content-Disposition: attachment.

GET/v1/documentos/{id}/pdfBaixar PDF

Retorna application/pdf.

Modelo	PDF
NFS-e	DANFSe quando o XML é do padrão nacional. Outros layouts podem retornar 422.
NF-e	PDF de conferência (não substitui o DANFE oficial)
CT-e / MDF-e	422 PDF indisponível no v1

Retenção: se o conteúdo foi expurgado, a API responde 410. Os metadados continuam disponíveis.

curl "https://api.contabil.notreve.com.br/v1/documentos/35261012345678000199550010000001231000001234/xml" \
  -H "Authorization: Bearer chave_..." \
  -o nota.xml

curl "https://api.contabil.notreve.com.br/v1/documentos/123/pdf" \
  -H "Authorization: Bearer chave_..." \
  -o nota.pdf

Webhooks

Webhook é um canal de notificação da mesma API v1, não uma versão nova. O contrato já está definido; a entrega será ativada em breve.

Eventos: documento.capturado, sync.falhou, certificado.vencendo e importacao.concluida.

POST https://seu-sistema.com/webhooks/notreve
X-Evento: documento.capturado
X-Entrega: evt_...
X-Assinatura: t=1760800000,v1=hmac-sha256-hex

{
  "id": "evt_...",
  "tipo": "documento.capturado",
  "versao": "1",
  "criado_em": "2026-10-18T14:30:00Z",
  "dados": {
    "empresa_id": "uuid",
    "documento": {
      "id": 123,
      "chave": "352610...",
      "modelo": "nfe",
      "competencia": "2026-10"
    }
  }
}

Assinatura: HMAC-SHA256 de t + "." + corpo com o segredo do endpoint.
Retentativas: 1 min, 5 min, 30 min, 2 h, 6 h e 24 h. Responda 2xx para confirmar.
Idempotência: use o id do evento para não processar duas vezes.

Retenção

Cada empresa informa retencao_dias. Cada documento informa retencao_dias e expira_em.

Baixe antes do prazo. Depois de expira_em, o conteúdo pode ser expurgado no próximo ciclo. XML e PDF passam a responder 410. Os metadados continuam disponíveis.

A retenção é definida em contrato e pode variar por empresa.

Erros

HTTP	Código	Quando
401	`chave_invalida` / `chave_expirada`	Chave ausente, inválida, revogada ou expirada.
404	`nao_encontrado`	Empresa ou nota inexistente na organização.
410	`conteudo_expurgado`	Conteúdo expurgado pela retenção.
422	`pdf_indisponivel` / `conteudo_indisponivel`	PDF não suportado para o modelo ou XML indisponível.
429	`limite_excedido`	Limite de 120 requisições por minuto.
500	`erro_interno`	Falha inesperada. Use o `requisicao_id` no suporte.

OpenAPI

Especificação para importar no Postman, Insomnia ou gerar clientes: openapi.json.