API Reference

A spec completa (todos endpoints, schemas, headers globais como Idempotency-Key + X-RateLimit-*) é gerada automaticamente do código Fastify+Zod e exposta como OpenAPI 3.0 válido.

Acesso direto

📘

Swagger UI interativa: api.zfiscoo.zek.app.br/docs — testa requests no browser, mostra schemas, faz try-it-out com sua API key.


# JSON spec puro
curl https://api.zfiscoo.zek.app.br/docs/json > zfiscoo-openapi.json
 
# Importa em ferramentas que suportam OpenAPI 3:
# - Postman: File → Import → Cole URL
# - Insomnia: Import/Export → URL
# - VS Code REST Client: usa o JSON direto

Gere seu próprio SDK

A spec é OpenAPI 3.0 válido — qualquer gerador funciona. Recomendados:

TypeScript / JavaScript: openapi-typescript-codegen
Go: oapi-codegen
Python: openapi-python-client
Java/Kotlin: openapi-generator-cli
C# / .NET: NSwag

Exemplo TS:


npx openapi-typescript-codegen \
  --input https://api.zfiscoo.zek.app.br/docs/json \
  --output ./src/zfiscoo-types \
  --client fetch

Os types ficam disponíveis pra autocomplete + type-check do client.

SDK oficial TypeScript

O zfiscoo-sdk no npm é auto-gerado dessa mesma spec e publicado a cada release minor. Ver Recipes / Next.js pra exemplos de uso.


pnpm add zfiscoo-sdk

Estrutura da API (endpoints principais)

Recurso	Endpoints
Auth (dashboard)	`POST /v1/auth/{login,signup,logout,refresh}`, `POST /v1/auth/2fa/{setup,verify,disable}`
Account	`GET /v1/account`, `PATCH /v1/account`, `POST /v1/account/force-cancel`
Team	`GET /v1/team/members`, `POST /v1/team/invites`, `PATCH /v1/team/members/:id/role`
Applications (API keys)	`GET/POST/DELETE /v1/applications`, `POST /v1/applications/:id/rotate`
Issuers	`GET/POST /v1/issuers`, `POST /v1/issuers/:id/certificate`, `POST /v1/issuers/:id/csc`, `PATCH /v1/issuers/:id/danfe-settings`
HSM	`GET /v1/hsm/status`, `POST /v1/issuers/:id/migrate-cert-to-kms`
NFC-e (mod 65)	`POST /v1/nfce`, `GET /v1/nfce/:id`, `POST /v1/nfce/:id/cancel`, `GET /v1/nfce/:id/{danfe.pdf,xml,events}`
NF-e (mod 55)	`POST /v1/nfe`, `GET /v1/nfe/:id`, `POST /v1/nfe/:id/{cancel,cce,manifestation}`
NFS-e	`POST /v1/nfse`, `GET /v1/nfse/:id`, `POST /v1/nfse/:id/cancel`
Webhooks	`GET/POST/DELETE /v1/webhooks`, `GET /v1/webhooks/:id/deliveries`, `POST /v1/webhooks/:id/deliveries/:dlvId/replay`, `POST /v1/webhooks/:id/test`
Billing	`GET /v1/billing/subscription`, `GET /v1/billing/invoices`, `POST /v1/billing/upgrade`
Notifications	`GET /v1/notifications`, `POST /v1/notifications/:id/read`, `GET /v1/notifications/stream` (SSE)
Audit	`GET /v1/audit-log`
Search	`GET /v1/search?q=...` (full-text em invoices, issuers, eventos)
Meta	`GET /v1/ufs`, `GET /v1/municipios`
Health	`GET /healthz`, `GET /healthz/deep`

Headers globais documentados em todos os endpoints:

Request (POST/PUT/PATCH): Idempotency-Key
Response (2xx): X-RateLimit-{Limit,Remaining,Reset,Window}, Idempotency-Replay (quando aplicável)