Service Documentation CUSTOMER EXPOSED SERVICE: "Data Push"

To make use of any of the invocations contained within this information, as well as the provided APIs, the use of a ProjectName, UrlBase, and an ApiKey requested beforehand is required.

Important Contact Information:

For technical inquiries or assistance: soporte@ado-tech.com For information about this API and other solutions in our catalog, please contact our financial area for evaluation at julian@ado-tech.com For changes that require adjustments, you can contact the financial area for validation

Note: All access keys, endpoint URLs, and other access elements will only be provided after reaching a formal agreement between both entities.

Service Overview

This connectiondocumentation covers two types of servicesservices:

exposed

Client-Exposed Services (implemented by the clientclient): helps us ensureServices that wheneverthe aclient transactionmust isimplement completed,to wereceive webhook notifications and handle authentication ADO Services (provided by ADO): Services that clients can pushcall theto retrieve validation data towith yourimages end, allowing

Client-Exposed you to maintain this information on your side.Services

To enable ADO to perform push operations on the database, theThe client must expose a RESTful web service utilizing the OAuth2 authentication method.method Thisto serviceenable shouldADO exposeto perform push operations on the followingdatabase. methods:These services include token generation and webhook data reception.

ADO Services

TokenADO Serviceprovides validation services that clients can call to retrieve complete transaction data including images when requested.

Key Differences

• Webhook (Client-Exposed): Receives transaction notifications without images

Validation Service (ADO): Returns complete transaction data with images when requested

Client-Exposed Services

Token Service (Client Implementation Required)

Description: This service issuesmust be implemented by the client to issue an OAuth2 authentication token to authorize subsequent requests to the database push service.

HTTP Method: POST

Input Parameters:Endpoint:

/api/token

Request Parameters

Parameter Type Required Description grant_type (String):String Yes Type of HTTP authentication.authentication username (String):String Yes Username for token retrieval.retrieval password (String):String Yes Corresponding password for token retrieval.retrieval Response:

Response

Parameters Parameter Type Description access_token (String):String Issued access token.token token_type (String):String Generated token type.type expires_in (Int):Integer Token expiration time in minutes.minutes .issued (String):String Token issuance date and time.time .expires (String):String Token expiration date and time.time

HttpHTTP consumptionRequest Example:Example

curl -X POST http://localhost:62859/api/token \

-H "Content-Type: application/x-www-form-urlencoded" \

-d "grant_type=password&username=admin&password=contraseña"

Request BodyResponse Example

 

{
 
    "access_token": "laK8SdjrKUAN7ja4SicUS-mL8eNWW74OTU2ZmSzjABLCGUgZknEifQkNtd5F20pBQiWvDpVwda9Bf31hB-mnzJLWmuKYY1sygHT37RQGI3Ym1HkLHwduutHwze2m9ZSBWCSV9NgOjO5Zd0Rcl9eexjFOS7cR6lOIZxxu31rLI_mHMbgtdSMAG-gToiHkgeXw6zbYjVaO1IzKMDjczyLZuvlYOfKNiJeh-3XbfjRxUy0",
 
    "token_type": "bearer",
 
    "expires_in": 59,
 
    ".issued": "Mon, 27 May 2024 20:38:24 GMT",
 
    ".expires": "Mon, 27 May 2024 20:39:24 GMT"

}

Database Push Service - Webhook (Client Implementation Required)

SERVICE PUSH DATABASE

Push to Database

Description: This service receivesmust abe listimplemented ofby documentsthe client to bereceive signedtransaction anddata storesvia themwebhook innotifications. theNote: database.This webhook does not contain images.

HTTP Method: POST

Input Parameters:Endpoint:

/api/Integration/Documents

Request Parameters

Parameter Type Required Description JsonTransaction (JSON):JSON Yes JSON object containing transaction information in progress.progress Authorization (String):String Yes Authentication token (in request header). Response:

Response

Codes Code Description 200: Process completed successfully.successfully 401: Authorization failure.failure 500: Internal server error.error

HttpHTTP consumptionRequest Example:Example

curl -X POST http://localhost:62859/api/Integration/Documents \

-H "Authorization: Bearer {token}" \

-H "Content-Type: application/json" \

-d '{
 
   "Uid":"d3a0bc78a0c344c48f1951a9e181c6b2",
 
   "StartingDate":"2024-05-05T19:43:31.968755-05:00",
 
   "CreationDate":"2024-05-05T19:43:28.0930662-05:00",
 
   "CreationIP":"127.0.0.1",
 
   "DocumentType":1,
 
   "IdNumber":"1193539722",
 
   "FirstName":"ROGER",
 
   "SecondName":"JAVIER",
 
   "FirstSurname":"DE AVILA",
 
   "SecondSurname":"ARIAS",
 
   "Gender":"M",
 
   "BirthDate":"1990-05-03T00:00:00",
 
   "PlaceBirth":"BOGOTÁ D.C. (BOGOTÁ D.C.)",
 
   "TransactionType":1,
 
   "TransactionTypeName":"Enroll",
 
   "IssueDate":"2008-05-08T00:00:00",
 
   "AdoProjectId":"126",
 
   "TransactionId":"8676",
 
   "ProductId":"1",
 
   "ComparationFacesSuccesful":false,
 
   "FaceFound":false,
 
   "FaceDocumentFrontFound":false,
 
   "BarcodeFound":false,
 
   "ResultComparationFaces":0.0,
 
   "ComparationFacesAproved":false,
 
   "Extras":{
 
      "IdState":"8676",
 
      "StateName":"Proceso satisfactorio"
 
   },
 
   "Scores":[
 
      {
 
         "Id":8676,
 
         "UserName":"Rest",
 
         "StateName":"Proceso satisfactorio",
 
         "StartingDate":"2020-08-05T19:43:31.968755-05:00",
 
         "Observation":"Calificado automáticamente - Rest_Close"
 
      }
 
   ]

}'

