Anticipos Mutations - Satélite API

Overview

The Anticipos API provides mutation operations to create advances, update their status through the approval workflow, and manage approver assignments. All mutations require proper authentication and authorization.

CreateAnticipo

Creates a new advance request in the system.

mutation {
  createAnticipo(value: {
    correo: "user@example.com"
    cedula: "1234567890"
    nombre: "Juan Pérez"
    estado: "INGRESADO"
    id_beneficiario: 456
    id_orden_compra: 789
    id_tipo_moneda: 10
    id_porcentaje: null
    valorMoneda: 1.0
    valor: 5000.00
    descripcion: "Anticipo para compra de materiales"
    credito: "SI"
    justifica: "Necesario para inicio de proyecto"
    suministro: "NO"
    id_cme: 5
    claseDoc: "KA"
    asignacion: ""
    texto: ""
  }) {
    idAnticipo
    correo
    estado
    valor
    fechaRegistro
    beneficiario {
      razonSocial
      codigoBeneficiario
    }
  }
}

Input Parameters

correo

string

required

Email address of the requester

cedula

string

required

Identification number of the requester

nombre

string

required

Full name of the requester

estado

string

required

Initial state, typically “INGRESADO”

id_beneficiario

integer

required

ID of the beneficiary receiving the advance

id_orden_compra

integer

Optional purchase order ID if the advance is linked to a PO

id_tipo_moneda

integer

required

Currency type ID from catalog (e.g., USD, EUR)

id_porcentaje

integer

Optional percentage ID if advance is calculated as percentage of PO value

valorMoneda

decimal

Exchange rate or currency value

valor

decimal

required

Amount of the advance

descripcion

string

required

Description or justification for the advance

credito

string

Credit-related information

justifica

string

Detailed justification

suministro

string

Supply-related flag (“SI” or “NO”)

id_cme

integer

required

Special Payment Condition (CME) ID

claseDoc

string

SAP document class (e.g., “KA” for supplier advance)

asignacion

string

Assignment field (populated after approval)

texto

string

Text field for SAP (populated after approval)

Response

Returns the created advance object with generated ID and registration timestamp.

{
  "data": {
    "createAnticipo": {
      "idAnticipo": 123,
      "correo": "user@example.com",
      "estado": "INGRESADO",
      "valor": 5000.00,
      "fechaRegistro": "2024-03-05T10:30:00",
      "beneficiario": {
        "razonSocial": "Proveedor XYZ S.A.",
        "codigoBeneficiario": "PROV001"
      }
    }
  }
}

The fechaRegistro field is automatically set to the current server time (UTC-5) when the advance is created.

UpdateAnticipoEstado

Updates the status of an advance, triggering approval workflow actions including email notifications and SAP integration.

mutation {
  updateAnticipoEstado(value: {
    idAnticipo: 123
    estado: "REVISIÓN"
  }) {
    idAnticipo
    estado
    fechaCambioEstado
    codigoRegistroSap
  }
}

Input Parameters

idAnticipo

integer

required

ID of the advance to update

estado

string

required

New state for the advance. Valid values:

REVISIÓN: Submit for first-level approval
APROBADO_T: First-level approval (triggers second-level notification)
APROBADO: Final approval (triggers SAP registration)
RECHAZADO: First-level rejection
RECHAZADO_T: Second-level rejection

id_motivo_rechazo

integer

Required when estado is “RECHAZADO” or “RECHAZADO_T”. ID of rejection reason from catalog.

observaciones

string

Optional observations, typically used with rejections to provide feedback

Workflow Actions by State

REVISIÓN - Submit for Approval

When advancing to REVISIÓN state:

Sets fechaCambioEstado to current timestamp
Sends email notification to requester confirming submission
Retrieves first-level approver
Sends email notification to approver requesting review

Email sent to: Requester and first-level approver

APROBADO_T - First Level Approved

When first-level approver approves:

Sets fechaCambioEstado to current timestamp
Retrieves second-level approver
Sends email notification to second-level approver

Email sent to: Second-level approver

If there is no second-level approver, this state can be skipped directly to APROBADO.

APROBADO - Final Approval

When final approval is granted, the system performs comprehensive SAP integration:

Date Calculation: Calculates next business day for payment, excluding:
- Weekends (Saturday/Sunday)
- Company holidays from catalog
SAP Document Creation: Builds SAP payment document with:
- Header information (document class, company, dates, currency)
- Creditor information (beneficiary SAP code, CME)
- Position details (amount, base date, assignment, text)
API Call: Sends document to SAP via ApiAnticipos service
Response Processing:
- Stores SAP document number in codigoRegistroSap
- Sets asignacion with payment date (format: “PAGDIAdd/MM/yyyy”)
- Sets texto with advance ID and beneficiary code
Email Notification: Sends approval confirmation to requester

