Catálogos MH

El API Connect usa dos tipos de catálogos de referencia:

Vivos — expuestos como endpoints, consultables en tiempo real. Úsalos cuando necesites el listado completo o un subconjunto filtrado.
Estáticos — valores enumerados fijos que no cambian. Los envías directo como literales en tus requests.

Catálogos vivos (endpoints)

Actividades económicas

Lista del catálogo CAT-019 del MH — requerido para activity_code en el cliente de CCF y para el activity_code del emisor.


Método	`GET`
URL	`https://ocote.io/api/connect/catalogs/activities`
Query params	`search` (opcional) — filtra por código o descripción. Case- y accent-insensitive: `programacion` encuentra `PROGRAMACIÓN`.
Autenticación	Header `Authorization: Bearer odt_...`

Ejemplo:

curl "https://ocote.io/api/connect/catalogs/activities?search=software" \
  -H "Authorization: Bearer odt_xxx"

[
  { "code": "62010", "description": "Programación informática" },
  { "code": "62020", "description": "Consultoría de informática" },
  { "code": "62090", "description": "Otras actividades de tecnologías de la información y servicios informáticos" }
]

El endpoint devuelve máximo 50 resultados por llamada. Si no envías search, devuelve las primeras 50.

Departamentos y municipios

Lista de CAT-012 (departamentos) y CAT-013 (municipios) agrupados.


Método	`GET`
URL	`https://ocote.io/api/connect/catalogs/departments`
Query params	`search` (opcional) — filtra por nombre de departamento o municipio. Case- y accent-insensitive: `usulutan` encuentra `USULUTÁN`.
Autenticación	Header `Authorization: Bearer odt_...`

curl "https://ocote.io/api/connect/catalogs/departments?search=usulutan" \
  -H "Authorization: Bearer odt_xxx"

Respuesta (abreviada):

[
  {
    "code": "11",
    "name": "USULUTÁN",
    "municipalities": [
      { "code": "1124", "short_code": "24", "name": "USULUTÁN NORTE" },
      { "code": "1125", "short_code": "25", "name": "USULUTÁN ESTE" },
      { "code": "1126", "short_code": "26", "name": "USULUTÁN OESTE" }
    ]
  }
]

Cómo usar estos códigos en los requests

En el payload de cliente o sujeto excluido se envían separados como department + municipality. Para municipality podés usar cualquiera de los dos formatos que expone el catálogo:

Formato largo — el code completo tal cual. Ej: "department": "11", "municipality": "1124".
Formato corto — solo el short_code (los últimos 2 dígitos). Ej: "department": "11", "municipality": "24".

Ambos resuelven al mismo municipio. El formato largo es más cómodo porque podés copiarlo directo del catálogo; el corto se preserva por compatibilidad con integraciones existentes.

Si te interesa una experiencia sin códigos, usá Distritos en vez de este endpoint.

Distritos

Los distritos son la capa más granular dentro de cada municipio (ej. Berlín dentro de Usulután Norte). Son el mismo concepto que ves en el panel de Ocote desktop.

Usar distritos es el flujo recomendado: el integrador busca por nombre, obtiene un UUID, y lo envía en el payload. El API Connect deriva automáticamente el departamento y municipio MH del padre, así que no tenés que manejar códigos.


Método	`GET`
URL	`https://ocote.io/api/connect/catalogs/districts/search`
Query params	`q` (opcional) — nombre del distrito. Case- y accent-insensitive: `berlin` encuentra `Berlín`. `page` (opcional, default `1`) — paginación de 20 por página.
Autenticación	Header `Authorization: Bearer odt_...`

curl "https://ocote.io/api/connect/catalogs/districts/search?q=berlin" \
  -H "Authorization: Bearer odt_xxx"

Respuesta:

{
  "results": [
    {
      "id": "155",
      "text": "Distrito de Berlín - USULUTÁN NORTE, USULUTÁN",
      "name": "Distrito de Berlín",
      "municipality": "USULUTÁN NORTE",
      "department": "USULUTÁN"
    }
  ],
  "pagination": { "more": false }
}

Luego en el payload de /invoice o /suex:

{
  "customer": {
    "name": "Cliente en Berlín",
    "district": "155",
    "address": "Berlín, Usulután"
  }
}

Cuando envías district, los campos department y municipality se ignoran (aunque vengan en el payload). Ver Factura (01) para la tabla completa de campos.

Unidades de medida

Lista del catálogo CAT-014 del MH.


