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 documentation covers two types of services:

1. Client-Exposed Services (implemented by the client): Services that the client must implement to receive webhook notifications and handle authentication
2. ADO Services (provided by ADO): Services that clients can call to retrieve validation data with images

Client-Exposed Services

The client must expose a RESTful web service utilizing the OAuth2 authentication method to enable ADO to perform push operations on the database. These services include token generation and webhook data reception.

ADO Services

ADO provides 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 must be implemented by the client to issue an OAuth2 authentication token to authorize subsequent requests to the database push service.

HTTP Method: POST
Endpoint: /api/token

Request Parameters

Parameter	Type	Required	Description
grant_type	String	Yes	Type of HTTP authentication
username	String	Yes	Username for token retrieval
password	String	Yes	Corresponding password for token retrieval

Response Parameters

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

HTTP Request 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"

Response 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)

Description: This service must be implemented by the client to receive transaction data via webhook notifications. Note: This webhook does not contain images.

HTTP Method: POST
Endpoint: /api/Integration/Documents

Request Parameters

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

Response Codes

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

HTTP Request 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"}