Service Registration

Overview

Service registration (Registración) records healthcare services provided to eligible patients. This operation supports both complete success and partial success scenarios where individual line items may be rejected while the overall transaction is approved.

Registration Request

Method Signature

public Hl7Result<RegistracionResponse> consultarRegistracion(
    RegistracionRequest request
)

Source: Hl7Service.java:39-50

Service registration requires an active authenticated session and should follow a successful eligibility check.

RegistracionRequest Structure

The registration request contains comprehensive service and provider information:

Operation Data

modo

String

required

Operation mode - single character code

creden

String

required

Patient credential number (up to 23 characters)

tipo

Integer

required

Transaction type code

alta

String

Service date/time in format: yyyy-MM-dd'T'HH:mm:ss

fecdif

String

Service date in format: yyyy-MM-dd

manual

Manual

Manual processing flag:

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

consulta

Manual

Consultation type flag (same enum as manual)

Technical Data

ticketExt

Integer

External ticket number for transaction tracking

termId

String

Terminal identifier (up to 20 characters)

interNro

Integer

Internal transaction number

Provider Data

cuit

String

Provider CUIT (tax identification) - up to 40 characters

oriMatri

String

Provider matriculation origin (up to 10 characters)

Previous Result Data

autoriz

Integer

Previous authorization number (if modifying)

rechaExt

Integer

Previous rejection code (if re-submitting)

HL7 Extended Data

icd

String

ICD diagnosis code (up to 6 characters)

param1

String

Custom parameter 1 (up to 255 characters)

param2

String

Custom parameter 2 (up to 255 characters)

param3

String

Custom parameter 3 (up to 255 characters)

tipoEfector

String

Effector type code (4 characters)

idEfector

String

Effector identifier (11 characters)

tipoPrescr

String

Prescriber type code (4 characters)

idPrescr

String

Prescriber identifier (11 characters)

msgId

String

Message ID (20 characters)

ackacept

String

Acknowledgment acceptance code (2 characters)

ackackapl

String

Acknowledgment application code (2 characters)

tipoMensaje

String

Message type (1 character)

powerBuilder

Boolean

PowerBuilder compatibility flag

Request Example

RegistracionRequest request = new RegistracionRequest();

// Operation data
request.setModo("N");
request.setCreden("12345678901234567890123");
request.setTipo(1);
request.setAlta("2024-03-15T14:30:00");
request.setFecdif("2024-03-15");
request.setManual(Manual.MANUAL);

// Technical data
request.setTicketExt(67890);
request.setTermId("TERM-001");
request.setInterNro(100);

// Provider data
request.setCuit("20123456789");
request.setOriMatri("PROV-001");

// Extended HL7 data
request.setIcd("A09.0");
request.setParam1("Service item 1");
request.setParam2("Service item 2");

Registration Response

Response Structure

The response contains both header (Cabecera) and detail (Detalle) information: Source: RegistracionResponse.java

public class RegistracionResponse {
    private RegistracionCabecera cabecera;
    private RegistracionDetalle[] detalle;
}

Cabecera (Header) Fields

transac

Long

Transaction number assigned by the system

transacAlta

String

Transaction creation timestamp

rechaCabecera

Integer

Header rejection code. If greater than 0, the entire transaction is rejected.

rechaCabeDeno

String

Human-readable rejection reason for header rejection

apeNom

String

Patient’s last name and first name

planCodi

String

Patient’s plan code

pmi

String

Patient Medical Identifier

edad

Integer

Patient age

sexo

String

Patient sex

sexoAuto

String

Authorized sex value

generoAuto

String

Authorized gender value

gravado

String

Taxable status indicator

leyimp

String

Tax law applicability

icdDeno

String

ICD code denomination

nomPrestad

String

Provider name

sucursal

String

Branch office identifier

autoriz

Integer

Authorization number for the transaction

Detalle (Detail) Fields

transac

Long

Detail transaction number (may differ from header)

recha

Integer

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

denoItem

String

Human-readable rejection reason for this specific item

Validation Logic

The service implements sophisticated validation to handle both complete and partial success scenarios: Source: Hl7Service.java:131-169

private Hl7Result<RegistracionResponse> validarRegistracion(
    RegistracionResponse r
) {
    if (r == null || r.getCabecera() == null) {
        return errorRespuestaInvalida();
    }
    
    RegistracionCabecera cab = r.getCabecera();
    
    // Check for header rejection
    if (cab.getRechaCabecera() != null && cab.getRechaCabecera() > 0) {
        return Hl7Result.rejected(
            r,
            Hl7Error.functional(
                String.valueOf(cab.getRechaCabecera()),
                cab.getRechaCabeDeno()
            )
        );
    }
    
    // Check for detail item rejections
    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);
}

