Autenticación

Todas las peticiones al API Connect se autentican con una API key en el header Authorization con esquema Bearer.

Authorization: Bearer odt_f57b5eabebb5ee8698d54c5c9427a991f6254150e819d04b2f56a490

No hay otro esquema de autenticación. No usamos OAuth, no usamos sesiones, no hay rotación automática de tokens. Una API key es de larga duración hasta que tú la desactivas.

Obtener una API key

Las API keys las emite Ocote directamente sobre una empresa configurada en la plataforma. El flujo es:

1. Tú (o tu cliente) ya tiene la empresa registrada en Ocote DTE, con firmador MH cargado y al menos una sucursal/POS activos.
2. Ocote genera la API key desde el panel de administración y te la entrega.
3. La guardas en tu gestor de secretos.

La key se asocia a la empresa y no expira por defecto, pero puede ser desactivada en cualquier momento desde el panel de Ocote (queda registro del evento y todas las peticiones posteriores devuelven 401).

Formato del token

Las API keys siguen el formato:

odt_[56 caracteres hexadecimales]

El prefijo odt_ (Ocote DTE) es fijo y te permite distinguirlas visualmente de otros secretos si las ves en logs o variables de entorno. Una key típica:

odt_f57b5eabebb5ee8698d54c5c9427a991f6254150e819d04b2f56a490

Cómo enviarla

Encabezado estándar en todas las peticiones que consumen/modifican datos:

POST /api/connect/invoice HTTP/1.1
Host: ocote.io
Authorization: Bearer odt_xxx
Content-Type: application/json

Excepción: endpoint de descarga de archivos.

El endpoint GET /file/{id} acepta la key como query param en vez de header, porque muchas veces se usa directamente desde el navegador (abrir un ticket, compartir un link de JSON):

GET /api/connect/file/{document_id}?type=ticket&key=odt_xxx

El resto del API — emisión, consulta, invalidación — usa siempre el header Authorization.

Ejemplos

curl

curl https://ocote.io/api/connect/status/SALE-2026-0042 \
  -H "Authorization: Bearer odt_f57b5eabebb5ee8698d54c5c9427a991f6254150e819d04b2f56a490"

Node.js (axios)

import axios from 'axios';

const ocote = axios.create({
  baseURL: 'https://ocote.io/api/connect',
  headers: {
    'Authorization': `Bearer ${process.env.OCOTE_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const { data } = await ocote.get('/status/SALE-2026-0042');
console.log(data);

Python (requests)

import os, requests

headers = {
    "Authorization": f"Bearer {os.environ['OCOTE_API_KEY']}",
    "Content-Type": "application/json",
}

r = requests.get(
    "https://ocote.io/api/connect/status/SALE-2026-0042",
    headers=headers,
)
r.raise_for_status()
print(r.json())

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://ocote.io/api/connect/',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('OCOTE_API_KEY'),
        'Content-Type'  => 'application/json',
    ],
]);

$response = $client->get('status/SALE-2026-0042');
echo $response->getBody();

Respuestas de error de autenticación

HTTP	Mensaje	Causa
401	API key requerida	Falta el header Authorization o no arranca con Bearer .
401	API key invalida	La key no existe o fue desactivada.
401	Empresa inactiva	La empresa asociada a la key está deshabilitada.

Las respuestas 401 no consumen rate limit. Las respuestas 400/500 tampoco descuentan contra el límite horario pero sí contra el de minuto (ver Rate limits).

Rotación y seguridad

• Trata la key como una contraseña. No la expongas en el frontend, no la commitees a repos, no la mandes por canales no cifrados.
• Si la comprometiste, pide una key nueva a Ocote y desactiva la vieja. Todas las peticiones posteriores con la key vieja devolverán 401. El external_ref sigue siendo tuyo: emisiones que hiciste antes quedan consultables con la key nueva siempre que pertenezcan a la misma empresa.
• Una key por entorno es lo recomendado. Si tienes stage y producción, usa dos keys distintas — típicamente una sobre empresa en ambiente test y otra sobre empresa en ambiente 01.

No embebas la key en el navegador

El API Connect está pensado para consumirse desde un backend. Si necesitas que tu frontend muestre info de DTEs emitidos, el patrón correcto es que tu backend consulte el API con la key y exponga un endpoint propio al frontend.