Guía de integración

Claves y permisos

Cada sistema usa su propia clave de API, en la cabecera X-API-Key o en Authorization: Bearer. La crea un administrador de la cuenta en el portal, en «Claves de API», y se muestra una sola vez. Al crearla, se le asignan solo los permisos que necesita:

Una tienda que emite y después descarga el PDF necesita emit y read. Ninguna clave puede crear usuarios ni otras claves, ni subir el certificado de firma. Eso lo hace un administrador desde el portal, para que una clave expuesta no permita tomar el control de la cuenta.

Primero, el sandbox

Una clave de prueba (cfe_test_…) emite en el sandbox de su cuenta, con la misma API y el mismo pedido que una clave real. El sandbox tiene numeración propia (serie SB), firma con un certificado de prueba y no cuenta para el consumo. Nada llega a la DGI: cada comprobante recibe una respuesta de prueba con los estados y los códigos de la DGI, y pasa por los mismos pasos que en producción. El PDF y el ticket dicen «SIN VALOR FISCAL — AMBIENTE DE PRUEBAS: no se envió a la DGI», y cada comprobante, evento y webhook incluye "sandbox": true.

La cabecera Cfe-Sandbox-Outcome (o la configuración de la clave, al crearla) elige la respuesta de prueba. Sin ninguna de las dos, es accepted:

curl -X POST https://api.okcfe.tinylab.com.uy/v1/invoices \
  -H "x-api-key: $CLAVE_DE_PRUEBA" -H "content-type: application/json" \
  -H "idempotency-key: invoice:shopify:mi-tienda:5012345" \
  -H "cfe-sandbox-outcome: acceptedrejected:E04delay:30timeout" -d @pedido.json

Lo que incluye el sandbox

Claves

Hasta 10 claves de prueba activas, además de las de su membresía

Por mes

10.000 comprobantes de prueba

Guardados

Hasta 100.000; al llegar a ese número, la API responde 409 sandbox_full (el sandbox está lleno) hasta que se vacía

Limpieza

Se vacía solo después de 30 días sin emitir. También puede vaciarlo desde el portal en cualquier momento: las claves se mantienen y la numeración vuelve a 1

Para pasar a producción, en su código solo se cambia la clave de prueba por la real. Además, la cuenta debe tener cargados su certificado de firma y su CAE: lo indica el control de la sección siguiente.

¿Puede emitir?

Con la clave real, GET /v1/tenant/readiness indica si la cuenta puede emitir (can_emit) y qué falta. Cada control trae un código estable, para mostrarlo en la pantalla de su conector. Una cuenta nueva sin CAE responde can_emit: false; cuando se carga, pasa a true. Los códigos más frecuentes:

Emitir

Un e-Ticket (tipo 101) con su envío, a partir de un pedido de una tienda con precios con IVA incluido:

curl -X POST https://api.okcfe.tinylab.com.uy/v1/invoices \
  -H "x-api-key: $CLAVE" \
  -H "idempotency-key: invoice:shopify:mi-tienda:5012345" \
  -H "content-type: application/json" \
  -d '{
    "cfe_type": 101,
    "external_id": "#1001",
    "gross_amounts": 1,
    "lines": [
      { "description": "Remera de algodón", "quantity": "2",
        "unit_price": "1220.00", "vat_rate": "22" },
      { "description": "Envío a domicilio", "quantity": "1",
        "unit_price": "244.00", "vat_rate": "22",
        "codes": [{ "type": "INT1", "code": "ENVIO" }] }
    ]
  }'

import { CfeClient, IdempotencyKey } from '@cfe/sdk'

const cfe = new CfeClient({
  baseUrl: 'https://api.okcfe.tinylab.com.uy',
  apiKey: process.env.CFE_API_KEY!,
})

const cfeDelPedido = await cfe.emit(
  {
    cfe_type: 101,
    external_id: '#1001',
    gross_amounts: 1,
    lines: [
      { description: 'Remera de algodón', quantity: '2',
        unit_price: '1220.00', vat_rate: '22' },
      { description: 'Envío a domicilio', quantity: '1',
        unit_price: '244.00', vat_rate: '22',
        codes: [{ type: 'INT1', code: 'ENVIO' }] },
    ],
  },
  { idempotencyKey: IdempotencyKey.forInvoice('shopify', 'mi-tienda', 5012345) },
)

use Cfe\Sdk\Client;
use Cfe\Sdk\IdempotencyKey;
use Symfony\Component\HttpClient\Psr18Client;

$cfe = new Client('https://api.okcfe.tinylab.com.uy', getenv('CFE_API_KEY'), new Psr18Client());