Email sent to: Requester

If SAP integration fails, a GraphQLException is thrown with error code Error_Api_Sap_Web_Service.

RECHAZADO / RECHAZADO_T - Rejection

When an advance is rejected (at either level):

Sets fechaCambioEstado to current timestamp
Stores id_motivo_rechazo and observaciones
Retrieves rejection reason from catalog
Sends detailed rejection email to requester including:
- Approver name who rejected
- Rejection reason
- Observations/feedback

Email sent to: Requester

SAP Integration Details

For APROBADO state, the system creates a document with this structure:

// Header
{
  "bldat": "05.03.2024",        // Document date
  "blart": "KA",                 // Document class
  "bukrs": "1000",               // Company code
  "budat": "05.03.2024",        // Posting date
  "monat": "03",                 // Fiscal period
  "waers": "USD",                // Currency
  "xblnr": "123",                // Reference (anticipo ID)
  "bktxt": "123 4500123456"     // Header text (ID + PO)
}

// Creditor
{
  "newko": "PROV001",            // Beneficiary SAP code
  "zumsk": "Z001"                // CME type
}

// Position
{
  "wrbtr": "5000.00",            // Amount
  "zfbdt": "05.03.2024",        // Base date
  "zuonr": "PAGDIA06/03/2024",  // Assignment with payment date
  "sgtxt": "123-4500123456-..." // Position text (max 50 chars)
}

Response

{
  "data": {
    "updateAnticipoEstado": {
      "idAnticipo": 123,
      "estado": "APROBADO",
      "fechaCambioEstado": "2024-03-05T14:20:00",
      "codigoRegistroSap": "5000012345"
    }
  }
}

Error Responses

