Verifica credencial y devuelve contexto efectivo

GET

/v1/echo

Producción
Homologación / pruebas

Endpoint de diagnóstico. Usalo durante la integración para verificar:

Que tu API_KEY es válida.
Qué cuenta tiene asociada el ApiAccess.
Si está fijado a una sucursal específica o es global.
Qué sucursal y punto de emisión va a resolver con los headers que estás mandando.
Qué features tiene tu plan activado.

Consejo: dejalo cableado en tu health check para detectar rotación de credenciales o cambios de plan antes de que rompan emisiones productivas.

Autorizaciones

BearerAuth

Respuestas

200

Contexto efectivo del ApiAccess autenticado

nullable

Ejemplos

Credencial válida, ApiAccess fijado a sucursal

{
  "data": {
    "credencial": {
      "id": "7f6e5d4c-3b2a-1098-7654-321fedcba098",
      "nombre": "Integración POS sucursal centro",
      "sucursalIdAsignada": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "ultimoUso": "2026-05-17T13:41:55.000Z"
    },
    "cuenta": {
      "id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
      "rut": "210000000000",
      "razonSocial": "MI EMPRESA S.A.",
      "estado": "active"
    },
    "plan": {
      "apiHabilitada": true,
      "esProveedorFactura": false,
      "limiteUsuarios": 5,
      "limiteCfes": null,
      "limiteSucursales": 3,
      "multiplesPuntosEmision": true
    },
    "sucursal": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "nombre": "Sucursal Centro",
      "codigoDgi": 1
    },
    "puntoEmision": {
      "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "codigoTerminal": "POS-01"
    },
    "horaServidor": "2026-05-17T13:42:00.000Z"
  }
}

401

No autenticado. La API_KEY no fue enviada o no es válida.

Códigos posibles: API_AUTH_HEADER_MISSING, API_AUTH_HEADER_INVALID, API_ACCESS_INVALID.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta header Authorization

{
  "error": {
    "code": "API_AUTH_HEADER_MISSING",
    "message": "Se esperaba la cabecera Authorization con esquema Bearer"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Secret key inválida o revocada

{
  "error": {
    "code": "API_ACCESS_INVALID",
    "message": "Acceso no autorizado"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

403

Acceso prohibido. La credencial es válida pero el plan o el alcance de sucursal lo impiden.

Códigos posibles: API_FEATURE_DISABLED, API_ACCESS_BRANCH_MISMATCH.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

El plan no incluye API

{
  "error": {
    "code": "API_FEATURE_DISABLED",
    "message": "El plan de esta cuenta no tiene habilitado el acceso a la API"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Header x-branch-id distinto al fijo del ApiAccess

{
  "error": {
    "code": "API_ACCESS_BRANCH_MISMATCH",
    "message": "El ApiAccess está fijado a otra sucursal y no coincide con x-branch-id"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

429

Rate limit excedido. Esperá los segundos indicados en el header Retry-After.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Excediste el rate limit

{
  "error": {
    "code": "API_RATE_LIMITED",
    "message": "Se superó el límite de requests para esta API key"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Headers

Retry-After

integer

Ejemplo

Segundos hasta que se libera la ventana de rate limit