Autenticación

Una llave por cuenta, en el encabezado Authorization. No hay OAuth, ni tokens que expiren, ni refresh: una llave vive hasta que la revocas.

Las llaves se crean en el panel, en Cuenta → API, sección Llaves de API, con cualquiera de los dos planes. Empiezan con otk_ y se enseñan una sola vez, al crearlas: guardamos su huella, no la llave.

El esquema es obligatorio

Authorization: Bearer <llave>, con la palabra Bearer y un espacio. Una llave suelta en el encabezado contesta unauthorized aunque sea correcta: aceptarla sería una segunda forma de entrar, sin documentar, que después habría que mantener funcionando.

La llave es de la cuenta, no de una persona

Pertenece al despacho. Quien la creó puede irse y la integración sigue funcionando, que es justo lo que se quiere de una credencial de servidor. En la bitácora las acciones hechas con llave quedan a nombre de la llave.

Una cuenta puede tener varias, y conviene: una por integración, para poder revocar la de un proveedor sin tumbar las demás. Revocar es inmediato y no se deshace.

Qué emisor factura

La llave dice la cuenta; el emisor lo dice cada llamada, con issuer_id. Un despacho con ciento cuarenta contribuyentes usa una sola llave y nombra el emisor en cada factura. Si la cuenta tiene uno solo, puedes omitirlo.

Límites

600 peticiones cada 5 minutos por llave, y 300 cada 5 minutos por dirección IP. Si pasas cualquiera de los dos te contestamos 429 con rate_limited y el encabezado Retry-After, en segundos. Espera ese tiempo antes de volver a llamar.

Con el plan Básico, la API timbra hasta 100 facturas al mes. Cuentan todas las que la cuenta timbró ese mes, también las del panel. La siguiente se contesta con 429, invoice_limit_reached y un Retry-After que llega al día 1 del mes siguiente, hora del centro de México. El plan Pro no tiene ese límite. Leer, cancelar y repetir una llamada con la misma Idempotency-Key siguen funcionando.

Versión y estado

Todas las respuestas de /v1 traen el encabezado X-Oden-Tax-Api-Version: v1.

GET /v1/health no pide llave. Contesta 200 con status, version y time. Sirve para saber si la API está arriba, no si tu llave funciona.

Errores

unauthorized: Falta la llave, no viene con el esquema Bearer, o fue revocada. 401.
payment_required: La cuenta tiene un pago pendiente. 402: no es que no puedas, es que nos debes.
rate_limited: Pasaste el límite de peticiones. 429, con Retry-After en segundos.