Referência da API

Emita, consulte e cancele documentos
A API stackin emite, consulta e cancela documentos fiscais brasileiros (NF-e e NFS-e) em seu nome.
JSON sobre HTTPS
Requisições e respostas são JSON, autenticadas com uma API key Bearer.
Escopada a uma empresa
Toda requisição é escopada a uma empresa — a UF, endereço e certificado digital do emissor são resolvidos no servidor a partir da API key, então a requisição só precisa dos campos de negócio (comprador, itens, valores).

Começando agora?

Crie uma conta gratuita, gere uma SDK key e emita seu primeiro documento em homologation — é grátis e ilimitado, sem cartão.

1. Crie sua contaCadastre-se em alguns segundos.2. Gere uma SDK keyCrie sua key no dashboard.3. Emita seu primeiro documentoTeste em homologation — grátis e ilimitado.

Base URL

https://api.stackin.io/api/v1

Todos os endpoints da API são relativos a essa base URL.

Autenticação

A API autentica com uma API key — mesmo mecanismo do SDK, só que com o contexto em . Sem login, sem JWT — um header Bearer em cada requisição.

Conseguindo uma API key

1
Cadastre-se e faça login em .
2
Crie uma empresa — obrigatório antes da key.
3
Vá em Settings → API key no dashboard, e escolha o contexto api.
4
Nomeie a key e escolha o ambiente (homologation ou production, padrão homologation) — fixo pelo resto da vida da key, não muda depois.
5
Copie a key na hora — ela aparece , na criação, e não pode ser recuperada depois. Perdeu, revoga e cria outra.

cURL

curl https://api.stackin.io/api/v1/invoices \
  -H "Authorization: Bearer $STACKIN_API_KEY"

Token ausente ou inválido retorna 401 — veja abaixo.

Ambientes

Cada API key é criada para exatamente um ambiente — ou or — escolhido ao gerá-la, e fixo pelo resto da vida da key.

Não existe campo de ambiente nas requisições da API: a key decide pra onde vai o documento.

HomologationAmbiente de teste

Grátis e ilimitado — é o ambiente de teste real do SEFAZ/ADN, não é mock — então integre e teste tudo antes de trocar pra production.

ProductionAmbiente real

Para documentos reais. Garanta que tudo funciona em homologation antes de trocar.

Uma empresa pode ter keys dos dois ambientes ao mesmo tempo (até 3 no total).

Paginação

GET /invoices é paginado com os query params e and (padrão query params (default , máx , max ).

O envelope da resposta sempre inclui:

total: integertotal de linhas que batem com os filtros.
total_pages: integer
next_page / prev_page: integer | null
data: arrayas linhas da página.

Erros

A API utiliza códigos HTTP padrão. Na maioria dos casos, a resposta contém um objeto detail. Rejeições da SEFAZ ou ADN retornam informações adicionais sobre o autorizador.

Exemplo de resposta

{
  "detail": "This company has no state set — required for NFe. Set it via PATCH /companies/{id}."
}

HTTP	Erro	Quando	Saiba mais
400	Configuração inválida	A configuração do emissor (certificado, endereço, campos fiscais) está ausente ou inválida.
401	Não autorizado	O Bearer token está ausente, expirado, inválido ou não foi criado para o host que você está chamando (`api.stackin.io` vs `sdk.stackin.io`).	Ver detalhes
402	Limite atingido	A cota do plano da empresa para notas de production foi atingida e o plano não tem preço de excedente (trial).
409	Conflito de operação	A operação pedida não se aplica a esse `document_type` (ex.: operação exclusiva de nfse numa nfe).
422	Erro de validação	O corpo da requisição falhou na validação — campo obrigatório faltando ou malformado.
501	Não implementado	Assinatura para esse tipo de documento/país ainda não implementada no servidor.
502	Autorizador rejeitouRejeição do autorizador	O autorizador (SEFAZ/UF ou ADN) rejeitou a requisição. `detail.message` traz o erro do próprio autorizador, e `detail.invoice_id` (só na emissão) permite consultar a tentativa rejeitada.	Ver detalhes

Rejeições do autorizador

Quando a SEFAZ ou ADN rejeita uma operação, a resposta inclui informações adicionais.

Use detail.invoice_id para consultar o status da tentativa em /invoices/{{id}}.

{
  "detail": {
    "message": "IE do emitente inválida",
    "invoice_id": "inv_8f3c9b2e6a7d"
  }
}

detail.message: Mensagem retornada pelo autorizador.
detail.invoice_id: Identifica a tentativa de emissão.

Endpoints

Notas fiscais

Emite um novo documento. items[].product.br (ncm, cfop) é obrigatório para , ignorado em , ignored for — serviço não tem código de classificação fiscal, então nfse só lê description e amount de cada item.

Lista o histórico de emissões da empresa, paginado (veja Paginação acima). Filtre com document_type e and (issued, rejected, cancelled).

Consulta o status atual de um documento direto no autorizador pela access key. Requer como query param.

Cancela um documento previamente autorizado. precisa ter pelo menos 15 caracteres para nfe (o campo xJust do autorizador exige). Cancelar não devolve cota do plano — a capacidade do autorizador já foi gasta na emissão.

Reenvia uma emissão que falhou, pelo `id` local do documento (não pela chave de acesso — uma nota rejeitada não tem uma). Útil pra retentar depois de corrigir um problema de configuração ou uma indisponibilidade do autorizador. Consome crédito como uma emissão nova, já que é uma nova transmissão.