API REST

Cada capacidad de stackin es accesible por una API REST documentada y versionada — solicitudes y respuestas JSON, autenticadas con una única API key Bearer ligada a una empresa y un entorno (homologation o production).

Este es el mismo contrato sobre el que están construidos los SDKs oficiales, así que todo lo que el SDK puede hacer, la API cruda también puede — útil para lenguajes sin cliente oficial todavía, o integraciones que prefieren no agregar una dependencia.

La paginación es uniforme en todo endpoint de listado: offset/limit en la solicitud (por defecto limit=20, máx 100), más sort_by/order_by para el orden; la respuesta vuelve con total, page, per_page, total_pages, next_page y prev_page — un único helper de paginación cubre el historial de emisión sin importar cuánto crezca el volumen de la empresa.

Los errores se mapean a códigos HTTP reales, con cuerpo JSON — {"detail": "..."} en la mayoría de los casos, excepto 502, que tiene forma propia. 400 es configuración de la empresa faltante (generalmente un certificado ausente); 401 es clave faltante, rotada o no enviada; 402 es cuota del plan agotada (solo emisión/reemisión la consumen — cancelación y consulta son gratis); 409 es una operación que el estado actual del documento no permite (cancelar algo ya cancelado, por ejemplo); 422 es validación con el campo problemático nombrado en el cuerpo; 501 es un tipo de documento aún sin firma implementada en ese flujo; 502 es el autorizador del gobierno rechazando o fallando al procesar — el único que lleva el código/mensaje del propio autorizador, ya que esa es la información que decide si la solución está en tus datos o en reintentar más tarde.

No existe funcionalidad "exclusiva del SDK" escondida detrás de las bibliotecas cliente — los SDKs existen por tipado, reintentos y ergonomía, no para desbloquear capacidad que la API cruda no tiene.

Consulta la referencia completa de la API para autenticación, paginación, códigos de error y cada endpoint.