$cfeDelPedido = $cfe->emit([
    'cfe_type' => 101,
    'external_id' => '#1001',
    'gross_amounts' => 1,
    'lines' => [
        ['description' => 'Remera de algodón', 'quantity' => '2',
         'unit_price' => '1220.00', 'vat_rate' => '22'],
        ['description' => 'Envío a domicilio', 'quantity' => '1',
         'unit_price' => '244.00', 'vat_rate' => '22',
         'codes' => [['type' => 'INT1', 'code' => 'ENVIO']]],
    ],
], IdempotencyKey::forInvoice('shopify', 'mi-tienda', 5012345));

import uy.cfe.sdk.CfeClient;
import uy.cfe.sdk.IdempotencyKey;

CfeClient cfe = CfeClient.create("https://api.okcfe.tinylab.com.uy", System.getenv("CFE_API_KEY"));

JsonNode cfeDelPedido = cfe.emit(Map.of(
    "cfe_type", 101,
    "external_id", "#1001",
    "gross_amounts", 1,
    "lines", List.of(
        Map.of("description", "Remera de algodón", "quantity", "2",
               "unit_price", "1220.00", "vat_rate", "22"),
        Map.of("description", "Envío a domicilio", "quantity", "1",
               "unit_price", "244.00", "vat_rate", "22",
               "codes", List.of(Map.of("type", "INT1", "code", "ENVIO"))))),
    IdempotencyKey.forInvoice("shopify", "mi-tienda", 5012345));

using Cfe.Sdk;

using var cfe = new CfeClient("https://api.okcfe.tinylab.com.uy", Environment.GetEnvironmentVariable("CFE_API_KEY")!);

JsonNode cfeDelPedido = await cfe.EmitAsync(new
{
    CfeType = 101,
    ExternalId = "#1001",
    GrossAmounts = 1,
    Lines = new object[]
    {
        new { Description = "Remera de algodón", Quantity = "2",
              UnitPrice = "1220.00", VatRate = "22" },
        new { Description = "Envío a domicilio", Quantity = "1",
              UnitPrice = "244.00", VatRate = "22",
              Codes = new[] { new { Type = "INT1", Code = "ENVIO" } } },
    },
}, IdempotencyKey.ForInvoice("shopify", "mi-tienda", 5012345));

• Responde 201 Created (el comprobante se creó) con el comprobante numerado, firmado y en PENDING (pendiente de la respuesta de la DGI). okCFE lo envía a la DGI sin intervención.
• La Idempotency-Key se arma con el pedido: si la solicitud se repite por un corte o un tiempo de espera agotado, la API devuelve el mismo comprobante. Con la misma clave y otro cuerpo, responde 409 idempotency_key_reused (esa clave ya se usó con otros datos).
• external_id es el número de pedido que ve el cliente, único por cuenta. Un segundo comprobante con el mismo número recibe 409 external_id_taken (ese pedido ya tiene comprobante), con el id del existente. Se busca con GET /v1/invoices?external_id=%231001.
• vat_rate en lugar del indicador de facturación: la tasa que su tienda ya calculó (22, 10 o 0). okCFE la traduce al indicador de la DGI (3: tasa básica, 2: tasa mínima, 1: exento).
• El envío es una línea más, con el código interno INT1 ENVIO: así una devolución lo identifica sola.
• Antes de emitir, POST /v1/invoices/preview con el mismo cuerpo devuelve los totales y todos los errores juntos, cada uno con su ruta (lines[1].vat_rate), sin usar un número.

Una solicitud que la API rechaza nunca usa un número de comprobante.

De qué campo de su tienda sale cada dato

Los datos mínimos de un pedido de Shopify, Magento 2 o WooCommerce. Los conectores para instalar todavía no están disponibles: esto es lo que hace su desarrollador con la API o un SDK.

Órdenes: validar antes de cobrar

Cuando la tienda cobra antes de facturar, una orden valida la factura entera al confirmar el carrito y la emite cuando el pago se confirma. Crear una orden no usa un número de la numeración ni cuenta en el consumo del mes.

1. Al confirmar el carrito, POST /v1/orders con el mismo cuerpo que POST /v1/invoices. Responde los totales calculados, el número de la orden (ORD-0000000012) y su version, o el 422 con cada error, antes de cobrar.
2. Si el carrito cambia, PUT /v1/orders/{id} con el pedido completo (lo que no viene deja de estar) e If-Match con la versión leída. La versión sube.
3. El cobro usa totals.payable y el número ORD-… como referencia del pago.
4. Al confirmarse el pago, POST /v1/orders/{id}/execute con la version cobrada: se emite la factura y se envía a la DGI. Repetirlo devuelve la misma factura; otra versión responde 409 order_version_mismatch (la orden cambió) y no emite.

