Referência da API

API REST v1. Erros em application/problem+json (RFC 9457). Paginação por cursor. Webhooks assinados com HMAC-SHA256.

Versão 0.1.0. Gerado de openapi.json — não edite à mão.

Sessão do painel web

Entrar (painel web)

http

POST /api/v1/auth/login

Corpo: LoginInput

Respostas: 200 Me — Define o cookie de sessão · 401 · 429

Sair

http

POST /api/v1/auth/logout

Respostas: 204

Usuário logado

http

GET /api/v1/auth/me

Autenticação: session

Respostas: 200 Me · 401

Uso das telas (painel)

http

POST /api/v1/telemetry

Lote de até 50 eventos do painel: tela aberta e tempo nela, ou ação marcada. Uso interno do painel (sessão).

Autenticação: session

Corpo: UiBatch

Respostas: 204 · 400 · 401

Dados fiscais e certificado A1 da empresa emissora

GET /api/v1/issuer

http

GET /api/v1/issuer

Respostas: 200 IssuerEnvelope · 403 — Só o dono, por sessão

PUT /api/v1/issuer

http

PUT /api/v1/issuer

Corpo: IssuerInput

Respostas: 200 Issuer · 400 — Dado inválido · 403 · 409 — CNPJ em uso ou troca com certificado ativo

GET /api/v1/issuer/certificate

http

GET /api/v1/issuer/certificate

Respostas: 200 CertificateEnvelope · 403 — Só o dono, por sessão

POST /api/v1/issuer/certificate

http

POST /api/v1/issuer/certificate

Corpo: UploadCertificate

Respostas: 201 Certificate · 403 — Só o dono, por sessão, com a senha da conta · 422 — Certificado recusado (motivo em detail)

DELETE /api/v1/issuer/certificate

http

DELETE /api/v1/issuer/certificate

Corpo: RemoveCertificate

Respostas: 204 · 403 — Só o dono, por sessão, com a senha da conta · 404

GET /api/v1/issuer/status

http

GET /api/v1/issuer/status

Autenticação: api_key (invoices:read)

Respostas: 200 IssuerStatus

Emissão, consulta e cancelamento de NFS-e

Listar notas

http

GET /api/v1/invoices

Autenticação: api_key (invoices:read) ou session

Parâmetro	Onde	Tipo	Descrição
`limit`	query	integer	1 a 100 (padrão 50).
`cursor`	query	string
`status`	query	string	`processing`, `authorized`, `rejected` ou `cancelled`.
`external_ref`	query	string

Respostas: 200 InvoicePage · 400

Emitir nota

http

POST /api/v1/invoices

Responde 202 com a nota em processing; o envio ao governo é assíncrono (acompanhe pelo GET ou pelo webhook invoice.authorized/invoice.rejected). Idempotency-Key obrigatório: repetir com a mesma chave e o mesmo corpo devolve a mesma nota.

Autenticação: api_key (invoices:write) ou session

Parâmetro	Onde	Tipo	Descrição
`Idempotency-Key`	header	string	Chave única da operação (até 100 caracteres)

Corpo: NewInvoice

Respostas: 202 Invoice · 400 · 409 — Já há nota viva para o external_ref · 422 — Empresa não pronta para emitir, ou chave repetida com outro corpo

Buscar nota

http

GET /api/v1/invoices/{id}

Autenticação: api_key (invoices:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	string

Respostas: 200 Invoice · 404

Cancelar nota

http

POST /api/v1/invoices/{id}/cancel

Responde 202; o cancelamento é assíncrono (webhook invoice.cancelled ou invoice.cancellation_rejected). Idempotency-Key obrigatório.

Autenticação: api_key (invoices:cancel) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	string
`Idempotency-Key`	header	string

Corpo: CancelInput

Respostas: 202 Invoice · 400 · 404 · 409

XML da NFS-e

http

GET /api/v1/invoices/{id}/xml

Autenticação: api_key (invoices:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	string

Respostas: 200 · 404 · 409

Chaves para integrações

Listar API keys ativas

http

GET /api/v1/api-keys

Autenticação: session

Respostas: 200 ApiKey[]

Criar API key

http

POST /api/v1/api-keys

Autenticação: session

Corpo: NewApiKey

Respostas: 201 CreatedApiKey · 400

Revogar API key

http

DELETE /api/v1/api-keys/{id}

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 204 · 404