Update Fideval Contract

POST /recurrent-advances/fideval/update-contract/:contract_id

Actualiza un RecurrentAdvance con los datos devueltos por Fideval tras la creación o firma del contrato: URL de firma digital, estado y metadata adicional.

Endpoint

POST /api/v1/recurrent-advances/fideval/update-contract/{contract_id}/

• contract_id (path): número de contrato generado por Fideval. Debe coincidir con RecurrentAdvance.contract_created_number.

Authentication

api-key: YOUR_API_KEY
Content-Type: application/json

El header api-key debe corresponder a un ExternalProvider.api_key válido. Si falta o es inválido → 401 Unauthorized.

Request Body

Campo	Tipo	Requerido	Descripción
signing_url	string	✓	URL de firma digital devuelta por Fideval (UrlFirmaContrato). Máx 2000 caracteres.
status	string	✓	Estado del contrato. Valores permitidos: COMPLETED, REJECTED, PENDING_TO_SIGN.
metadata	object	✗	Datos adicionales. Se mergea con la metadata existente del RecurrentAdvance.

Mapeo de status

El valor recibido se mapea al RecurrentAdvanceStatus interno:

Input	Mapea a
COMPLETED	COMPLETED
REJECTED	REJECTED
PENDING_TO_SIGN	PENDING

Ejemplo de solicitud

# Production
curl -X POST \
     -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "signing_url": "https://fideval.example.com/firma/abc123",
       "status": "PENDING_TO_SIGN",
       "metadata": { "source": "fideval-webhook" }
     }' \
     "https://api.erolapp.com/api/v1/recurrent-advances/fideval/update-contract/FID-2026-00123/"

# Staging
curl -X POST \
     -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "signing_url": "https://fideval.example.com/firma/abc123",
       "status": "PENDING_TO_SIGN",
       "metadata": { "source": "fideval-webhook" }
     }' \
     "https://be-staging.erolapp.com/api/v1/recurrent-advances/fideval/update-contract/FID-2026-00123/"

Response

Código de estado: 200 OK

{
  "success": true,
  "recurrent_advance_uuid": "f8d1c2a4-1234-5678-9abc-def012345678",
  "contract_created_number": "FID-2026-00123",
  "status": "PENDING",
  "contract_signing_url": "https://fideval.example.com/firma/abc123"
}

Efectos secundarios

Sobre el RecurrentAdvance localizado por contract_created_number:

1. contract_signing_url se sobrescribe con signing_url.

2. status se setea según el mapeo.

3. metadata se mergea (los keys recibidos pisan a los existentes) y se agrega una traza bajo el key fideval_contract_update:

   {
     "fideval_contract_update": {
       "received_status": "PENDING_TO_SIGN",
       "mapped_status": "PENDING",
       "updated_at": "2026-05-15T13:24:00.123456+00:00"
     }
   }

4. updated_at se actualiza automáticamente.

Casos de uso

• Webhook de Fideval tras creación del contrato con la UrlFirmaContrato lista para que el usuario firme.
• Notificación de cambio de estado del contrato (firmado, rechazado).
• Actualización de metadata adicional sin afectar los campos existentes.

Notas importantes

• El lookup es por contract_created_number exacto (string). Asegurarse de enviar el mismo formato que se generó al crear el contrato.
• El endpoint es idempotente respecto a signing_url y status: reintentar con el mismo body produce el mismo resultado final (la traza updated_at sí se renueva).
• La metadata se mergea, no se reemplaza — los keys históricos se preservan salvo colisión.

Error Responses

400 Bad Request — Body inválido.

{ "error": "signing_url is required" }

{ "error": "Invalid status", "allowed": ["COMPLETED", "REJECTED", "PENDING_TO_SIGN"] }

{ "error": "metadata must be an object" }

401 Unauthorized — Header api-key ausente o inválido.

{ "error": "Invalid or missing API key" }

404 Not Found — No existe un RecurrentAdvance con ese contract_created_number.

{ "error": "No recurrent advance found for contract FID-2026-00123" }

409 Conflict — Más de un RecurrentAdvance comparte ese contract_created_number.

{ "error": "Multiple recurrent advances share contract FID-2026-00123" }