Paso a paso para integrar el onboarding vía API

Esta guía describe cómo integrar el flujo de onboarding de compañías utilizando la API de Conekta. El proceso incluye:

Creación de la compañía

Envío y actualización de documentos

Seguimiento del estado de verificación mediante webhooks

1. Crea una company

Crea una company a través de API de companies

curl --location --request POST 'https://api.conekta.io/companies' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx: \
--data-raw '
{
    "name": "test",
    "type_company": "owner",
    "comercial_info": {
        "website": "http://www.test.com",
        "mcc": "5812",
        "merchant_support_email": "[email protected]", 
        "merchant_support_phone": "5300000000"
    },
    "fiscal_info": {
        "business_phone": "5300000000",
        "fiscal_type": "moral"
    },
    "bank_account_info":{
        "clabe": "000000000000000000"
    }
}
'

{
    "id": "6827305a1ec60400015eb116",
    "name": "test",
    "active": false,
    "account_status": "signed_up",
    "parent_company_id": "680bf1da38716d00013543bc",
    "onboarding_status": "pending",
    "documents": [
        {
            "file_classification": "deposit_account_cover",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "cfdi",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "id_legal_representative",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "proof_of_address",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "id_legal_representative_back",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "power_of_attonery",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "constitutive_act_basic",
            "status": "pending",
            "file_name": null
        }
    ],
    "created_at": 1743712372,
    "object": "company"
}

Consulta de company

Si se necesita consultar la información de la company se puede utilizar lo siguiente API de companies

curl --location --request GET 'https://api.conekta.io/companies/:company_id' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx:

{
    "id": "6827305a1ec60400015eb116",
    "name": "test",
    "active": false,
    "account_status": "signed_up",
    "parent_company_id": "680bf1da38716d00013543bc",
    "onboarding_status": "pending",
    "documents": [
        {
            "file_classification": "deposit_account_cover",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "cfdi",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "id_legal_representative",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "proof_of_address",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "id_legal_representative_back",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "power_of_attonery",
            "status": "pending",
            "file_name": null
        },
        {
            "file_classification": "constitutive_act_basic",
            "status": "pending",
            "file_name": null
        }
    ],
    "created_at": 1743712372,
    "object": "company"
}

2. Cargar documento

Con la respuesta de la creación de la companies se devuelve los documentos necesarios para cargar se puede utilizar la siguiente API de document

curl --location --request POST 'https://api.conekta.io/companies/:company_id/document' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx: \
--data-raw '
{
    "file_classification": "cfdi",
    "content_type": "application/pdf",
    "international": false,
    "file_name": "test.pdf",
    "file_data": "file data in base64"
}
'

{
    "file_classification": "id_legal_representative",
    "file_name": "prueba3.pdf",
    "status": "uploaded"
}

Tipos de file classification

Listado de file classification con los formatos aceptados

Tipo de archivo	Descripción	Formatos aceptados
id_legal_representative	identificación oficial frente	image/jpeg image/png
id_legal_representative_back	identificación oficial atrás	image/jpeg image/png
cfdi	Prueba de situación fiscal	application/pdf
constitutive_act_basic	Acta constitutiva	application/pdf image/jpeg image/png
proof_of_address	Comprobante de domicilio del negocio	application/pdf image/jpeg image/png
power_of_attonery	Poderes de representación	application/pdf image/jpeg image/png
deposit_account_cover	Carátula de la cuenta de depósito	application/pdf image/jpeg image/png
permit_casino	Permiso ante SEGOB	application/pdf image/jpeg image/png
license_sanitation	Licencia sanitaria de COFEPRIS	application/pdf image/jpeg image/png
registration_tourism	Inscripción ante el Registro Nacional de Turismo (SECTUR)	application/pdf image/jpeg image/png

Consulta de documentos

Si se necesita consultar qué documentos que se tienen que cargar se puede utilizar lo siguiente API de documents

curl --location --request GET 'https://api.conekta.io/companies/:company_id/documents' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx:

[
    {
        "file_classification": "deposit_account_cover",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "cfdi",
        "file_name": "prueba1.pdf",
        "status": "uploaded"
    },
    {
        "file_classification": "id_legal_representative",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "proof_of_address",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "id_legal_representative_back",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "power_of_attonery",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "constitutive_act_basic",
        "file_name": "",
        "status": "pending"
    }
]

