Empresa, preparación y numeración

Perfil

• GET /v1/company devuelve el perfil, status y ETag.
• PATCH /v1/company reemplaza el perfil (CompanyUpdate) con If-Match e idempotencia. La identificación fiscal no cambia.
  • Falla con COMPANY_HAS_PENDING_DOCUMENTS si el cambio invalidaría trabajo pendiente o incierto.
  • Conserva las versiones anteriores. Un cambio invalida la marca de identidad verificada y obliga a revisar los requisitos de firma afectados.

Preparación (readiness)

GET /v1/company/readiness explica los requisitos actuales sin modificar nada:

{
  "company_id": "…",
  "environment": "simulation",
  "status": "ready",
  "checks": [
    { "name": "numbering", "status": "verified", "source": "system", "message": "…" }
  ],
  "as_of": "…"
}

• status: configuring, testing, ready, restricted o closed.
• Cada check (identity, signing_authorization, certificate, software, qualification, numbering, delivery, commercial) tiene status (pending, verified, invalid, expired, not_applicable) y source (declared, verified, system).
• ready es disponibilidad administrativa. Cada admisión vuelve a comprobar firma, configuración y rango.

GET /v1/capabilities indica qué funciones puede usar tu clave, combinando empresa, ambiente, actor y permisos. Un perfil habilitado no sustituye las precondiciones de admisión.

Estado del servicio

GET /v1/status (permiso company:read) muestra la observación más reciente del ambiente, los incidentes activos y las acciones sugeridas. Si la observación falta o está vencida, devuelve unknown. No sustituye la consulta del resultado de cada documento.

Rangos de numeración

• POST /v1/numbering-ranges registra rangos authorized_invoice (simulación y habilitación) y note_sequence (habilitación).
  • Prefijos de 1 a 4 caracteres; consecutivos hasta 999999999.
  • Los rangos de factura de habilitación requieren resolución y fechas. Se declaran, no se verifican contra la DIAN.
  • Este endpoint no recibe claves técnicas: usa configuración XML de habilitación.
• Los rangos de factura disjuntos pueden continuar un prefijo sin reutilizar consecutivos. Se rechazan solapamientos. Las secuencias de notas conservan prefijos exclusivos.
• GET /v1/numbering-ranges/{id} devuelve metadatos y ETag.
• Activación y desactivación usan { "reason": "…" }, If-Match e idempotencia. No se suspende un rango con trabajo pendiente ni se reactiva uno vencido o agotado.

Consumo del rango

• Cada admisión consume capacidad, contando las solicitudes pendientes sin número.
• Con NUMBERING_EXHAUSTED no se crea documento, trabajo ni consumo.
• Un replay idempotente recupera la admisión anterior aunque el rango ya se haya agotado.
• Cancelar antes de numerar libera capacidad. Un número asignado no se recicla.

Sedes, contingencia y transición automática de rangos están fuera del alcance actual.

En habilitación, las facturas nuevas con descuentos o cargos, globales o por línea, reciben QUALIFICATION_ADJUSTMENTS_UNSUPPORTED.