Registration Operations

Overview

The registration operation records medical services, procedures, and supplies provided to patients. It supports both header-level validation and item-level detail validation, allowing for partial success scenarios.

Operation Method

Hl7Result<RegistracionResponse> consultarRegistracion(RegistracionRequest request)

Service Location: Hl7Service.java:39-50 Endpoint URL: Retrieved via EnvironmentConfig.getHl7RegistracionUrl()

Request Structure

RegistracionRequest

The request contains operation parameters, technical data, provider information, and HL7 extensions.

Operation Data Fields

modo

String

required

Operation mode. Single character field (max length: 1)

creden

String

required

Credential number. Fixed length: 23 characters

tipo

Integer

required

Service type identifier (tinyint)

alta

String

Registration datetime in format: yyyy-MM-dd'T'HH:mm:ss

fecdif

String

Service date in format: yyyy-MM-dd (varchar 10)

manual

Manual

Manual processing indicator. Enum values:

MANUAL (“0”)
CAPITADOR (“C”)
COMSULTA (“L”)

consulta

Manual

Consultation mode indicator (same enum as manual)

Technical Data Fields

ticketExt

Integer

External ticket number for tracking

termId

String

Terminal identifier (max length: 20)

interNro

Integer

Internal transaction number

Provider Fields

cuit

String

Provider CUIT tax identification (max length: 40)

oriMatri

String

Provider registration origin (max length: 10)

Previous Result Fields

autoriz

Integer

Previous authorization number if applicable

rechaExt

Integer

Previous rejection code (smallint)

HL7 Extended Fields

icd

String

ICD diagnostic code (max length: 6)

param1

String

Custom parameter 1 (max length: 255)

param2

String

Custom parameter 2 (max length: 255)

param3

String

Custom parameter 3 (max length: 255)

tipoEfector

String

Effector type code (max length: 4)

idEfector

String

Effector identifier (max length: 11)

tipoPrescr

String

Prescriber type code (max length: 4)

idPrescr

String

Prescriber identifier (max length: 11)

msgId

String

Message identifier (max length: 20)

ackacept

String

Acknowledgment acceptance code (max length: 2)

ackackapl

String

Acknowledgment application code (max length: 2)

tipoMensaje

String

Message type indicator (max length: 1)

powerBuilder

Boolean

PowerBuilder compatibility flag (bit)

Example Request

RegistracionRequest request = new RegistracionRequest();
request.setModo("N");
request.setCreden("12345678901234567890123");
request.setTipo(2);
request.setAlta("2024-03-15T10:30:00");
request.setFecdif("2024-03-15");
request.setCuit("20123456789");
request.setIcd("A00.0");
request.setParam1("Additional info");

Hl7Result<RegistracionResponse> result = hl7Service.consultarRegistracion(request);

Response Structure

RegistracionResponse

The response has a two-level structure: a header (cabecera) and optional detail items (detalle).

cabecera

RegistracionCabecera

required

Header information containing overall transaction data and rejection status

detalle

RegistracionDetalle[]

Array of detail items with individual item rejection information. May be null if no detail validation is performed.

RegistracionCabecera

Header-level response data.

Transaction Fields

transac

Long

Transaction identifier assigned by the system

transacAlta

String

Transaction registration timestamp

autoriz

Integer

Authorization number if approved

Rejection Fields

rechaCabecera

Integer

Header rejection code. If greater than 0, the entire registration is rejected at the header level.

rechaCabeDeno

String

Human-readable description of the header rejection reason

Member Information

apeNom

String

Patient’s full name

pmi

String

Patient Medical Identifier

edad

Integer

Patient age

sexo

String

Patient sex

sexoAuto

String

Authorized sex value

generoAuto

String

Authorized gender value

Coverage Information

planCodi

String

Plan code identifier

gravado

String

Tax status indicator

leyimp

String

Tax law applicability

Provider Information

icdDeno

String

ICD code description

nomPrestad

