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:
- Client-Exposed Services (implemented by the
clientclient):helps us ensureServices thatwhenevertheaclienttransactionmustisimplementcompleted,towereceive webhook notifications and handle authentication - ADO Services (provided by ADO): Services that clients can
pushcalltheto retrieve validation datatowithyourimages
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
Request Parameters
Parameter Type Required Description grant_type (String):String Yes Type of HTTP authentication.authenticationusername (String):String Yes Username for token retrieval.retrievalpassword (String):String Yes Corresponding password for token retrieval.retrievalResponse:ParametersParameter Type Description access_token (String):String Issued access token.tokentoken_type (String):String Generated token type.typeexpires_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.timeHttpHTTPconsumptionRequestExample:Examplecurl -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{
}
Response
Database Push Service - Webhook (Client Implementation Required)
SERVICE PUSH DATABASEPush to Database- Description: This service
receivesmustabelistimplementedofbydocumentsthe client tobereceivesignedtransactionanddatastoresviathemwebhookinnotifications.theNote:database.This - webhook does not contain images.
HTTP Method:
POST Input Parameters:Endpoint:Request Parameters
Parameter Type Required Description JsonTransaction (JSON):JSON Yes JSON object containing transaction information in progress.progressAuthorization (String):String Yes Authentication token (in request header) .Response:CodesCode Description 200 :Process completed successfully.successfully401 :Authorization failure.failure500 :Internal server error.errorHttpHTTPconsumptionRequestExample:Examplecurl -X POST http://localhost:62859/api/Integration/Documents \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
}'
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/ExampleQuery 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"}
Response
/api/Integration/Documents
/api/token