Skip to navigation
Empezar

Onboarding del tenant

Deja una empresa lista para emitir en PILOTO en 7 pasos. Los pasos encadenan IDs (company → branch → POS → setup). Todas las rutas valen con y sin /v1 (usa /v1).

En esta página aprenderás: dejar una empresa lista para emitir en 7 pasos · Prerrequisitos: API corriendo + BACKEND_SECRET (operador) · Tiempo: ~20 min.

1

Empresa (operador)

Solo nit + business_name son obligatorios. La api_key solo se muestra una vez: guárdala como secreto. NIT duplicado → 409.

CampoTipoObligatorioDescripción
nitstringSíSin guiones ni dígito verificador extra
business_namestringSíRazón social
ambienteenumNo, default PILOTOPILOTO o PRODUCCION (beta: siempre PILOTO)
modalidadintNo, default 11 electrónica, 2 computarizada
municipio, direccion, telefonostringNoDatos de la empresa
codigo_actividadstringNoSe hereda a los ítems que lo omitan
token_delegadostringNoToken SIAT (vía PATCH /companies/{id})
certificate_webhook_urlstringNohttp(s):// para alertas de vencimiento
invoice_email_enabledboolNo, default falseEmail de factura (función cloud)
// Operador: autentica con BACKEND_SECRET, no con apiKey
const op = new Supay({
  baseUrl,
  backendToken: process.env.BACKEND_SECRET!,
});
const { company, api_key } = await op.bootstrap.createCompany({
  nit: "123456789",
  business_name: "Mi Empresa SRL",
  ambiente: "PILOTO",
  modalidad: 1,
  codigo_actividad: "620900",
});
// A partir de aquí todo usa la key del tenant
const supay = new Supay({ apiKey: api_key!, baseUrl });

Alternativa humana: signup → login → POST /auth/companies (quedas owner), luego POST /companies/{id}/api-keys. Detalle en Autenticación.

2

Sucursal

CampoTipoObligatorioDescripción
company_iduuidSíDebe ser tu tenant
namestringSíEj. “Casa Matriz”
codigo_sucursalintNo, default 00 = casa matriz
addressstringNoDirección
const branch = await supay.branches.create({
  company_id: company.id,
  codigo_sucursal: 0,
  name: "Casa Matriz",
  address: "Av. 123",
});

Actualizar sucursal es PUT /branches/{id} (no PATCH). Listar: GET /branches/?company_id=<id>.

3

Punto de venta

CampoTipoObligatorioDescripción
branch_iduuidSíSucursal del paso 2
namestringSíEj. “Caja 1”
descriptionstringSíEj. “Punto principal”
tipo_punto_ventaintNo, default 2Tipo SIAT del POS

codigo_punto_venta se asigna solo; company_id/codigo_sucursal se heredan. Actualizar es PATCH (no PUT).

const pos = await supay.pointOfSales.create({
  branch_id: branch.id,
  name: "Caja 1",
  description: "Punto principal",
  tipo_punto_venta: 2,
});
4

Certificado P12

multipart/form-data, límite 5 MB, solo .p12/.pfx.

Campo (form)TipoObligatorioDescripción
p12_filebinarioSíArchivo P12/PFX
p12_passwordstringNoClave del P12
name / typestringNoDefault cert-<id>-<fecha> / P12
// Sube el P12 que firma ante el SIAT
await supay.certificates.upload({
  id: company.id,
  p12_file: new File([p12Bytes], "cert.p12"), // Blob/Buffer según runtime
  p12_password: "***",
  name: "cert-principal",
});
// Verifica el activo y su vigencia
const activo = await supay.certificates.getActive({ id: company.id });
// not_after: alertas a 30/15/7 días + marca EXPIRED automática
5

Setup SIAT (CUIS + CUFD)

Idempotente: ejecútalo tras crear el POS y cada vez que dudes del estado. Granular: POST /siat/cuis/{pos} y /siat/cufd/{pos} con {} (CUFD requiere CUIS).

// Deja CUIS + CUFD vigentes de una vez
const setup = await supay.siat.setup({ point_of_sale_id: pos.id });
// setup.readiness
6

Sincronizar catálogos

Sin ?operation sincroniza todo; con ?operation=tipoMoneda solo esa. Operación desconocida → 400.

const sync = await supay.siat.syncCatalogs({ pointOfSaleId: pos.id });
// sync.operations[].codigos, sync.readiness.ready
7

Verificar readiness e insumos

// Todo listo cuando ready === true y missing vacío
const ready = await supay.catalogs.getReadiness({
  id: company.id,
  point_of_sale_id: pos.id,
});
// Insumos para armar tu primer payload
const boot = await supay.catalogs.getEmisionBootstrap({
  id: company.id,
  codigo_actividad: "620900",
});
const prods = await supay.catalogs.listProductosSin({
  id: company.id,
  q: "tornillo",
});
// elige codigo_producto_sin + unidad_medida para tu payload

Operaciones secundarias

// Sucursales
const sucursales = await supay.branches.list({ company_id: company.id });
await supay.branches.update({ id: branch.id, name: "Sucursal Norte" });
await supay.branches.delete({ id: branch.id });
// Puntos de venta
const punto = await supay.pointOfSales.get({ id: pos.id });
await supay.pointOfSales.update({ id: pos.id, description: "Caja 2" });
// Solo lectura
const certs = await supay.certificates.list({ id: company.id });
const keys = await supay.apiKeys.list({ id: company.id });

Siguiente: Emitir factura · Sectores.