API REST

Cada capacidade do stackin é acessível por uma API REST documentada e versionada — requisições e respostas JSON, autenticadas com uma única API key Bearer presa a uma empresa e um ambiente (homologation ou production).

Esse é o mesmo contrato em cima do qual os SDKs oficiais são construídos, então tudo que o SDK faz, a API crua também faz — útil pra linguagens sem client oficial ainda, ou integrações que preferem não adicionar dependência.

Paginação é uniforme em todo endpoint de listagem: offset/limit na requisição (padrão limit=20, máx 100), mais sort_by/order_by pra ordenação; a resposta volta com total, page, per_page, total_pages, next_page e prev_page — um único helper de paginação cobre o histórico de emissão não importa o quanto o volume da empresa cresça.

Erros mapeiam pra códigos HTTP reais, com corpo JSON — {"detail": "..."} na maioria dos casos, exceto o 502 que tem formato próprio. 400 é configuração da empresa faltando (geralmente certificado ausente); 401 é key ausente, rotacionada ou não enviada; 402 é cota do plano esgotada (só emissão/reemissão consomem — cancelamento e consulta são grátis); 409 é uma operação que o estado atual do documento não permite (cancelar algo já cancelado, por exemplo); 422 é validação com o campo problemático nomeado no corpo; 501 é tipo de documento ainda sem assinatura implementada nesse fluxo; 502 é o autorizador do governo rejeitando ou falhando ao processar — o único que carrega o código/mensagem do próprio autorizador, já que essa é a informação que decide se o conserto é nos seus dados ou tentar de novo depois.

Não existe funcionalidade "exclusiva de SDK" escondida atrás das bibliotecas cliente — os SDKs existem por tipagem, retry e ergonomia, não pra desbloquear capacidade que a API crua não tem.

Veja a referência completa da API pra autenticação, paginação, códigos de erro e cada endpoint.