API REST de NFS-e

Seu sistema pede a nota. A Seelo emite.

A Seelo API é uma API REST. Você manda os dados do serviço em JSON e a gente calcula os impostos, monta o XML, assina com o certificado da empresa, transmite para a prefeitura e avisa o seu sistema quando sair o resultado.

RESTJSONHTTPSBearer tokenWebhooks

Entrar na lista de espera Ver endpoints

202 resposta da emissão

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "c1f4a9d2-7b3e-4c55-8e21-0a6d9f3b5e77",
  "objeto": "nfse",
  "id_externo": "pedido-98765",
  "status": "processando",
  "ambiente": "homologacao",
  "numero": null
}

Como funciona

Da chave à nota autorizada em quatro passos.

Crie a chave

No Painel da API você gera uma chave de teste (sk_test_) e uma de produção (sk_live_).

Envie a nota

Um POST /v1/nfse com a empresa, o tomador e o serviço, em JSON.

Receba o 202

A API responde na hora com o id da nota e o status processando.

Saiba o resultado

Quando a prefeitura responder, o webhook avisa seu sistema. Ou consulte por GET.

Primeira chamada

Qualquer linguagem que faça HTTP.

Não existe biblioteca para instalar. A integração é uma requisição POST com um JSON, igual a qualquer outra API REST que o seu time já usa.

Endereço base: https://api.seelo.com.br/v1
Autenticação: Authorization: Bearer sk_...
Sem nota duplicada: Envie o id_externo do seu pedido ou o cabeçalho Idempotency-Key. Repetir a chamada devolve a mesma nota.

curl -X POST https://api.seelo.com.br/v1/nfse \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-98765" \
  -d '{
    "empresa_id": "8b0d6f0e-...",
    "id_externo": "pedido-98765",
    "tomador": { "documento": "12345678000199" },
    "servico": { "discriminacao": "Mensalidade", "valor": 1500 }
  }'

O básico

Uma API REST, sem surpresa.

HTTPS e JSON

Corpo e resposta em JSON, UTF-8. Datas no formato ISO 8601 e valores em reais.

Bearer token

Toda chamada leva o cabeçalho Authorization: Bearer com a sua chave.

Verbos padrão

GET consulta, POST cria ou executa uma ação, PATCH altera, DELETE remove.

Sem SDK

Se a sua linguagem faz uma requisição HTTP, ela já fala com a Seelo.

Endpoints

Os recursos principais.

Notas, empresas, tomadores, serviços, webhooks e exportações. Todos sob /v1, com os mesmos padrões de resposta e de erro.

Status da nota

processandoRecebida e enviada para a prefeitura.
autorizadaNota válida, com número, PDF e XML.
rejeitadaA prefeitura recusou. O motivo vem no corpo.
canceladaCancelamento aceito pela prefeitura.

POST/nfseEmitir nota
POST/nfse/loteEmitir em lote
GET/nfse/{id}Consultar nota
GET/nfse/externo/{id_externo}Consultar pelo id do seu sistema
GET/nfse/{id}/pdfBaixar PDF (DANFSe)
GET/nfse/{id}/xmlBaixar XML
POST/nfse/{id}/cancelarCancelar nota
POST/nfse/{id}/substituirSubstituir nota
POST/nfse/simularSimular impostos sem emitir
POST/empresasCadastrar empresa emissora
POST/empresas/{id}/certificadoEnviar certificado A1
POST/tomadoresCadastrar tomador
POST/servicosCadastrar serviço
POST/webhooksCadastrar webhook
POST/exportacoesPedir ZIP do período
GET/cnpj/{cnpj}Consultar CNPJ

Webhooks

A Seelo faz um POST no endereço que você cadastrar sempre que a nota mudar de status. Cada envio é assinado (HMAC SHA-256) e, se falhar, tentamos de novo por até 24 horas.

POST https://seu-sistema.com/webhooks/nfse
X-Signature: sha256=8f2a...c41e

{
  "evento": "nfse.autorizada",
  "data": {
    "id": "c1f4a9d2-...",
    "numero": "2026000001234",
    "valores": { "servico": 1500.00, "iss": 75.00 },
    "pdf_url": "https://.../nfse.pdf"
  }
}

Códigos de resposta

Status HTTP padrão. Todo erro volta com um código e uma mensagem em português.

200 / 201Deu certo. 200 também quando o id_externo já existe.
202Aceito, em processamento.
400JSON mal formado ou campo inválido.
401Chave ausente, errada ou revogada.
403A chave não tem escopo para essa empresa ou ação.
404Recurso não encontrado.
409Conflito, como Idempotency-Key reaproveitada.
422Dados válidos, mas a regra fiscal não fecha.
429Limite de requisições. Espere um pouco e repita.
5xxErro do nosso lado ou da prefeitura. Pode repetir.

Recursos

O que já vem junto.

Emissor Nacional

Padrão nacional da NFS-e, com adaptadores para prefeituras com sistema próprio.

Webhooks com reenvio

Tentativas em 1 min, 5 min, 30 min, 2 h, 12 h e 24 h. Histórico e reenvio manual.

Sem nota duplicada

Mesmo id_externo devolve a mesma nota. Antes de reenviar, consultamos o provedor.

Sandbox de verdade

Chaves sk_test_ falam com a homologação. Valores especiais simulam rejeição e queda.

Chaves com escopo

Só leitura, só emissão ou empresas específicas. Revogue a qualquer momento.

Limites claros

Rate limit por plano, cabeçalhos de uso e página pública de status.

IBS e CBS prontos

Campos da reforma tributária já no leiaute, sem quebrar sua integração.

Certificado no cofre

Arquivo .pfx e senha criptografados. Nunca são devolvidos pela API.

Quer integrar quando abrir?

Entre na lista e receba o acesso ao sandbox primeiro.

Entrar na lista de espera