Referencia de la API

Emite, consulta y cancela documentos
La API de stackin emite, consulta y cancela documentos fiscales brasileños (NF-e y NFS-e) en tu nombre.
JSON sobre HTTPS
Solicitudes y respuestas son JSON, autenticadas con una API key Bearer.
Delimitada a una empresa
Cada solicitud está delimitada a una empresa — el estado, la dirección y el certificado digital del emisor se resuelven en el servidor a partir de la API key, así que la solicitud solo necesita los campos de negocio (comprador, ítems, montos).

¿Recién empezando?

Cree una cuenta gratuita, genere una SDK key y emita su primer documento en homologation — es gratis e ilimitado, sin tarjeta.

1. Crea tu cuentaRegístrate en unos segundos.2. Genera una SDK keyCrea tu key en el dashboard.3. Emite tu primer documentoPrueba en homologation — gratis e ilimitado.

Base URL

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

Todos los endpoints de la API son relativos a esta base URL.

Autenticación

La API autentica con una API key — mismo mecanismo que el SDK, solo que con el contexto en . Sin login, sin JWT — un header Bearer en cada solicitud.

Cómo obtener una API key

1
Regístrese e inicie sesión en .
2
Cree una empresa — obligatorio antes de la key.
3
Vaya a Settings → API key en el dashboard, y elija el contexto api.
4
Nombre la key y elija su entorno (homologation o production, por defecto homologation) — queda fijo durante toda la vida de la key, no se puede cambiar después.
5
Copie la key de inmediato — se muestra , al crearla, y no se puede recuperar después. Si la pierde, revóquela y cree otra.

cURL

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

Un token ausente o inválido devuelve 401 — ver abajo.

Entornos

Cada API key se crea para exactamente un entorno — o or — elegido al generarla, y fijo durante toda la vida de la key.

No hay campo de entorno en las solicitudes de la API: la key decide a dónde va el documento.

HomologationEntorno de prueba

Gratis e ilimitado — es el entorno de prueba real de SEFAZ/ADN, no un mock — así que integra y prueba todo antes de cambiar a production.

ProductionEntorno real

Para documentos reales. Asegúrate de que todo funcione en homologation antes de cambiar.

Una empresa puede tener keys de ambos entornos a la vez (hasta 3 en total).

Paginación

GET /invoices está paginado con los query params y and (por defecto query params (default , máx , max ).

El envelope de la respuesta siempre incluye:

total: integertotal de filas que coinciden con los filtros.
total_pages: integer
next_page / prev_page: integer | null
data: arraylas filas de la página.

Errores

La API usa códigos HTTP estándar. En la mayoría de los casos la respuesta lleva un objeto detail. Los rechazos de la SEFAZ o ADN devuelven información adicional sobre el autorizador.

Ejemplo de respuesta

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

HTTP	Error	Cuándo	Más información
400	Configuración inválida	La configuración del emisor (certificado, dirección, campos fiscales) está ausente o es inválida.
401	No autorizado	El Bearer token está ausente, expirado, es inválido o no fue creado para el host que estás llamando (`api.stackin.io` vs `sdk.stackin.io`).	Ver detalles
402	Límite alcanzado	La cuota del plan de la empresa para notas de production fue alcanzada y el plan no tiene precio de excedente (trial).
409	Conflicto de operación	La operación solicitada no aplica a ese `document_type` (ej.: una operación exclusiva de nfse en una nfe).
422	Error de validación	El cuerpo de la solicitud falló la validación — campo obligatorio faltante o malformado.
501	No implementado	La firma para ese tipo de documento/país aún no está implementada en el servidor.
502	El autorizador rechazóRechazo del autorizador	El autorizador (SEFAZ/estado o ADN) rechazó la solicitud. `detail.message` trae el error del propio autorizador, y `detail.invoice_id` (solo en la emisión) permite consultar el intento rechazado.	Ver detalles

Rechazos del autorizador

Cuando la SEFAZ o ADN rechaza una operación, la respuesta incluye información adicional.

Usa detail.invoice_id para consultar el estado del intento en /invoices/{{id}}.

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

detail.message: Mensaje devuelto por el autorizador.
detail.invoice_id: Identifica el intento de emisión.

Endpoints

Facturas

Emite un nuevo documento. items[].product.br (ncm, cfop) es obligatorio para , se ignora en , ignored for — un servicio no tiene código de clasificación fiscal, así que nfse solo lee description y amount de cada ítem.

Lista el historial de emisiones de la empresa, paginado (vea Paginación arriba). Filtre con document_type y and (issued, rejected, cancelled).

Consulta el estado actual de un documento directamente en el autorizador por su access key. Requiere como query param.

Cancela un documento previamente autorizado. debe tener al menos 15 caracteres para nfe (el campo xJust del autorizador lo exige). Cancelar no devuelve la cuota del plan — la capacidad del autorizador ya se gastó en la emisión.

Reenvía una emisión fallida por el `id` local del documento (no por su clave de acceso — una nota rechazada no tiene una). Útil para reintentar después de corregir un problema de configuración o una caída del autorizador. Consume crédito como una emisión nueva, ya que es una nueva transmisión.