Documentação

Referência completa da API Fiscal SysVelox — autenticação, endpoints, idempotência, webhooks, erros e separação de ambientes.

Nunca integrou com uma API antes?

Comece pelo guia passo a passo — do cadastro da empresa até a primeira nota emitida, sem pular nada.

Ver guia completo

Referência completa de campos (NF-e/NFC-e)

Destinatário completo, pagamento dividido, desconto/frete/troco, ICMS regime normal, IPI, PIS/COFINS reais, IBS/CBS, transportadora, devolução — todo campo, com exemplo.

Ver referência completa

Autenticação

Cada conta tem uma ou mais API Keys, no formato sk_test_... (homologação) ou sk_live_... (produção). Envie em toda requisição:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

A chave completa nunca é armazenada em texto puro — só o hash SHA-256. O valor em texto puro só existe no retorno da criação; se for perdido, é preciso gerar uma nova. Chaves podem ser revogadas a qualquer momento, permitindo rotação sem downtime.

Ambientes (test / live)

O ambiente de emissão é decidido pela API Key usada, nunca por um campo enviado no payload. Isso evita que um erro de configuração do integrador emita uma nota fiscal real usando credencial de teste, ou vice-versa.

sk_test_... — só emite contra a SEFAZ de homologação. Nunca autoriza um documento fiscal real.
sk_live_... — só emite contra a SEFAZ de produção.

Endpoints

Método	Rota	Descrição
POST	`/v1/nfce`	Emite uma NFC-e (modelo 65).
POST	`/v1/nfe`	Emite uma NF-e (modelo 55).
POST	`/v1/nfse`	Emite uma NFS-e (padrão nacional), por município aderente.
GET	`/v1/notas/{id}`	Consulta o status de um documento.
GET	`/v1/notas/{id}/xml`	Baixa o XML autorizado.
GET	`/v1/notas/{id}/danfe`	Baixa o PDF (DANFE/DANFCE/DANFSE).
POST	`/v1/notas/{id}/cancelamento`	Cancela um documento já autorizado.

Exemplo — emitir uma NFC-e

curl -X POST https://api.sysvelox.com/v1/nfce \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: venda-123" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "emp_xxx",
    "items": [
      { "description": "Produto exemplo", "ncm": "12345678", "cfop": "5102",
        "unit": "UN", "quantity": 1, "unit_price_cents": 1000, "total_cents": 1000,
        "cst_icms": "102" }
    ]
  }'

# resposta imediata (assíncrona)
{ "id": "nf_xxxxxxxxx", "status": "processando" }

Idempotência

POST /v1/nfce, /v1/nfe e /v1/nfse aceitam o header Idempotency-Key, único por (conta, CNPJ, chave):

Idempotency-Key: venda-123456

Reenviar a mesma chave com o mesmo payload devolve a operação original — não cria um novo documento.
Reenviar a mesma chave com payload diferente é erro 409.
A garantia é uma constraint UNIQUE no banco, não uma checagem só em código — cobre corretamente duas requisições simultâneas com a mesma chave (retry de rede, duplo clique).

Webhooks

Eventos disponíveis: {nfce,nfe,nfse}.authorized, .rejected, .cancelled.

{
  "event": "nfce.authorized",
  "document_id": "nf_xxxxx",
  "company_id": "emp_xxxxx",
  "number": 123,
  "series": 1,
  "access_key": "...",
  "protocol": "...",
  "authorized_at": "..."
}

Toda entrega leva um cabeçalho de assinatura HMAC-SHA256, com timestamp incluso no cálculo (protege contra replay):

X-ApiNotas-Signature: t=1700000000,v1=<hmac-sha256 hex>
X-ApiNotas-Event: nfce.authorized

Assinatura = HMAC-SHA256("{timestamp}.{corpo}", secret). Valide a janela de tempo (ex.: 5 minutos) antes de recalcular e comparar a assinatura. Retentativas com backoff exponencial (30s até 32min, até 8 tentativas); redirecionamentos HTTP nunca são seguidos automaticamente.

Erros

{
  "error": {
    "code": "INVALID_NCM",
    "message": "O NCM informado é inválido.",
    "field": "items.0.ncm"
  }
}

Nunca exposto na resposta: stack trace, caminhos internos, SQL, senha ou certificado.

HTTP	Uso
`200`	Sucesso (GET/consulta)
`201`	Recurso criado
`202`	Aceito para processamento assíncrono
`400`	Requisição malformada
`401`	Autenticação ausente/inválida
`403`	Autenticado mas sem permissão
`404`	Recurso não encontrado
`409`	Conflito (Idempotency-Key reusada com payload diferente)
`422`	Payload válido em forma, mas semanticamente inválido
`429`	Rate limit excedido
`500`	Erro interno
`503`	Indisponibilidade temporária (ex.: SEFAZ fora do ar)

Toda resposta autenticada também traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset — janela fixa de 1 minuto por API Key. Ao exceder, 429 com Retry-After.

E a franquia mensal, em X-Usage-Limit, X-Usage-Remaining e X-Usage-Reset (fim do ciclo atual) — sem precisar consultar o portal.

Exemplos de código

Exemplos completos e testados em cURL, PHP, Node.js, Python e Java — com arquivo pra baixar em cada um.

Ver exemplos e baixar modelos

Dúvidas?

Pergunte no fórum (é preciso entrar) ou fale com a equipe.