String

Provider name

sucursal

String

Branch office identifier

RegistracionDetalle

Item-level detail with individual rejection tracking.

transac

Long

Transaction identifier for this detail item

recha

Integer

Item rejection code. If greater than 0, this specific item is rejected.

denoItem

String

Human-readable description of the item rejection reason

Example Response (Full Success)

{
  "cabecera": {
    "transac": 123456789,
    "transacAlta": "2024-03-15T10:30:45",
    "rechaCabecera": 0,
    "rechaCabeDeno": null,
    "apeNom": "DOE, JOHN",
    "pmi": "987654321",
    "planCodi": "PLAN001",
    "autoriz": 555123
  },
  "detalle": null
}

Example Response (Header Rejected)

{
  "cabecera": {
    "transac": 123456790,
    "rechaCabecera": 210,
    "rechaCabeDeno": "Credencial sin cobertura activa",
    "apeNom": "DOE, JOHN",
    "pmi": "987654321"
  },
  "detalle": null
}

Example Response (Partial Success)

{
  "cabecera": {
    "transac": 123456791,
    "rechaCabecera": 0,
    "rechaCabeDeno": null,
    "apeNom": "DOE, JOHN",
    "pmi": "987654321",
    "autoriz": 555124
  },
  "detalle": [
    {
      "transac": 123456791,
      "recha": 0,
      "denoItem": null
    },
    {
      "transac": 123456791,
      "recha": 405,
      "denoItem": "Código de práctica no autorizado"
    },
    {
      "transac": 123456791,
      "recha": 0,
      "denoItem": null
    }
  ]
}

Validation Logic

The service performs two-level validation (Hl7Service.java:131-169):

1. Header Validation

if (cab.getRechaCabecera() != null && cab.getRechaCabecera() > 0) {
    return Hl7Result.rejected(
        r,
        Hl7Error.functional(
            String.valueOf(cab.getRechaCabecera()),
            cab.getRechaCabeDeno()
        )
    );
}

Header Rejection: If rechaCabecera > 0 in the cabecera, the entire registration is rejected. No items are processed.

2. Detail Validation

List<Hl7ItemError> detalles = new ArrayList<>();

if (r.getDetalle() != null) {
    for (RegistracionDetalle d : r.getDetalle()) {
        if (d.getRecha() != null && d.getRecha() > 0) {
            detalles.add(
                new Hl7ItemError(
                    String.valueOf(d.getRecha()),
                    d.getDenoItem(),
                    Hl7ItemErrorOrigin.DETALLE
                )
            );
        }
    }
}

return detalles.isEmpty()
    ? Hl7Result.ok(r)
    : Hl7Result.partial(r, detalles);

Partial Success: If the header is accepted but one or more detail items have recha > 0, the operation returns PARTIAL status with a list of Hl7ItemError objects. Each error has origin = DETALLE.

Result Status

OK - Complete success

Hl7Result.ok(response)

Header accepted: rechaCabecera is 0, null, or negative
All detail items accepted or no detail validation performed
Full registration processed

PARTIAL - Partial success

Hl7Result.partial(response, itemErrors)

Header accepted: rechaCabecera is 0, null, or negative
One or more detail items rejected: recha > 0
Contains list of Hl7ItemError with origin DETALLE
Some items registered, others rejected

REJECTED - Header rejection

Hl7Result.rejected(response, error)

Header rejected: rechaCabecera > 0
No items processed
Contains functional error with rejection details

ERROR - Technical failure

Hl7Result.error(error)

Network error, invalid response, or parsing failure
No response data available

Handling Results

Complete Success

Hl7Result<RegistracionResponse> result = hl7Service.consultarRegistracion(request);

if (result.isOk()) {
    RegistracionResponse data = result.getData().get();
    RegistracionCabecera cab = data.getCabecera();
    
    System.out.println("Registration successful");
    System.out.println("Transaction: " + cab.getTransac());
    System.out.println("Authorization: " + cab.getAutoriz());
    System.out.println("Patient: " + cab.getApeNom());
}