Validation Flow

Null Check: Verify response and cabecera exist
Header Rejection Check: If rechaCabecera > 0, entire transaction is rejected
Detail Validation: Iterate through all detail items
Partial Success: If header is approved but some details are rejected, return PARTIAL status
Complete Success: If header and all details are approved, return OK status

A header rejection (rechaCabecera > 0) means the entire transaction failed. Detail items are only validated if the header is approved.

Handling Partial Success

Partial success occurs when the transaction is approved at the header level, but individual line items are rejected:

Hl7ItemError Structure

public class Hl7ItemError {
    private final String code;           // Rejection code
    private final String message;        // Rejection description
    private final Hl7ItemErrorOrigin origin;  // DETALLE
}

Checking for Partial Results

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

if (result.isOk()) {
    // Complete success - all items approved
    System.out.println("All items registered successfully");
    
} else if (result.isPartial()) {
    // Partial success - some items rejected
    RegistracionResponse data = result.getData().get();
    List<Hl7ItemError> rejectedItems = result.getDetails();
    
    System.out.println("Transaction approved: " + data.getCabecera().getTransac());
    System.out.println("Rejected items: " + rejectedItems.size());
    
    for (Hl7ItemError item : rejectedItems) {
        System.err.println("  Code: " + item.getCode());
        System.err.println("  Reason: " + item.getMessage());
    }
}

With PARTIAL status, the transaction header is successful and has a valid transac number. Only specific detail items were rejected.

Complete Usage Example

import com.hl7client.model.dto.request.hl7.RegistracionRequest;
import com.hl7client.model.dto.request.hl7.Manual;
import com.hl7client.model.dto.response.hl7.RegistracionResponse;
import com.hl7client.model.dto.response.hl7.RegistracionCabecera;
import com.hl7client.model.result.Hl7Result;
import com.hl7client.model.result.Hl7Status;
import com.hl7client.model.result.Hl7ItemError;
import com.hl7client.service.Hl7Service;

public class RegistrationExample {
    
    private final Hl7Service hl7Service;
    
    public void registerService(String credential, String icdCode, 
                                String serviceDescription) {
        
        // Build registration request
        RegistracionRequest request = new RegistracionRequest();
        request.setModo("N");
        request.setCreden(credential);
        request.setTipo(1);
        request.setAlta(getCurrentTimestamp());
        request.setFecdif(getCurrentDate());
        request.setManual(Manual.MANUAL);
        request.setTicketExt(generateTicketNumber());
        request.setTermId(getTerminalId());
        request.setCuit(getProviderCuit());
        request.setIcd(icdCode);
        request.setParam1(serviceDescription);
        
        // Execute registration
        Hl7Result<RegistracionResponse> result = 
            hl7Service.consultarRegistracion(request);
        
        // Handle response
        if (result.isOk()) {
            handleCompleteSuccess(result.getData().get());
            
        } else if (result.isPartial()) {
            handlePartialSuccess(
                result.getData().get(), 
                result.getDetails()
            );
            
        } else if (result.getStatus() == Hl7Status.REJECTED) {
            handleCompleteRejection(
                result.getData().get(),
                result.getIssue().get()
            );
            
        } else if (result.isError()) {
            handleTechnicalError(result.getIssue().get());
        }
    }
    
    private void handleCompleteSuccess(RegistracionResponse response) {
        RegistracionCabecera cab = response.getCabecera();
        
        System.out.println("Registration successful!");
        System.out.println("Transaction: " + cab.getTransac());
        System.out.println("Authorization: " + cab.getAutoriz());
        System.out.println("Patient: " + cab.getApeNom());
        System.out.println("PMI: " + cab.getPmi());
        System.out.println("Plan: " + cab.getPlanCodi());
        
        // Store transaction number for future reference
        storeTransactionNumber(cab.getTransac());
    }
    