{
  "errors": [
    {
      "message": "IndAntAnticipoDTO not found.",
      "extensions": {
        "code": "IndAntAnticipoDTO_NOT_FOUND"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Error, no registrado en SAP.",
      "extensions": {
        "code": "Error_Api_Sap_Web_Service"
      }
    }
  ]
}

CreateAprobacionAnticipo

Creates an approval record linking an approver to an advance.

mutation {
  createAprobacionAnticipo(value: {
    id_aprobador: 10
    id_anticipo: 123
    nivel: 1
    sistema: "Anticipos"
    estado: "Pendiente"
  }) {
    idAprobacion
    nivel
    estado
    aprobador {
      nombre
      email
    }
  }
}

Input Parameters

id_aprobador

integer

required

User ID of the approver

id_anticipo

integer

required

Advance ID to be approved

nivel

integer

required

Approval level (1 or 2)

sistema

string

required

System name, should be “Anticipos”

estado

string

required

Initial approval status, typically “Pendiente”

Response

{
  "data": {
    "createAprobacionAnticipo": {
      "idAprobacion": 456,
      "nivel": 1,
      "estado": "Pendiente",
      "aprobador": {
        "nombre": "María González",
        "email": "maria.gonzalez@example.com"
      }
    }
  }
}

Typically, you create approval records immediately after creating the advance, assigning both first and second-level approvers based on business rules (amount thresholds, department, etc.).

UpdateAprobacionAnticipo

Updates an approval record, typically to mark it as completed.

mutation {
  updateAprobacionAnticipo(value: {
    idAprobacion: 456
    id_aprobador: 10
    id_anticipo: 123
    estado: "Aprobado"
  }) {
    idAprobacion
    estado
  }
}

Input Parameters

idAprobacion

integer

required

ID of the approval record to update

id_aprobador

integer

required

User ID of the approver

id_anticipo

integer

required

Advance ID

estado

string

required

New approval status (e.g., “Aprobado”, “Rechazado”)

Updating the approval record does NOT automatically update the advance status. You must call UpdateAnticipoEstado separately to trigger the workflow actions.

DeleteAnticipo

Deletes an advance and all associated approval records.

mutation {
  deleteAnticipo(id: 123) {
    idAnticipo
    estado
  }
}

Input Parameters

integer

required

ID of the advance to delete

Response

Returns the deleted advance(s).

This operation is irreversible and will cascade delete all approval records associated with the advance. Use with caution and ensure proper authorization.

DeleteAprobacion

Deletes a specific approval record.

mutation {
  deleteAprobacion(id: 456) {
    idAprobacion
    nivel
  }
}

Input Parameters

integer

required

ID of the approval record to delete

Deleting an approval record does not affect the advance itself, only the approval assignment.

Complete Workflow Example

Here’s a complete example of creating and approving an advance:

Step 1: Create Advance

mutation {
  createAnticipo(value: {
    correo: "requester@example.com"
    cedula: "1234567890"
    nombre: "Juan Pérez"
    estado: "INGRESADO"
    id_beneficiario: 456
    id_tipo_moneda: 10
    valor: 5000.00
    descripcion: "Anticipo para materiales"
    id_cme: 5
    claseDoc: "KA"
  }) {
    idAnticipo
  }
}

Step 2: Assign Approvers

mutation {
  nivel1: createAprobacionAnticipo(value: {
    id_aprobador: 10
    id_anticipo: 123
    nivel: 1
    sistema: "Anticipos"
    estado: "Pendiente"
  }) {
    idAprobacion
  }
  
  nivel2: createAprobacionAnticipo(value: {
    id_aprobador: 20
    id_anticipo: 123
    nivel: 2
    sistema: "Anticipos"
    estado: "Pendiente"
  }) {
    idAprobacion
  }
}

Step 3: Submit for Review

mutation {
  updateAnticipoEstado(value: {
    idAnticipo: 123
    estado: "REVISIÓN"
  }) {
    estado
    fechaCambioEstado
  }
}

Step 4: First-Level Approval

mutation {
  # Update approval record
  updateAprobacionAnticipo(value: {
    idAprobacion: 456
    estado: "Aprobado"
  }) {
    estado
  }
  
  # Update advance status
  updateAnticipoEstado(value: {
    idAnticipo: 123
    estado: "APROBADO_T"
  }) {
    estado
  }
}

Step 5: Final Approval (SAP Registration)

mutation {
  # Update second approval record
  updateAprobacionAnticipo(value: {
    idAprobacion: 457
    estado: "Aprobado"
  }) {
    estado
  }
  
  # Final approval - triggers SAP integration
  updateAnticipoEstado(value: {
    idAnticipo: 123
    estado: "APROBADO"
  }) {
    estado
    codigoRegistroSap
    asignacion
  }
}

Best Practices

Validation

Validate beneficiary exists and is not blocked
Check credit limits before creating advance
Verify purchase order amount vs. advance amount
Ensure approvers have proper permissions

Error Handling

Handle SAP integration failures gracefully
Log all approval actions for audit trail
Implement retry logic for network failures
Validate state transitions are valid

Security

Verify user can only update their own advances
Check approver has permission for the level
Validate advance hasn’t been modified by another user
Audit all status changes

Performance

Batch approval record creation
Use transactions for multi-step operations
Cache catalog data (currencies, CME types)
Index advances by estado and correo

Email Notifications

The system automatically sends HTML email notifications for:

Event	Recipients	Template
Submit for review	Requester, Approver 1	NotificacionAnticipo
First-level approval	Approver 2	NotificacionAnticipo
Final approval	Requester	NotificacionAnticipoAprobado
Rejection (any level)	Requester	NotificacionAnticipoRechazado

Email content includes:

Advance ID and details
Beneficiary information
Amount and currency
Approver name (for approvals/rejections)
Rejection reason and observations (for rejections)
SAP document number (for final approval)

Query Advances

Learn how to retrieve advance information

Overview

Understand the anticipos module architecture

Authentication

Plan Comercial

Orden Compra

Anticipos

Reembolsos

Supply Management

Bitácora Cumplimiento

Activos Fijos

Catalogos

External Integrations

​Overview

​CreateAnticipo

​Input Parameters

​Response

​UpdateAnticipoEstado

​Input Parameters

​Workflow Actions by State

​SAP Integration Details

​Response

​Error Responses

​CreateAprobacionAnticipo

​Input Parameters

​Response

​UpdateAprobacionAnticipo

​Input Parameters

​DeleteAnticipo

​Input Parameters

​Response

​DeleteAprobacion

​Input Parameters

​Complete Workflow Example

​Step 1: Create Advance

​Step 2: Assign Approvers

​Step 3: Submit for Review

​Step 4: First-Level Approval

​Step 5: Final Approval (SAP Registration)

​Best Practices

Validation

Error Handling

Security

Performance

​Email Notifications

​Related Resources

Query Advances

Overview

Overview

CreateAnticipo

Input Parameters

Response

UpdateAnticipoEstado

Input Parameters

Workflow Actions by State

SAP Integration Details

Response

Error Responses

CreateAprobacionAnticipo

Input Parameters

Response

UpdateAprobacionAnticipo

Input Parameters

DeleteAnticipo

Input Parameters

Response

DeleteAprobacion

Input Parameters

Complete Workflow Example

Step 1: Create Advance

Step 2: Assign Approvers

Step 3: Submit for Review

Step 4: First-Level Approval

Step 5: Final Approval (SAP Registration)

Best Practices

Email Notifications

Related Resources