3. Recepción de webhook con resultado del onboarding

Suscríbete a los webhooks para conocer el resultado del proceso de onboarding:

company.onboarding.success

company.onboarding.failed

Ejemplos

{
    "created_at": 1747401888,
    "data":
    {
        "object":
        {
            "account_status": "signed_up",
            "active": false,
            "created_at": 1747401888,
            "documents":
            [
                {
                    "file_classification": "deposit_account_cover",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "cfdi",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "id_legal_representative",
                    "file_name": "prueba2.jpeg",
                    "status": "uploaded"
                },
                {
                    "file_classification": "proof_of_address",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "id_legal_representative_back",
                    "file_name": "prueba1.jpeg",
                    "status": "uploaded"
                },
                {
                    "file_classification": "power_of_attonery",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "constitutive_act_basic",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                }
            ],
            "id": "68273b8e1ec60400015eb147",
            "name": "test",
            "object": "company",
            "onboarding_status": "in_review",
            "parent_company_id": "680bf1da38716d00013543bc"
        }
    },
    "id": "68273ca01ec60400015eb169",
    "livemode": true,
    "object": "event",
    "type": "company.onboarding.success",
    "webhook_logs":
    [
        {
            "failed_attempts": 0,
            "id": "webhl_2xzpCZB3Mka7SeMff",
            "last_attempted_at": 0,
            "last_http_response_status": -1,
            "object": "webhook_log",
            "response_data": null,
            "url": ""
        }
    ],
    "webhook_status": "pending"
}

{
    "created_at": 1747402149,
    "data":
    {
        "object":
        {
            "account_status": "signed_up",
            "active": false,
            "created_at": 1747401888,
            "documents":
            [
                {
                    "file_classification": "deposit_account_cover",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "cfdi",
                    "file_name": "prueba1.pdf",
                    "status": "failed"
                },
                {
                    "file_classification": "id_legal_representative",
                    "file_name": "prueba1.jpeg",
                    "status": "failed"
                },
                {
                    "file_classification": "proof_of_address",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "id_legal_representative_back",
                    "file_name": "prueba1.jpeg",
                    "status": "failed"
                },
                {
                    "file_classification": "power_of_attonery",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                },
                {
                    "file_classification": "constitutive_act_basic",
                    "file_name": "prueba1.pdf",
                    "status": "uploaded"
                }
            ],
            "id": "68273d2b1ec60400015eb16f",
            "name": "test",
            "object": "company",
            "onboarding_status": "pending",
            "parent_company_id": "680bf1da38716d00013543bc"
        }
    },
    "id": "68273da51ec60400015eb182",
    "livemode": true,
    "object": "event",
    "type": "company.onboarding.failed",
    "webhook_logs":
    [
        {
            "failed_attempts": 0,
            "id": "webhl_2xzpFsrtFnVRf8ZY6",
            "last_attempted_at": 0,
            "last_http_response_status": -1,
            "object": "webhook_log",
            "response_data": null,
            "url": ""
        }
    ],
    "webhook_status": "pending"
}

4. Update document

En caso de recibir un status: failed en un documento, puedes volver a enviarlo utilizando el endpoint API de document

curl --location --request PATCH 'https://api.conekta.io/companies/:company_id/document' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx: \
--data-raw '
{
    "file_classification": "cfdi",
    "content_type": "application/pdf",
    "international": false,
    "file_name": "test.pdf",
    "file_data": "file data in base64"
}
'

{
    "file_classification": "id_legal_representative",
    "file_name": "prueba3.pdf",
    "status": "uploaded"
}

Consulta de documentos

Si se necesita consultar qué documentos que se tienen que cargar se puede utilizar lo siguiente API de documents

curl --location --request GET 'https://api.conekta.io/companies/:company_id/documents' \
--header 'Accept: application/vnd.conekta-v2.2.0+json' \
--header 'Content-Type: application/json' \
-u key_xxxxxxxxxxxxxx:

[
    {
        "file_classification": "deposit_account_cover",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "cfdi",
        "file_name": "prueba1.pdf",
        "status": "uploaded"
    },
    {
        "file_classification": "id_legal_representative",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "proof_of_address",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "id_legal_representative_back",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "power_of_attonery",
        "file_name": "",
        "status": "pending"
    },
    {
        "file_classification": "constitutive_act_basic",
        "file_name": "",
        "status": "pending"
    }
]