curl -X POST https://api.okcfe.tinylab.com.uy/v1/orders -H "x-api-key: $CLAVE" -d @pedido.json
# 201: { "id": "0192…", "number": "ORD-0000000057", "state": "OPEN", "version": 1, "totals": { "payable": "1220.00", … } }
curl -X POST https://api.okcfe.tinylab.com.uy/v1/orders/0192…/execute -H "x-api-key: $CLAVE" \
  -d '{"version": 1, "paid_amount": "1220.00", "payment_reference": "MP-88123"}'
# 201: { "order": { "state": "EXECUTED", "invoice_id": "…" }, "invoice": { "series": "A", … } }

Si la facturación falla por algo que cambió desde que se creó la orden (el cupo del mes, la numeración, el certificado), la orden sigue abierta con el problema en last_error: resuelva la causa y facture de nuevo con la misma versión. La factura y la orden quedan unidas: la factura trae order_id y order_number, y el evento order.executed avisa cada factura de una orden. POST /v1/orders/{id}/duplicate crea una orden nueva con el pedido de otra, para facturar de nuevo una vencida o cancelada.

Estados y respuestas de la DGI

El campo status de un comprobante tiene uno de estos valores:

La DGI responde con estos códigos de estado, que aparecen en los envíos (GET /v1/submissions/{id}) y en el portal:

Un rechazo trae cada motivo en rejection_causes, con su code, el texto oficial de la DGI (gloss) y el detalle que haya agregado la DGI (detail, o null). Los motivos que más se ven:

Los motivos de rechazo de un envío empiezan con S (por ejemplo, S03: el certificado de firma no es válido) y las observaciones de un comprobante de contingencia, con C. La lista completa, con el texto de la DGI, está en GET /v1/catalog/codes (rejection_causes y dgi_states).

Errores

Todos los errores llegan como application/problem+json, con un code estable, un detail en el idioma de Accept-Language y el field. Un comprobante con datos que no validan trae todos sus errores juntos en errors, cada uno con la ruta del JSON enviado:

{
  "status": 422, "code": "invalid_cfe", "field": "NomItem", "detail": "…",
  "errors": [
    { "path": "lines[0].description", "code": "length", "field": "NomItem",
      "detail": "…", "params": { "min": 1, "max": 80, "got": 81 } },
    { "path": "recipient.number", "code": "invalid_ruc", "field": "DocRecep",
      "detail": "…", "params": {} }
  ]
}

En el ejemplo, length indica que la descripción supera los 80 caracteres e invalid_ruc, que el RUC del receptor no es válido. Con path se marca el campo del formulario; con code y params se escribe un mensaje propio. Los errores más frecuentes:

Cada code que puede devolver cada ruta está en el contrato OpenAPI.

Webhooks y eventos

La respuesta de la DGI llega después del 201. Hay dos formas de recibirla, y se recomienda usar las dos:

• Webhooks (POST /v1/webhooks): avisos automáticos a su sistema, que llegan en el momento. Puede tener varias direcciones de destino, cada una con su secreto y los eventos que elija (o todos); GET /v1/webhooks/events explica cada evento y POST /v1/webhooks/{id}/test envía uno de prueba. Van firmados en x-cfe-signature: sha256=… (HMAC-SHA256 del cuerpo, con el secreto de ese destino) y se reintentan; si un destino falla, los demás siguen recibiendo. Pueden llegar más de una vez: descarte los repetidos por event_id.
• El feed (GET /v1/events?since=): los mismos eventos, que su sistema consulta con un cursor. Después de una interrupción, consulte desde el último cursor para recibir, en orden, todo lo que el webhook no pudo entregar.

El cuerpo de cada webhook es {"id", "event", "payload", "event_id", "sandbox"}; event_id es el id del mismo evento en el feed, y sandbox indica si viene del ambiente de pruebas. Hay veinte eventos, y cada destino elige los suyos:

Un destino con "events": ["*"] recibe todos, también los que se agreguen más adelante. GET /v1/webhooks/{id}/deliveries muestra cada entrega con lo que respondió su sistema, y PATCH /v1/webhooks/{id} con "enabled": false lo pone en pausa: lo pendiente espera hasta que se reanude.

Las personas del equipo pueden recibir avisos por correo, WhatsApp, Telegram, Slack o Teams (/v1/notifications): un certificado por vencer, pocos números de CAE, un rechazo de la DGI. Cada destino se confirma antes de recibir nada, con un código o, en Telegram, con un enlace que se abre desde el chat; los avisos se configuran desde el portal o por la API.

Verifique la firma con el cuerpo tal como llegó, antes de interpretarlo:

import { verifyWebhook } from '@cfe/sdk'

// cuerpo: el texto tal como llegó, sin interpretar
const evento = await verifyWebhook(cuerpo, request.headers['x-cfe-signature'], [secretoNuevo, secretoViejo])

use Cfe\Sdk\Webhook;

$cuerpo = file_get_contents('php://input'); // tal como llegó
$evento = Webhook::verify($cuerpo, $_SERVER['HTTP_X_CFE_SIGNATURE'] ?? null, [$secretoNuevo, $secretoViejo]);
http_response_code(204);