Validation Service (ADO Provided)

Get Validation Data

Description: This service is provided by ADO and allows clients to retrieve complete validation information for a specific transaction. Note: This service returns images when requested (returnImages=true).

HTTP Method: GET
Endpoint: /api/Example/Validation/Example

Query Parameters

Parameter Type Required Description returnImages Boolean No Whether to return images in response returnDocuments Boolean No Whether to return signed documents returnVideoLiveness Boolean No Whether to return video liveness data

Headers

Header Type Required Description accept String Yes Response content type (application/json) apiKey String Yes API key for authentication

HTTP Request Example

curl -X GET "https://adocolombia.ado-tech.com/Example/api/Example/Validation/Example?returnImages=true" \
-H "accept: application/json" \
-H "apiKey: Example" \
-H "returnDocuments: false" \
-H "returnVideoLiveness: true"

Complete Response Structure

Main Response Fields

Field Type Description Uid String Unique identifier for the transaction StartingDate DateTime Date and time when the process started CreationDate DateTime Date and time when the record was created CreationIP String IP address from which the transaction was initiated DocumentType Integer Type of document (1 = ID Card, etc.) IdNumber String Document identification number FirstName String Person's first name SecondName String Person's second name FirstSurname String Person's first surname SecondSurname String Person's second surname Gender String Person's gender (M/F) BirthDate DateTime Person's birth date Street String Street address CedulateCondition String ID card condition Spouse String Spouse information Home String Home address MaritalStatus String Marital status DateOfIdentification DateTime Date of identification DateOfDeath DateTime Date of death (if applicable) MarriageDate DateTime Marriage date Instruction String Special instructions PlaceBirth String Place of birth Nationality String Nationality MotherName String Mother's name FatherName String Father's name HouseNumber String House number Profession String Profession ExpeditionCity String City where document was issued ExpeditionDepartment String Department where document was issued BirthCity String City of birth BirthDepartment String Department of birth TransactionType Integer Type of transaction (1 = Enroll) TransactionTypeName String Name of transaction type IssueDate DateTime Date when document was issued BarcodeText String Barcode text from document OcrTextSideOne String OCR text from side one OcrTextSideTwo String OCR text from side two SideOneWrongAttempts Integer Number of wrong attempts on side one SideTwoWrongAttempts Integer Number of wrong attempts on side two FoundOnAdoAlert Boolean Whether found on ADO alert list AdoProjectId String ADO project identifier TransactionId String Transaction identifier ProductId String Product identifier ComparationFacesSuccesful Boolean Whether face comparison was successful FaceFound Boolean Whether face was found FaceDocumentFrontFound Boolean Whether face was found on document front BarcodeFound Boolean Whether barcode was found ResultComparationFaces Float Result of face comparison ResultCompareDocumentFaces Float Result of document face comparison ComparationFacesAproved Boolean Whether face comparison was approved ThresholdCompareDocumentFaces Float Threshold for document face comparison CompareFacesDocumentResult String Result of face document comparison NumberPhone String Phone number CodFingerprint String Fingerprint code ResultQRCode String QR code result DactilarCode String Dactyloscopic code ReponseControlList String Control list response Latitude String GPS latitude coordinate Longitude String GPS longitude coordinate SessionId String Session identifier CustomerIdFromClient String Customer ID from client ProcessId String Process identifier DocumentTypeFromClient Integer Document type from client IdNumberFromClient String ID number from client NotEnrolledForComparisonWithClientData Boolean Whether not enrolled for comparison ExpirationDate DateTime Expiration date

Extras Object Fields

Field Type Description IdState String State identifier StateName String State name

Images Array Fields

Field Type Description Id Integer Image identifier ImageTypeId Integer Type of image identifier ImageTypeName String Type of image name Image String Base64 encoded image data DownloadCode String Download code for image

Image Types

ImageTypeId ImageTypeName Description 1 Documento de identidad cara 1 ID document side 1 2 Documento de identidad cara 2 ID document side 2 3 Fotografía del cliente Client photograph 12 Fotografía facial del documento Document facial photograph 13 Fotografía firma del documento Document signature photograph 17 Recorte Documento de identidad cara 1 ID document side 1 crop 18 Recorte Documento de identidad cara 2 ID document side 2 crop 20 Video de Liveness Liveness video

SignedDocuments Array Fields

Field Type Description (Array structure depends on signed document type) Various Signed document information

Scores Array Fields

Field Type Description Id Integer Score identifier UserName String Username who scored StateName String State name CausalRejectionName String Reason for rejection StartingDate DateTime Date when scoring started Observation String Observation notes ObservationFromList String Observation from predefined list

Response_ANI Object Fields

Field Type Description Niup String National identification number FirstSurname String First surname Particle String Particle (connecting word) SecondSurname String Second surname FirstName String First name SecondName String Second name ExpeditionMunicipality String Municipality where document was issued ExpeditionDepartment String Department where document was issued ExpeditionDate String Date when document was issued CedulaState String ID card state code CedulaStateDescription String ID card state description

Parameters Object Fields

Field Type Description (Structure depends on specific parameters) Various Additional parameters

StateSignatureDocument Object Fields

Field Type Description (Structure depends on signature state) Various Signature document state information

Error Handling

Common Error Responses

HTTP Status Description Response Format 400 Bad Request {"error": "Invalid request parameters"} 401 Unauthorized {"error": "Invalid or expired token"} 404 Not Found {"error": "Resource not found"} 500 Internal Server Error {"error": "Internal server error"}