Cofase Integration - Satélite API

Overview

The Cofase (Coface) integration provides access to international credit insurance services and business risk assessment. This integration enables company lookup, credit limit verification, risk rating analysis, and product delivery tracking for B2B transactions.

Architecture

The integration consists of:

ApiCofase - Main service for authentication and API calls (Helpers/ApiCofase.cs)
ApiCofaseRepository - Data persistence layer (Services/ApiCofase/ApiCofaseRepository.cs)
ApiCofaseSettings - Configuration management

Authentication Flow

Cofase uses a two-factor authentication approach:

API Key: Sent via x-api-key header
OAuth Token: Password grant type authentication

Authentication Sequence

1. POST /token?rootcontext={context}&server={server}
   Headers: x-api-key: {apiKey}
   Body: { grantType: "password", username, password, refreshToken: "" }
   
2. Response: { idToken, accessToken, refreshToken, expiresIn, tokenType }

3. Subsequent requests use idToken in Authorization header

Location: Helpers/ApiCofase.cs:30-89

Service Methods

SearchCompanyByIdentifier

Searches for company information using a tax identifier (RUC). Location: Helpers/ApiCofase.cs:91+

Parameters

client

ClienteDTO

required

Client information for logging and context

tokenApi

ApiAuthCofase

required

Valid authentication token from AuthenticateAsync

documento

String!

required

Company identifier (RUC number for Ecuador)

Request Format

GET /companies/identifier
  ?countryCode=ECU
  &identifierType=RUC_ECU
  &identifierValue={documento}

Headers:
  x-api-key: {apiKey}
  X-COF-Policy-Number: {policyNumber}
  authorization: {idToken}

Response Structure

companies

List<Companies>

List of matching companies

count

Int

Number of companies found

GetProductDetailsByDeliveryId

Retrieves product details and credit decisions for a specific delivery.

Parameters

client

ClienteDTO

required

Client information

documento

String!

required

Document identifier

Response Structure

Returns an ApiProductDelivery object containing:

product

Product

Product information and credit decision details

apiCofaseInfo

ApiCofaseDTO

Stored Cofase data from database

Data Models

ApiAuthCofase

Authentication response structure:

{
  idToken: string      // Used for subsequent API calls
  accessToken: string  // Access token
  refreshToken: string // Token for refresh
  expiresIn: string   // Expiration time
  tokenType: string   // Token type (usually "Bearer")
}

Companies

Company information structure:

{
  easyNumber: string                    // Unique Coface identifier
  branches: List<string>                // Branch identifiers
  secondaryIdentifiers: List<SecondaryIdentifiers>
  mainIdentifier: SecondaryIdentifiers  // Primary identifier
  headOffice: HeadOffice               // Headquarters information
  matchedCompanyName: string           // Company name
  internationalCompanyName: string     // International name
}

Product

Credit product details:

{
  decisionTypeCode: string    // Credit decision type
  billedAmount: decimal       // Billed amount
  orderedAmount: OrderedAmount // Requested amount details
  underwriter: string         // Underwriter information
  currentPeriodIds: string    // Current period identifiers
  creditLimitPeriods: string  // Credit limit period data
  ratingScore: string         // Risk rating score
  decisionDate: DateTime      // Date of credit decision
  orderDate: DateTime         // Order date
  orderId: string            // Order identifier
  deliveryId: string         // Delivery identifier
  deliveryStatus: string     // Current delivery status
  familyTypeCode: string     // Product family code
  productCode: string        // Product code
}

Address

Address structure for company locations:

{
  countryCode: string        // ISO country code
  city: string              // City name
  postalCode: string        // Postal/ZIP code
  streets: List<string>     // Street address lines
  geoDivCode: string        // Geographic division code
  poBox: string             // PO Box
  language: string          // Language code
}

Repository Operations

The ApiCofaseRepository provides database operations: Location: Services/ApiCofase/ApiCofaseRepository.cs

Create

Stores a new Cofase record.

Task<ApiCofaseDTO> Create(ApiCofaseDTO apiCofase)

GetById

Retrieves a Cofase record by ID.

Task<ApiCofaseDTO> GetById(int id)

Update

Updates an existing Cofase record.

Task<ApiCofaseDTO> Update(ApiCofaseDTO apiCofase)

GraphQL Integration

GetApiCofaseByClientId

Retrieves Cofase information for a client by document number. Location: Schema/Query/Query.cs:1231-1246

query GetApiCofaseByClientId($documento: String!) {
  getApiCofaseByClientId(documento: $documento) {
    id
    companyCatalog
    decisionTypeCode
    billedAmount
    orderedAmount
    underwriter
    currentPeriodIds
    creditLimitPeriods
    ratingScore
    decisionDate
    orderDate
    orderId
    deliveryId
    deliveryStatus
    familyTypeCode
    productCode
    createdAt
    updatedAt
  }
}

Parameters

documento

String!

required