import uy.cfe.sdk.Webhook;
import uy.cfe.sdk.WebhookEvent;

// cuerpo: los bytes tal como llegaron, sin interpretar
WebhookEvent evento = Webhook.verify(cuerpo, request.getHeader("x-cfe-signature"), secretoNuevo, secretoViejo);

using Cfe.Sdk;

// cuerpo: los bytes tal como llegaron, sin interpretar
WebhookEvent evento = Webhook.Verify(cuerpo, Request.Headers["x-cfe-signature"], secretoNuevo, secretoViejo);

Mientras cambia el secreto, pase los dos: cualquiera de ellos es válido. La URL del webhook debe ser pública y usar https.

curl "https://api.okcfe.tinylab.com.uy/v1/events?since=$CURSOR&limit=100" -H "x-api-key: $CLAVE"
# { "events": [ { "id": 8812, "event": "invoice.processed", "payload": { … } } ],
#   "next_cursor": "ZTE6…", "has_more": false, "retention_days": 30 }

Al recibir invoice.processed, GET /v1/invoices/{id} indica el resultado: ACCEPTED (el pedido queda facturado) o REJECTED, con cada motivo en rejection_causes. Si la DGI rechazó con un motivo que conserva el número (E02 o E09), POST /v1/invoices/{id}/reissue vuelve a emitirlo.

Devoluciones

Cada devolución de la tienda es un POST /v1/invoices/{id}/refund con su identificador en refund_id: el creditmemo de Magento, el refund de Shopify o el reembolso de WooCommerce. okCFE emite la nota de crédito; su sistema solo indica qué se devolvió.

• Repetir es seguro: el mismo refund_id con el mismo cuerpo devuelve la misma nota de crédito.
• No se devuelve de más, ni por línea, ni por tasa, ni en total. Lo que excede responde 422 refund_exceeds_remaining (el importe supera lo que queda por devolver), con el saldo.
• GET /v1/invoices/{id}/refunds indica lo que queda por devolver de cada línea.

PDF y ticket POS

• pdf_url es un enlace fijo al PDF, sin credenciales, para el correo de confirmación al cliente. Si el enlace se expuso, POST /v1/invoices/{id}/pdf-link genera uno nuevo y el anterior deja de funcionar.
• El ticket POS, GET /v1/invoices/{id}/pos, para impresoras térmicas de 80 y 57 mm. El parámetro encoding elige el formato: json, los bloques para dibujar el ticket en pantalla (cfe-pos/1, con su JSON Schema público); escpos, los datos listos para una impresora compatible con ESC/POS; text, texto plano. columns elige el ancho: 48 caracteres por renglón (80 mm) o 32 (57 mm).

curl -o ticket.bin "https://api.okcfe.tinylab.com.uy/v1/invoices/$ID/pos?encoding=escpos&columns=48" \
  -H "x-api-key: $CLAVE"

Límites

Las respuestas incluyen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 429 rate_limited (demasiadas solicitudes) incluye Retry-After: espere ese tiempo y vuelva a intentarlo; los SDK lo hacen solos. GET /v1/usage indica el consumo del mes y los límites de la membresía, y llegan avisos por webhook al 80 % y al 100 %.

SDK

Cuatro clientes generados a partir del contrato de la API, con los mismos nombres y el mismo comportamiento. Incluyen un método por operación, reintentos que respetan Retry-After, la Idempotency-Key derivada del pedido, errores con su ruta (error.at('lines[0].quantity')), la verificación de la firma del webhook y un iterador del feed que guarda el cursor.

Cada SDK incluye los mismos ejemplos completos: un pedido (de Shopify en TypeScript, de WooCommerce en PHP y de un sistema de gestión en Java y C#) hasta el comprobante, la devolución, el PDF y el ticket; el mismo pedido con una orden, desde el carrito hasta la factura al confirmarse el pago; la instalación, que deja su webhook con los eventos que usa y lo prueba; y un recorrido de prueba con los mismos pasos en los cuatro, que se corre contra el sandbox con una clave de prueba.

Disponibles a pedido: se entregan junto con la clave de prueba (todavía no están publicados en npm, Packagist, Maven Central ni NuGet).

Tipos de comprobante

El campo cfe_type lleva el código de la DGI de cada tipo. okCFE emite los 42:

El contrato completo

Cada ruta, con sus campos y sus errores, está en el contrato OpenAPI, público y sin credenciales: api.okcfe.uy/v1/openapi.json. El catálogo (GET /v1/catalog/cfe-types) indica, para cada uno de los 42 tipos de CFE, qué campos lleva, cuáles son opcionales y cuáles completa okCFE con los datos de su cuenta.

Solicitar una clave de prueba