Documentação da API

Verifica banco local e, com ?remote=1, o webservice SIGEP.

Request

GET http://nf.srv1798916.hstgr.cloud/api/v1/health?remote=1
X-API-Key: <SUA_NFSE_API_KEY>

Resposta 200

{
  "status": "ok",
  "database": "ok",
  "sigep_v2": "online",
  "transmission_enabled": false
}

Consulta CPF no cadastro municipal ou CNPJ no cadastro público. Para CPF, informe o emissor que possui o login do portal.

Request

GET http://nf.srv1798916.hstgr.cloud/api/v1/recipients/{document}?issuer_cnpj={emissor}

Exemplo:
GET http://nf.srv1798916.hstgr.cloud/api/v1/recipients/00372377130?issuer_cnpj=37826351000166

Resposta 200

{
  "document": "00372377130",
  "name": "NOME DO TOMADOR",
  "email": "",
  "registration_status": "Cadastro municipal localizado",
  "address": {
    "street_type": "RUA",
    "street": "38",
    "number": "85",
    "district": "RESIDENCIAL DAS BRISAS",
    "city_code": "5211909",
    "city": "JATAÍ",
    "state": "GO",
    "postal_code": "75803565"
  }
}

Consulta um emissor pelo CNPJ. A listagem completa está em GET /issuers.

GET http://nf.srv1798916.hstgr.cloud/api/v1/issuers/37826351000166

Edita os dados do emissor. O CNPJ da URL permanece inalterado.

{
  "legal_name": "RAZÃO SOCIAL",
  "municipal_registration": "301186501",
  "tax_regime": "NORMAL",
  "certificate_path": "C:\\\\certificados\\\\empresa.pfx",
  "rps_series": "1",
  "next_rps_number": 876,
  "enabled": true
}

DELETE /issuers/{cnpj} exclui o emissor quando ele ainda não possui notas vinculadas.

Envia ou renova o A1 usando multipart/form-data. O servidor valida senha, validade e CNPJ, salva o arquivo e atualiza o caminho automaticamente.

curl -X POST "http://nf.srv1798916.hstgr.cloud/api/v1/issuers/37826351000166/certificate" \
  -H "X-API-Key: <SUA_NFSE_API_KEY>" \
  -F "certificate_file=@empresa.pfx"

Lista retenções cadastradas por CNPJ tomador. Use ?recipient_cnpj=... para filtrar.

GET http://nf.srv1798916.hstgr.cloud/api/v1/recipient-tax-profiles?recipient_cnpj=50565317000143

Request JSON

{
  "profile_name": "IPASGO",
  "recipient_cnpj": "50565317000143",
  "city": "GOIÂNIA",
  "valid_from": "2026-01-01",
  "pis_rate": "0.65",
  "cofins_rate": "3",
  "csll_rate": "1",
  "ir_rate": "1.5",
  "iss_withheld": false
}

Resposta 201

{
  "id": 2,
  "profile_name": "IPASGO",
  "recipient_cnpj": "50565317000143",
  "pis_rate": "0.65",
  "cofins_rate": "3",
  "csll_rate": "1",
  "ir_rate": "1.5",
  "iss_withheld": 0
}

PUT /recipient-tax-profiles/{id} edita usando o mesmo JSON. DELETE /recipient-tax-profiles/{id} exclui.

Inclui uma emissão na fila. Para tomadores cadastrados, omita os valores dos impostos: o sistema calculará automaticamente.

Request JSON

{
  "source_reference": "n8n-pedido-123",
  "issuer_cnpj": "37826351000166",
  "competence": "2026-08-20",
  "service_value": "1000.00",
  "description": "Serviços laboratoriais",
  "recipient": {
    "document": "50565317000143",
    "name": "IPASGO",
    "email": "financeiro@example.com",
    "address": {
      "street_type": "RUA",
      "street": "Nome da rua",
      "number": "100",
      "district": "Centro",
      "city_code": "5208707",
      "state": "GO",
      "postal_code": "74000000"
    }
  }
}

Resposta 201

{
  "id": 1,
  "source_reference": "n8n-pedido-123",
  "issuer_cnpj": "37826351000166",
  "recipient_document": "50565317000143",
  "status": "PENDING",
  "service_value_cents": 100000
}

Repetir a mesma source_reference devolve a emissão existente com HTTP 200, sem duplicar.

PUT /invoices/{id} edita usando o mesmo JSON. DELETE /invoices/{id} exclui. As duas operações só são permitidas antes da assinatura e da reserva do RPS.

Valida dados, impostos e certificado sem transmitir a nota.

POST http://nf.srv1798916.hstgr.cloud/api/v1/invoices/1/validate

Resposta 200

{
  "valid": true,
  "errors": [],
  "invoice": { "id": 1, "status": "VALIDATED" }
}

Assina e transmite ao SIGEP somente quando NFSE_ENABLE_TRANSMISSION=true. Enquanto bloqueada, responde HTTP 409.

Resposta autorizada

{
  "id": 1,
  "status": "AUTHORIZED",
  "nfse_number": "12345",
  "verification_code": "ABC123",
  "pdf_url": "http://nf.srv1798916.hstgr.cloud/api/v1/invoices/1/pdf"
}

GET /invoices/{id}/pdf chama a operação oficial consultarPdfNfseRps e devolve application/pdf. Envie também o cabeçalho X-API-Key.

{
  "error": "transmission_blocked",
  "message": "transmissão real está desabilitada"
}

GET http://nf.srv1798916.hstgr.cloud/api/v1/issuers/37826351000166/rps

Resposta 200

{
  "issuer_cnpj": "37826351000166",
  "series": "1",
  "next_rps": 876,
  "last_allocated_rps": null,
  "last_authorized_rps": null,
  "source": "local"
}

{ "last_used_rps": 875 }