Client document identifier (Cédula or RUC)

Response Fields

Int

Unique identifier for the Cofase record

companyCatalog

String

Company catalog information (JSON)

decisionTypeCode

String

Credit decision type code

billedAmount

Decimal

Amount billed for the service

orderedAmount

String

Requested credit amount

underwriter

String

Underwriter information

currentPeriodIds

String

Current period identifiers

creditLimitPeriods

String

Credit limit period information

outstandingNotificationDocument

String

Outstanding notification document information

customerComment

String

Customer comments or notes

effectDate

DateTime

Effective date of the credit decision

oclData

String

OCL (Outstanding Credit Limit) data

ratingScore

String

Risk rating score

decisionDate

DateTime

Date when credit decision was made

position

String

Position information

deliverySource

String

Source of the delivery

orderDate

DateTime

Date when order was placed

orderId

String

Unique order identifier

deliveryId

String

Unique delivery identifier

deliveryStatus

String

Current status of the delivery

familyTypeCode

String

Product family type code

productCode

String

Specific product code

createdAt

DateTime

Record creation timestamp

updatedAt

DateTime

Last update timestamp

Error Handling

CLIENTEDTO_NOT_FOUND

Thrown when client doesn’t exist in the database.

{
  "errors": [{
    "message": "ClienteDTO NOT_FOUND.",
    "extensions": { "code": "CLIENTEDTO_NOT_FOUND" }
  }]
}

ApiCofaseDTO_NOT_FOUND

Thrown when no Cofase record exists for the client.

{
  "errors": [{
    "message": "ApiCofaseDTO NOT_FOUND.",
    "extensions": { "code": "ApiCofaseDTO_NOT_FOUND" }
  }]
}

Logging

All Cofase API calls are logged to the ApiLog table including:

Request body
Response body
URL endpoint
User ID
Timestamps
Status (enviado/received)

Data Persistence

Cofase data is stored in the ind_ac_api_cofase database table with automatic timestamp tracking.

Example Usage

query {
  getApiCofaseByClientId(documento: "1234567890") {
    decisionTypeCode
    billedAmount
    ratingScore
    decisionDate
    deliveryStatus
    creditLimitPeriods
  }
}

Response Example

{
  "data": {
    "getApiCofaseByClientId": {
      "id": 456,
      "decisionTypeCode": "APPROVED",
      "billedAmount": 150.00,
      "ratingScore": "A2",
      "decisionDate": "2024-03-01T14:30:00Z",
      "deliveryStatus": "COMPLETED",
      "creditLimitPeriods": "12",
      "productCode": "CREDIT_REPORT_FULL",
      "createdAt": "2024-03-01T14:35:00Z",
      "updatedAt": "2024-03-01T14:35:00Z"
    }
  }
}

Configuration

Required configuration in appsettings.json:

{
  "ApiCofaseSettings": {
    "Server": "https://api.coface.com",
    "RootContextAuth": "auth",
    "RootContextCompany": "company",
    "Username": "your-username",
    "Password": "your-password",
    "Apikey": "your-api-key",
    "PolicyNumber": "your-policy-number"
  }
}

Best Practices

Token Management: Tokens expire - always check expiration and re-authenticate as needed
Error Logging: All API calls are logged for audit and debugging purposes
Cache Utilization: Use database records to avoid unnecessary API calls
Document Validation: Validate RUC format before querying Cofase
Policy Number: Ensure correct policy number is configured for your account

Authentication

Plan Comercial

Orden Compra

Anticipos

Reembolsos

Supply Management

Bitácora Cumplimiento

Activos Fijos

Catalogos

External Integrations

​Overview

​Architecture

​Authentication Flow

​Authentication Sequence

​Service Methods

​SearchCompanyByIdentifier

​Parameters

​Request Format

​Response Structure

​GetProductDetailsByDeliveryId

​Parameters

​Response Structure

​Data Models

​ApiAuthCofase

​Companies

​Product

​Address

​Repository Operations

​Create

​GetById

​Update

​GraphQL Integration

​GetApiCofaseByClientId

​Parameters

​Response Fields

​Error Handling

​CLIENTEDTO_NOT_FOUND

​ApiCofaseDTO_NOT_FOUND

​Logging

​Data Persistence

​Example Usage

​Response Example

​Configuration

​Best Practices

Overview

Architecture

Authentication Flow

Authentication Sequence

Service Methods

SearchCompanyByIdentifier

Parameters

Request Format

Response Structure

GetProductDetailsByDeliveryId

Parameters

Response Structure

Data Models

ApiAuthCofase

Companies

Product

Address

Repository Operations

Create

GetById

Update

GraphQL Integration

GetApiCofaseByClientId

Parameters

Response Fields

Error Handling

CLIENTEDTO_NOT_FOUND

ApiCofaseDTO_NOT_FOUND

Logging

Data Persistence

Example Usage

Response Example

Configuration

Best Practices