Autenticación y contexto

La API usa HTTP Bearer con la API_KEY de tu ApiAccess.

Authorization: Bearer <API_KEY>

Obtener la API_KEY

1. Ingresá al panel de Host Factura con tu usuario administrador.
2. En Configuración → API, creá un nuevo Access. Opcionalmente asocialo a una sucursal específica para que las emisiones queden atribuidas a esa sucursal sin necesidad de header.
3. Al crearlo se muestra una sola vez la API_KEY. Copiala a tu vault (1Password, AWS Secrets Manager, Vault, etc.).
4. Si la perdés o sospechás filtración, rotala desde el panel — la anterior se invalida en el acto.

Precaución

Nunca commitees la API_KEY en repositorios. Usá una API_KEY distinta por entorno (producción / homologación) y rotala periódicamente.

Headers comunes

Header	Tipo	Cuándo
Authorization: Bearer <API_KEY>	obligatorio	Siempre
x-branch-id: <uuid>	opcional	Operar contra una sucursal específica cuando el ApiAccess es global
x-point-id: <uuid>	opcional	Cuando la sucursal tiene 2+ puntos de emisión activos
X-Request-ID: <uuid>	opcional	Si lo enviás se respeta; si no, lo genera el servidor

Sucursales y puntos de emisión

• Si tu ApiAccess está fijado a una sucursal, todas las emisiones se atribuyen a esa sucursal. Enviar x-branch-id con otro valor devuelve 403 API_ACCESS_BRANCH_MISMATCH.
• Si tu ApiAccess es global, podés enviar x-branch-id para apuntar a una sucursal; sin el header se asume la casa central.
• Si la sucursal resuelta tiene 2 o más puntos de emisión activos, x-point-id es obligatorio. Con uno solo, se selecciona automáticamente.

Consejo

Usá GET /v1/echo durante la integración (y en tu health check) para verificar que la credencial es válida y ver qué cuenta, sucursal, punto de emisión y features resuelve con los headers que estás mandando.

Estructura de respuestas

Éxito:

{ "data": {}, "meta": {} }

Error:

{
  "error": { "code": "CODIGO_ESTABLE", "message": "Mensaje legible en español", "details": {} },
  "requestId": "uuid-de-correlación"
}

Usá el campo code (SCREAMING_SNAKE_CASE, estable) para lógica condicional; el message puede cambiar entre versiones. Incluí el requestId en tickets de soporte.

Rate limits

• Cuentas estándar: 60 requests/minuto por ApiAccess.
• Cuentas proveedor: 600 requests/minuto.

Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al excederlo recibís 429 API_RATE_LIMITED con header Retry-After.

El detalle de todos los códigos de error globales está en la Referencia OpenAPI.