Quickstart

Emite tu primer comprobante electrónico en menos de cinco minutos. Necesitas una cuenta y una API key; el resto es una sola llamada HTTP.

Requisitos

Una cuenta de Emitoo (crea una gratis en app.emitoo.io/registro).
Una API key con el prefijo fpk_….
Un RUC o cédula de cliente válido (Ecuador).

1. Crea una API key

Entra al panel, ve a API Keys y genera una nueva con permiso de escritura sobre facturas. Se mostrará una sola vez: guárdala en un secret manager.

Trata tu API key como una contraseña

Cualquiera con la key puede emitir comprobantes a nombre de tu organización. No la commitees al repo ni la envíes al frontend.

2. Emite tu primera factura

Con la key en mano, haz un POST a /api/v1/facturas. La respuesta llega en milisegundos con la factura en estado PENDIENTE; el envío al ente tributario corre en background.

import { Emitoo } from "emitoo";

const client = new Emitoo(); // lee la API key de EMITOO_API_KEY

const factura = await client.facturas.crear({
  tipo_identificacion: "04", // 04 = RUC, 05 = cédula
  identificacion: "0991234567001",
  razon_social: "ACME S.A.",
  email: "facturacion@acme.example",
  detalles: [
    { codigo_principal: "LIC-1", descripcion: "Licencia mensual",
      cantidad: 1, precio_unitario: 75.0, tarifa_iva: 15 },
  ],
});

console.log(factura.id, factura.estado);
// => 177 "PENDIENTE"  (llega a "AUTORIZADO" en segundos)

from emitoo import EmitooClient

client = EmitooClient()  # lee la API key de EMITOO_API_KEY

factura = client.facturas.crear({
    "tipo_identificacion": "04",  # 04 = RUC, 05 = cédula
    "identificacion": "0991234567001",
    "razon_social": "ACME S.A.",
    "email": "facturacion@acme.example",
    "detalles": [
        {"codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
         "cantidad": 1, "precio_unitario": 75.0, "tarifa_iva": 15},
    ],
})

print(factura["id"], factura["estado"])
# => 177 "PENDIENTE"

client, err := emitoo.New("") // lee la API key de EMITOO_API_KEY
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

factura, err := client.Facturas.Crear(ctx, emitoo.M{
	"tipo_identificacion": "04", // 04 = RUC, 05 = cédula
	"identificacion":      "0991234567001",
	"razon_social":        "ACME S.A.",
	"email":               "facturacion@acme.example",
	"detalles": []emitoo.M{
		{"codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
			"cantidad": 1, "precio_unitario": 75.0, "tarifa_iva": 15},
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(factura["id"], factura["estado"])
// => 177 PENDIENTE

curl -X POST https://api.emitoo.io/api/v1/facturas \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_identificacion": "04",
    "identificacion": "0991234567001",
    "razon_social": "ACME S.A.",
    "email": "facturacion@acme.example",
    "detalles": [
      { "codigo_principal": "LIC-1", "descripcion": "Licencia mensual",
        "cantidad": 1, "precio_unitario": 75.00, "tarifa_iva": 15 }
    ]
  }'

3. Espera el resultado

Tienes dos formas de enterarte cuando el comprobante es autorizado:

Webhook — suscribe un endpoint a factura.autorizada y te avisamos en cuanto llegue.
Polling — consulta GET /api/v1/facturas/{id}/status hasta ver AUTORIZADO.

// El SDK hace el polling por ti: espera hasta un estado final
// (lanza TimeoutError si se agota el tiempo).
const autorizada = await client.facturas.esperarAutorizacion(factura.id, {
  timeoutMs: 60_000,
});
console.log(autorizada.estado); // "AUTORIZADO"

# El SDK hace el polling por ti: espera hasta un estado final
# (lanza TimeoutError si se agota el tiempo).
factura = client.facturas.esperar_autorizacion(factura["id"], timeout=60.0)
print(factura["estado"])  # "AUTORIZADO"

// El SDK hace el polling por ti: espera hasta un estado final
// (retorna un error que envuelve emitoo.ErrTimeout si se agota).
id := int(factura["id"].(float64))
autorizada, err := client.Facturas.EsperarAutorizacion(ctx, id, 60*time.Second, 2*time.Second)
if err != nil {
	log.Fatal(err)
}
fmt.Println(autorizada["estado"]) // AUTORIZADO

curl https://api.emitoo.io/api/v1/facturas/177/status \
  -H "X-API-Key: $EMITOO_API_KEY"

Siguientes pasos

Lee la guía de autenticación para entender roles, scopes y rotación de keys.
Configura webhooks firmados para enterarte de los eventos sin polling.
Revisa la tabla de errores para manejar casos borde en producción.