Quickstart

Esta guía asume que ya tienes una API key (odt_...) sobre una empresa en ambiente test. Si aún no la tienes, ver Autenticación.

Emite una factura (tipo 01)

Copia, pega tu API key en lugar de odt_xxx, y ejecuta:

curl

curl -X POST https://ocote.io/api/connect/invoice \
  -H "Authorization: Bearer odt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "01",
    "external_ref": "MI-PRIMERA-FACTURA-001",
    "lines": [
      { "description": "Servicio de consultoría", "quantity": 1, "unit_price": 100.00 }
    ]
  }'

Node.js (axios)

import axios from 'axios';

const { data } = await axios.post(
  'https://ocote.io/api/connect/invoice',
  {
    doc_type: '01',
    external_ref: 'MI-PRIMERA-FACTURA-001',
    lines: [
      { description: 'Servicio de consultoría', quantity: 1, unit_price: 100.00 },
    ],
  },
  { headers: { Authorization: `Bearer ${process.env.OCOTE_API_KEY}` } }
);

console.log(data);

Python (requests)

import os, requests

r = requests.post(
    "https://ocote.io/api/connect/invoice",
    headers={"Authorization": f"Bearer {os.environ['OCOTE_API_KEY']}"},
    json={
        "doc_type": "01",
        "external_ref": "MI-PRIMERA-FACTURA-001",
        "lines": [
            {"description": "Servicio de consultoría", "quantity": 1, "unit_price": 100.00},
        ],
    },
)
r.raise_for_status()
print(r.json())

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://ocote.io/api/connect/']);

$response = $client->post('invoice', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('OCOTE_API_KEY')],
    'json' => [
        'doc_type' => '01',
        'external_ref' => 'MI-PRIMERA-FACTURA-001',
        'lines' => [
            ['description' => 'Servicio de consultoría', 'quantity' => 1, 'unit_price' => 100.00],
        ],
    ],
]);

echo $response->getBody();

Respuesta esperada

{
  "success": true,
  "dte_success": true,
  "contingency": false,
  "rejected": false,
  "posted": true,
  "is_duplicate": false,
  "document_id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "external_ref": "MI-PRIMERA-FACTURA-001",
  "control_number": "DTE-01-M001P001-000000000000123",
  "generation_code": "A1B2C3D4-1234-5678-9ABC-DEF012345678",
  "reception_stamp": "20260421154532...",
  "dte_state": "",
  "dte_message": "",
  "observaciones": [],
  "codigo_msg": "",
  "ticket_url": "https://ocote.io/api/connect/file/a1b2c3d4-1234-5678-9abc-def012345678?type=ticket&key=odt_xxx",
  "json_url": "https://ocote.io/api/connect/file/a1b2c3d4-1234-5678-9abc-def012345678?type=json&key=odt_xxx"
}

Lo que acaba de pasar:

1. Ocote creó el documento con el external_ref que mandaste.
2. Asignó el correlativo fiscal control_number.
3. Lo firmó digitalmente y lo mandó al MH.
4. El MH devolvió el reception_stamp (sello de recepción).
5. Se generaron el ticket PDF y el JSON firmado, accesibles por los URLs del response.

Abre el ticket

Pega ticket_url en tu navegador. Obtienes un PDF listo para imprimir en térmica 80 mm o guardar.

Consulta el estado después

Usa tu external_ref (o el document_id) para consultar cualquier documento en cualquier momento:

curl "https://ocote.io/api/connect/status/MI-PRIMERA-FACTURA-001" \
  -H "Authorization: Bearer odt_xxx"

El response trae los mismos flags (success, dte_success, contingency, rejected…), más los montos del DTE y las URLs de archivos.

Qué explorar después

• Documentos > Factura (01) — todos los campos opcionales, cliente, método de pago, envío por correo.
• Documentos > CCF (03) — emitir a contribuyentes IVA con NIT y NRC (incluye retención IVA 1% automática).
• Retry e idempotencia — cómo reintentar con seguridad cuando un llamado falla.
• Respuestas y estados — tabla completa de qué significa cada combinación de flags.