Método	`GET`
URL	`https://ocote.io/api/connect/catalogs/units`
Query params	`search` (opcional) — filtra por código o descripción. Case- y accent-insensitive.
Autenticación	Header `Authorization: Bearer odt_...`

curl https://ocote.io/api/connect/catalogs/units \
  -H "Authorization: Bearer odt_xxx"

Las unidades son informativas. El API Connect usa 99 (Otra) por defecto para todas las líneas emitidas, ya que los wildcard items no requieren unidad específica. El listado está expuesto por completitud.

Catálogos estáticos

Tipos de contribuyente

Usado en customer.type_contributor en los requests de Factura, CCF y Exportación.

Valor	Tipo
`1`	Pequeño Contribuyente
`2`	Mediano Contribuyente
`3`	Gran Contribuyente — aplica retención IVA 1% automática si base ≥ $100
`4`	Gobierno — aplica retención IVA 1% automática si base ≥ $100

Ver Wildcard items > Retención IVA.

Tipos de documento identificador (receptor/sujeto)

Usado en customer.document_type y subject.document_type.

Código	Documento
`"02"`	Carnet de Residente
`"03"`	Pasaporte
`"13"`	DUI (Documento Único de Identidad)
`"36"`	NIT
`"37"`	Otro — default cuando el consumidor no envía `document_type` al crear un cliente nuevo vía `/invoice`

SUEX acepta solamente estos 5 valores (el API valida explícitamente). Factura/CCF/Exportación permite estos y otros códigos MH, pero la mayoría de integraciones usan 13 (personas naturales con DUI) o 36 (empresas con NIT). Si mandas un cliente sin especificar document_type, el API usa 37 ("Otro") para evitar rechazos del MH por mismatch entre tipo declarado y formato del número.

Formas de pago

Usado en payment_method. Catálogo CAT-017 del MH.

Código	Forma de pago
`"01"`	Billetes y monedas (Efectivo) — default
`"02"`	Tarjeta Débito
`"03"`	Tarjeta Crédito
`"04"`	Cheque
`"05"`	Transferencia / Depósito Bancario
`"08"`	Dinero electrónico
`"09"`	Monedero electrónico
`"10"`	Transferencia no bancaria
`"11"`	Remesa
`"12"`	Permuta
`"13"`	Otros medios no mencionados
`"14"`	Cuentas por pagar
`"15"`	Giro bancario
`"99"`	Otros

Condiciones de operación

Usado en transaction_condition. Catálogo CAT-016.

Valor	Condición
`1`	Contado — default
`2`	Crédito
`3`	Otro

Cuando transaction_condition: 2, los campos deadline y period toman relevancia para indicar el plazo del crédito. deadline es la unidad (catálogo CAT-018) y period es la cantidad.

`deadline`	Unidad
`1`	Días
`2`	Meses
`3`	Años

Ejemplo: crédito a 30 días → "deadline": 1, "period": 30. Crédito a 2 meses → "deadline": 2, "period": 2.

Ambientes

Usado en el DTE firmado (campo identificacion.ambiente). No se envía en el payload — se deriva de la configuración de tu empresa.

Código	Ambiente
`"00"`	Test / Pruebas
`"01"`	Producción

Ver Ambiente y URL base para cómo se configura.

Tipos de documento DTE

Código	Documento	Endpoint
`"01"`	Factura	`POST /invoice` con `doc_type: "01"`
`"03"`	Comprobante de Crédito Fiscal (CCF)	`POST /invoice` con `doc_type: "03"`
`"05"`	Nota de Crédito	`POST /credit-memo`
`"11"`	Factura de Exportación	`POST /invoice` con `doc_type: "11"`
`"14"`	Sujeto Excluido	`POST /suex`

El API Connect actual no expone los tipos 04 (Nota de Remisión), 06 (Nota de Débito), 07 (Comprobante de Retención), 08 (Comprobante de Liquidación), 09 (Contable de Liquidación), 15 (Comprobante de Donación). Si tu integración los requiere, consulta con Ocote.

Ver también

Convenciones — uso general de valores enumerados.
Factura (01) — request schema con los campos que usan estos catálogos.
CCF (03) — receptor con type_contributor que activa retención.
Sujeto Excluido (14) — tipos de documento aceptados.

Catálogos vivos (endpoints)​

Actividades económicas​

Departamentos y municipios​

Distritos​

Unidades de medida​

Catálogos estáticos​

Tipos de contribuyente​

Tipos de documento identificador (receptor/sujeto)​

Formas de pago​

Condiciones de operación​

Ambientes​

Tipos de documento DTE​

Ver también​