Partial Success

if (result.isPartial()) {
    RegistracionResponse data = result.getData().get();
    List<Hl7ItemError> errors = result.getDetails();
    
    System.out.println("Partial registration - some items rejected:");
    System.out.println("Transaction: " + data.getCabecera().getTransac());
    
    for (Hl7ItemError error : errors) {
        System.err.println("Item error [" + error.getCode() + "]: " 
            + error.getMessage());
    }
}

Header Rejection

if (result.getStatus() == Hl7Status.REJECTED) {
    RegistracionResponse data = result.getData().get();
    Hl7Error error = result.getIssue().get();
    
    System.err.println("Registration rejected at header level");
    System.err.println("Rejection code: " + error.getCode());
    System.err.println("Reason: " + error.getMessage());
    System.err.println("Transaction: " + data.getCabecera().getTransac());
}

Technical Error

if (result.isError()) {
    Hl7Error error = result.getIssue().get();
    System.err.println("Technical error: " + error.getMessage());
    System.err.println("Origin: " + error.getOrigin());
}

Environment Configuration

The registration endpoint URL is constructed using:

EnvironmentConfig.getHl7RegistracionUrl(SessionContext.getEnvironment())

URL Pattern (EnvironmentConfig.java:57-63):

{baseUrl}{apiContextPath}{apiVersionV3}{hl7ContextPath}/registracion

Example: https://api.example.com/api/v3/hl7/registracion

Eligibility Operations

Check eligibility before registration

Cancellation Operations

Cancel registered services

Result Types

Handle partial success and rejections

Core Services

HL7 Operations

Models

Overview

Operation Method

Request Structure

RegistracionRequest

Operation Data Fields

Technical Data Fields

Provider Fields

Previous Result Fields

HL7 Extended Fields

Example Request

Response Structure

RegistracionResponse

RegistracionCabecera

Transaction Fields

Rejection Fields

Member Information

Coverage Information

Provider Information

RegistracionDetalle

Example Response (Full Success)

Example Response (Header Rejected)

Example Response (Partial Success)

Validation Logic

1. Header Validation

2. Detail Validation

Result Status

Handling Results

Complete Success

Partial Success

Header Rejection

Technical Error

Environment Configuration

Eligibility Operations

Cancellation Operations

Result Types

Build docs developers (and LLMs) love

Core Services

HL7 Operations

Models

​Overview

​Operation Method

​Request Structure

​RegistracionRequest

​Operation Data Fields

​Technical Data Fields

​Provider Fields

​Previous Result Fields

​HL7 Extended Fields

​Example Request

​Response Structure

​RegistracionResponse

​RegistracionCabecera

​Transaction Fields

​Rejection Fields

​Member Information

​Coverage Information

​Provider Information

​RegistracionDetalle

​Example Response (Full Success)

​Example Response (Header Rejected)

​Example Response (Partial Success)

​Validation Logic

​1. Header Validation

​2. Detail Validation

​Result Status

​Handling Results

​Complete Success

​Partial Success

​Header Rejection

​Technical Error

​Environment Configuration

​Related Operations

Eligibility Operations

Cancellation Operations

Result Types

Build docs developers (and LLMs) love

Overview

Operation Method

Request Structure

RegistracionRequest

Operation Data Fields

Technical Data Fields

Provider Fields

Previous Result Fields

HL7 Extended Fields

Example Request

Response Structure

RegistracionResponse

RegistracionCabecera

Transaction Fields

Rejection Fields

Member Information

Coverage Information

Provider Information

RegistracionDetalle

Example Response (Full Success)

Example Response (Header Rejected)

Example Response (Partial Success)

Validation Logic

1. Header Validation

2. Detail Validation

Result Status

Handling Results

Complete Success

Partial Success

Header Rejection

Technical Error

Environment Configuration

Related Operations