    private void handlePartialSuccess(
        RegistracionResponse response,
        List<Hl7ItemError> rejectedItems
    ) {
        RegistracionCabecera cab = response.getCabecera();
        
        System.out.println("Registration partially successful");
        System.out.println("Transaction: " + cab.getTransac());
        System.out.println("Authorization: " + cab.getAutoriz());
        
        System.out.println("\nRejected items: " + rejectedItems.size());
        for (Hl7ItemError item : rejectedItems) {
            System.err.println("  Code: " + item.getCode());
            System.err.println("  Reason: " + item.getMessage());
        }
        
        // Transaction is valid despite rejected items
        storeTransactionNumber(cab.getTransac());
        
        // Notify user about rejected items
        notifyPartialSuccess(rejectedItems);
    }
    
    private void handleCompleteRejection(
        RegistracionResponse response,
        Hl7Error error
    ) {
        System.err.println("Registration rejected:");
        System.err.println("Code: " + error.getCode());
        System.err.println("Reason: " + error.getMessage());
        
        // Header data may still be available
        if (response.getCabecera() != null) {
            RegistracionCabecera cab = response.getCabecera();
            if (cab.getApeNom() != null) {
                System.err.println("Patient: " + cab.getApeNom());
            }
        }
        
        // Do not proceed with service provision
        notifyRejection(error.getMessage());
    }
    
    private void handleTechnicalError(Hl7Error error) {
        System.err.println("Technical error: " + error.getMessage());
        System.err.println("Origin: " + error.getOrigin());
        
        if (error.isSession()) {
            promptReauthentication();
        } else {
            retryOrEscalate(error);
        }
    }
}

Best Practices

Check Eligibility Before Registration

Always verify patient eligibility before attempting registration:

// 1. Check eligibility
Hl7Result<ElegibilidadResponse> eligibility = 
    hl7Service.consultarElegibilidad(eligibilityRequest);

if (!eligibility.isOk()) {
    System.err.println("Patient not eligible");
    return;
}

// 2. Proceed with registration
Hl7Result<RegistracionResponse> registration = 
    hl7Service.consultarRegistracion(registrationRequest);

Handle Partial Success Appropriately

Partial success means the transaction is valid but has item-level issues:

if (result.isPartial()) {
    // Transaction number is valid
    Long transactionId = result.getData().get()
        .getCabecera().getTransac();
    
    // Store the transaction
    saveTransaction(transactionId);
    
    // But notify about rejected items
    List<Hl7ItemError> rejected = result.getDetails();
    notifyUserAboutRejectedItems(rejected);
}

Store Transaction Numbers

Always store the transaction number for auditing and potential cancellation:

if (result.isOk() || result.isPartial()) {
    Long transac = result.getData().get()
        .getCabecera().getTransac();
    
    // Store for future reference
    database.saveTransaction(transac, request);
}

Validate Request Data

Validate request data before submission:

private void validateRequest(RegistracionRequest request) {
    if (request.getCreden() == null || request.getCreden().length() > 23) {
        throw new IllegalArgumentException("Invalid credential");
    }
    
    if (request.getCuit() == null || request.getCuit().length() > 40) {
        throw new IllegalArgumentException("Invalid CUIT");
    }
    
    if (request.getIcd() != null && request.getIcd().length() > 6) {
        throw new IllegalArgumentException("ICD code too long");
    }
}

Get Started

Core Features

Configuration

Development

Overview

Registration Request

Method Signature

RegistracionRequest Structure

Operation Data

Technical Data

Provider Data

Previous Result Data

HL7 Extended Data

Request Example

Registration Response

Response Structure

Cabecera (Header) Fields

Detalle (Detail) Fields

Validation Logic

Validation Flow

Handling Partial Success

Hl7ItemError Structure

Checking for Partial Results

Complete Usage Example

Best Practices

See Also

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Development

​Overview

​Registration Request

​Method Signature

​RegistracionRequest Structure

​Operation Data

​Technical Data

​Provider Data

​Previous Result Data

​HL7 Extended Data

​Request Example

​Registration Response

​Response Structure

​Cabecera (Header) Fields

​Detalle (Detail) Fields

​Validation Logic

​Validation Flow

​Handling Partial Success

​Hl7ItemError Structure

​Checking for Partial Results

​Complete Usage Example

​Best Practices

​See Also

Build docs developers (and LLMs) love

Overview

Registration Request

Method Signature

RegistracionRequest Structure

Operation Data

Technical Data

Provider Data

Previous Result Data

HL7 Extended Data

Request Example

Registration Response

Response Structure

Cabecera (Header) Fields

Detalle (Detail) Fields

Validation Logic

Validation Flow

Handling Partial Success

Hl7ItemError Structure

Checking for Partial Results

Complete Usage Example

Best Practices

See Also