# API REFERENCE - PUSHDATA



# 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

<table id="bkmrk-parameter-type-requi"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>grant\_type</td><td>String</td><td>Yes</td><td>Type of HTTP authentication</td></tr><tr><td>username</td><td>String</td><td>Yes</td><td>Username for token retrieval</td></tr><tr><td>password</td><td>String</td><td>Yes</td><td>Corresponding password for token retrieval</td></tr></tbody></table>

#### Response Parameters

<table id="bkmrk-parameter-type-descr"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>access\_token</td><td>String</td><td>Issued access token</td></tr><tr><td>token\_type</td><td>String</td><td>Generated token type</td></tr><tr><td>expires\_in</td><td>Integer</td><td>Token expiration time in minutes</td></tr><tr><td>.issued</td><td>String</td><td>Token issuance date and time</td></tr><tr><td>.expires</td><td>String</td><td>Token expiration date and time</td></tr></tbody></table>

#### HTTP Request Example

```bash
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

```json
{
    "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

<table id="bkmrk-parameter-type-requi-1"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>JsonTransaction</td><td>JSON</td><td>Yes</td><td>JSON object containing transaction information in progress</td></tr><tr><td>Authorization</td><td>String</td><td>Yes</td><td>Authentication token (in request header)</td></tr></tbody></table>

#### Response Codes

<table id="bkmrk-code-description-200"><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>Process completed successfully</td></tr><tr><td>401</td><td>Authorization failure</td></tr><tr><td>500</td><td>Internal server error</td></tr></tbody></table>

#### HTTP Request Example

```bash
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

<table id="bkmrk-parameter-type-requi-2"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>returnImages</td><td>Boolean</td><td>No</td><td>Whether to return images in response</td></tr><tr><td>returnDocuments</td><td>Boolean</td><td>No</td><td>Whether to return signed documents</td></tr><tr><td>returnVideoLiveness</td><td>Boolean</td><td>No</td><td>Whether to return video liveness data</td></tr></tbody></table>

#### Headers

<table id="bkmrk-header-type-required"><thead><tr><th>Header</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>accept</td><td>String</td><td>Yes</td><td>Response content type (application/json)</td></tr><tr><td>apiKey</td><td>String</td><td>Yes</td><td>API key for authentication</td></tr></tbody></table>

#### HTTP Request Example

```bash
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

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

### Extras Object Fields

<table id="bkmrk-field-type-descripti-1"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>IdState</td><td>String</td><td>State identifier</td></tr><tr><td>StateName</td><td>String</td><td>State name</td></tr></tbody></table>

### Images Array Fields

<table id="bkmrk-field-type-descripti-2"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Id</td><td>Integer</td><td>Image identifier</td></tr><tr><td>ImageTypeId</td><td>Integer</td><td>Type of image identifier</td></tr><tr><td>ImageTypeName</td><td>String</td><td>Type of image name</td></tr><tr><td>Image</td><td>String</td><td>Base64 encoded image data</td></tr><tr><td>DownloadCode</td><td>String</td><td>Download code for image</td></tr></tbody></table>

### Image Types

<table id="bkmrk-imagetypeid-imagetyp"><thead><tr><th>ImageTypeId</th><th>ImageTypeName</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>Documento de identidad cara 1</td><td>ID document side 1</td></tr><tr><td>2</td><td>Documento de identidad cara 2</td><td>ID document side 2</td></tr><tr><td>3</td><td>Fotografía del cliente</td><td>Client photograph</td></tr><tr><td>12</td><td>Fotografía facial del documento</td><td>Document facial photograph</td></tr><tr><td>13</td><td>Fotografía firma del documento</td><td>Document signature photograph</td></tr><tr><td>17</td><td>Recorte Documento de identidad cara 1</td><td>ID document side 1 crop</td></tr><tr><td>18</td><td>Recorte Documento de identidad cara 2</td><td>ID document side 2 crop</td></tr><tr><td>20</td><td>Video de Liveness</td><td>Liveness video</td></tr></tbody></table>

### SignedDocuments Array Fields

<table id="bkmrk-field-type-descripti-3"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>(Array structure depends on signed document type)</td><td>Various</td><td>Signed document information</td></tr></tbody></table>

### Scores Array Fields

<table id="bkmrk-field-type-descripti-4"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Id</td><td>Integer</td><td>Score identifier</td></tr><tr><td>UserName</td><td>String</td><td>Username who scored</td></tr><tr><td>StateName</td><td>String</td><td>State name</td></tr><tr><td>CausalRejectionName</td><td>String</td><td>Reason for rejection</td></tr><tr><td>StartingDate</td><td>DateTime</td><td>Date when scoring started</td></tr><tr><td>Observation</td><td>String</td><td>Observation notes</td></tr><tr><td>ObservationFromList</td><td>String</td><td>Observation from predefined list</td></tr></tbody></table>

### Response\_ANI Object Fields

<table id="bkmrk-field-type-descripti-5"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Niup</td><td>String</td><td>National identification number</td></tr><tr><td>FirstSurname</td><td>String</td><td>First surname</td></tr><tr><td>Particle</td><td>String</td><td>Particle (connecting word)</td></tr><tr><td>SecondSurname</td><td>String</td><td>Second surname</td></tr><tr><td>FirstName</td><td>String</td><td>First name</td></tr><tr><td>SecondName</td><td>String</td><td>Second name</td></tr><tr><td>ExpeditionMunicipality</td><td>String</td><td>Municipality where document was issued</td></tr><tr><td>ExpeditionDepartment</td><td>String</td><td>Department where document was issued</td></tr><tr><td>ExpeditionDate</td><td>String</td><td>Date when document was issued</td></tr><tr><td>CedulaState</td><td>String</td><td>ID card state code</td></tr><tr><td>CedulaStateDescription</td><td>String</td><td>ID card state description</td></tr></tbody></table>

### Parameters Object Fields

<table id="bkmrk-field-type-descripti-6"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>(Structure depends on specific parameters)</td><td>Various</td><td>Additional parameters</td></tr></tbody></table>

### StateSignatureDocument Object Fields

<table id="bkmrk-field-type-descripti-7"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>(Structure depends on signature state)</td><td>Various</td><td>Signature document state information</td></tr></tbody></table>

## Error Handling

### Common Error Responses

<table id="bkmrk-http-status-descript"><thead><tr><th>HTTP Status</th><th>Description</th><th>Response Format</th></tr></thead><tbody><tr><td>400</td><td>Bad Request</td><td>`{"error": "Invalid request parameters"}`</td></tr><tr><td>401</td><td>Unauthorized</td><td>`{"error": "Invalid or expired token"}`</td></tr><tr><td>404</td><td>Not Found</td><td>`{"error": "Resource not found"}`</td></tr><tr><td>500</td><td>Internal Server Error</td><td>`{"error": "Internal server error"}`</td></tr></tbody></table>