Referencia de la API

Esta sección describe los endpoints públicos del API de e-Miti, los shapes de request/response y los errores que podés encontrar.

Base URL

https://api.emiti.fravelabs.com

Todos los paths de esta referencia son relativos a esta base.

Autenticación

Todos los endpoints (excepto /health y /openapi.json) requieren el header Authorization. Para integraciones máquina-a-máquina usá ApiKey; el panel usa Bearer. Mirá la guía de autenticación para más detalle.

curl https://api.emiti.fravelabs.com/v1/de \
  -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx"

Rate limits

Los límites se aplican por principal (API key individual o usuario JWT) en ventanas de 1 minuto. Un tenant con múltiples API keys tiene cuota independiente por key.

Plan	Límite por principal
`emiti` (starter)	100 req/min
`api`	600 req/min
`hybrid`	600 req/min
`pro`	2 000 req/min
`enterprise`	10 000 req/min

Toda respuesta incluye estos headers:

Header	Descripción
`X-RateLimit-Limit`	Límite del plan (req/min).
`X-RateLimit-Remaining`	Requests restantes en la ventana actual.
`X-RateLimit-Reset`	Epoch UTC (segundos) en que se reinicia la ventana.

Cuando excedés el límite recibís 429 con header Retry-After (segundos hasta que se reinicia la ventana) y este body:

{
  "error": {
    "codigo": "RATE_LIMIT_EXCEDIDO",
    "mensaje": "Excediste el límite de 600 requests/min. Reintentá en 38s.",
    "request_id": "01HXY4Z...",
    "limit": 600,
    "reset_at": 1751916060
  }
}

Formato de errores

Todas las respuestas de error siguen este shape:

{
  "error": {
    "codigo": "DE_NO_ENCONTRADO",
    "mensaje": "No se encontró el documento solicitado.",
    "request_id": "01HXY4Z..."
  }
}

Códigos comunes:

Código	Status HTTP	Significado
`AUTH_APIKEY_INVALIDA`	401	Falta el header `Authorization` o la clave es inválida.
`TENANT_SUSPENDIDO`	403	El tenant está suspendido (impago, baja, etc.).
`RATE_LIMIT_EXCEDIDO`	429	Superaste el límite de requests por minuto de tu plan.
`VALIDACION_MULTIPLES_CAMPOS`	400	Errores de validación del request. El campo `errores[]` detalla cada uno.
`DE_NO_ENCONTRADO`	404	El CDC consultado no existe o pertenece a otro tenant.
`SIFEN_RECHAZO`	422	SIFEN rechazó el documento. `extra.codigo_sifen` y `extra.cdc` traen el detalle. Ver errores SIFEN.
`SIFEN_NO_DISPONIBLE`	503	SIFEN está caído o respondió error de red. Reintentar después.

Para errores de validación, el body incluye un array extra.errores[]:

{
  "error": {
    "codigo": "VALIDACION_MULTIPLES_CAMPOS",
    "mensaje": "Hay errores en el request.",
    "request_id": "01HXY4Z...",
    "extra": {
      "errores": [
        { "campo": "items.0.precio_unitario", "mensaje": "debe ser mayor o igual a 0" },
        { "campo": "receptor.numero_documento", "mensaje": "campo requerido" }
      ]
    }
  }
}

Versionado

La API está bajo el prefijo /v1. Cambios incompatibles van a publicarse bajo /v2 sin romper v1 por un período de deprecación previsible.

Endpoints públicos (sin auth)

Path	Para qué
`GET /health`	Healthcheck — devuelve `{"status": "ok", "db": "connected"}`.
`GET /openapi.json`	Schema OpenAPI 3.x del API. Usado por este sitio para generar el playground.

Introducción

Emisión y consulta

Eventos sobre DE

Receptores y series

Datos de referencia

Referencia de la API

Base URL

Autenticación

Rate limits

Formato de errores

Versionado

Endpoints públicos (sin auth)

​Base URL

​Autenticación

​Rate limits

​Formato de errores

​Versionado

​Endpoints públicos (sin auth)

Base URL

Autenticación

Rate limits

Formato de errores

Versionado

Endpoints públicos (sin auth)